@@ -5,6 +5,7 @@ This file provides guidance to WARP (warp.dev) when working with code in this re
55## Development Commands
66
77### Basic Development
8+
89``` bash
910# Start development server with file watching
1011npm run dev
@@ -17,6 +18,7 @@ npm run prod:docker
1718```
1819
1920### Code Quality
21+
2022``` bash
2123# Lint code
2224npm run lint
@@ -32,6 +34,7 @@ npm run format:check
3234```
3335
3436### Database Operations
37+
3538``` bash
3639# Generate new migration files from schema changes
3740npm run db:generate
@@ -44,6 +47,7 @@ npm run db:studio
4447```
4548
4649### Docker Development
50+
4751``` bash
4852# View development container logs
4953docker logs acquisitions-app-dev
@@ -61,6 +65,7 @@ docker-compose -f docker-compose.prod.yml down -v
6165```
6266
6367### Testing Database Connections
68+
6469``` bash
6570# Connect to Neon Local database directly
6671docker exec acquisitions-neon-local psql -U neon -d neondb
@@ -69,6 +74,7 @@ docker exec acquisitions-neon-local psql -U neon -d neondb
6974## Architecture Overview
7075
7176### Core Structure
77+
7278This is a Node.js/Express REST API with a layered architecture:
7379
7480- ** Routes** (` src/routes/ ` ) - Express route definitions and HTTP endpoint handlers
@@ -81,32 +87,38 @@ This is a Node.js/Express REST API with a layered architecture:
8187- ** Config** (` src/config/ ` ) - Application configuration (database, logging, security)
8288
8389### Database Architecture
90+
8491- ** ORM** : Drizzle ORM with PostgreSQL
8592- ** Provider** : Neon Database (serverless PostgreSQL)
8693- ** Development** : Uses Neon Local for ephemeral database branches
8794- ** Production** : Direct connection to Neon Cloud
8895
8996### Security Stack
97+
9098- ** Arcjet** : Bot detection, rate limiting, and shield protection
9199- ** Helmet** : HTTP security headers
92100- ** CORS** : Cross-origin resource sharing configuration
93101- ** JWT** : Authentication tokens with role-based access
94102- ** bcrypt** : Password hashing
95103
96104### Path Imports
105+
97106The project uses Node.js path imports (defined in ` package.json ` ):
107+
98108``` javascript
99109import logger from ' #config/logger.js' ;
100110import { users } from ' #models/user.model.js' ;
101111import { createUser } from ' #services/auth.service.js' ;
102112```
103113
104114### Environment Configuration
115+
105116- ` .env.development ` - Development environment (with Neon Local)
106117- ` .env.production ` - Production environment (direct Neon Cloud connection)
107118- ` .env.example ` - Template for environment variables
108119
109120### Key Features
121+
110122- User authentication (signup/signin/signout) with JWT tokens
111123- Role-based access control (admin, user, guest)
112124- Rate limiting based on user roles (admin: 20/min, user: 10/min, guest: 5/min)
@@ -115,18 +127,22 @@ import { createUser } from '#services/auth.service.js';
115127- Database migrations with Drizzle Kit
116128
117129### Docker Setup
130+
118131Two environments available:
132+
119133- ** Development** : Multi-container setup with Neon Local proxy for ephemeral databases
120134- ** Production** : Optimized single container connecting directly to Neon Cloud
121135
122136### Development Workflow
137+
1231381 . Use Docker for consistent development environment
1241392 . Neon Local creates fresh database branches for each development session
1251403 . Hot reload enabled for code changes
1261414 . Use Drizzle Studio for database inspection
1271425 . ESLint enforces code style with 2-space indentation, single quotes, and semicolons
128143
129144### API Endpoints
145+
130146- ` GET / ` - Health check endpoint
131147- ` GET /health ` - Detailed health status with uptime and memory usage
132148- ` GET /api ` - API status endpoint
@@ -139,6 +155,7 @@ Two environments available:
139155- ` DELETE /api/users/:id ` - Delete user (placeholder)
140156
141157### Database Schema
158+
142159- ** Users table** : id, name, email, password (hashed), role, created_at, updated_at
143160- Default role: "user"
144- - Supported roles: "user", "admin"
161+ - Supported roles: "user", "admin"
0 commit comments