# Backend Development Guidelines This file provides guidance for backend development in this project. ## Overview Express API backend with TypeScript, PostgreSQL database, and Redis caching. RESTful API design with comprehensive error handling, testing, and security practices. ## Project Structure ``` backend/ ├── src/ │ ├── controllers/ # Route handlers │ │ ├── auth.controller.ts │ │ ├── user.controller.ts │ │ └── product.controller.ts │ ├── services/ # Business logic │ │ ├── auth.service.ts │ │ ├── user.service.ts │ │ └── product.service.ts │ ├── models/ # Database models │ │ ├── User.ts │ │ └── Product.ts │ ├── middleware/ # Express middleware │ │ ├── auth.middleware.ts │ │ ├── validation.middleware.ts │ │ └── error.middleware.ts │ ├── routes/ # Route definitions │ │ ├── auth.routes.ts │ │ ├── user.routes.ts │ │ └── product.routes.ts │ ├── utils/ # Utilities │ │ ├── logger.ts │ │ ├── validators.ts │ │ └── crypto.ts │ ├── config/ # Configuration │ │ ├── database.ts │ │ └── redis.ts │ └── index.ts # App entry point ├── tests/ │ ├── unit/ # Unit tests │ ├── integration/ # Integration tests │ └── fixtures/ # Test data ├── prisma/ │ ├── schema.prisma # Database schema │ └── migrations/ # Migration files ├── .env.example ├── package.json └── tsconfig.json ``` ## File Structure - **controllers/** - Handle HTTP requests, validate input, call services - **services/** - Business logic layer, independent of HTTP - **models/** - Database models and Prisma client usage - **middleware/** - Express middleware (auth, validation, logging, errors) - **routes/** - Route definitions mapping URLs to controllers - **utils/** - Shared utility functions (logging, validation, crypto) - **config/** - Configuration files for database, Redis, etc. - **tests/** - Unit and integration tests ## Architecture **Layer Pattern**: Controllers → Services → Models → Database **Flow**: ``` HTTP Request → Route → Middleware → Controller → Service → Model → Database ↓ Response ``` **Components**: - **Controllers**: HTTP layer, request/response handling - **Services**: Business logic, reusable across controllers - **Models**: Data access layer with Prisma ORM - **Middleware**: Cross-cutting concerns (auth, logging, validation) ## Setup & Installation ```bash # Install dependencies npm install # Set up environment variables cp .env.example .env # Edit .env with: # - DATABASE_URL (PostgreSQL connection string) # - REDIS_URL (Redis connection string) # - JWT_SECRET (secret for token signing) # - PORT (default 3000) # Start PostgreSQL and Redis (using Docker) docker-compose up -d postgres redis # Run database migrations npx prisma migrate dev # Generate Prisma client npx prisma generate # Seed database npm run seed # Start development server npm run dev ``` ## API Design ### RESTful Conventions - Use RESTful conventions for API endpoints - Implement proper HTTP status codes: - `200 OK` - Successful GET/PUT/PATCH - `201 Created` - Successful POST - `204 No Content` - Successful DELETE - `400 Bad Request` - Validation error - `401 Unauthorized` - Authentication required - `403 Forbidden` - Insufficient permissions - `404 Not Found` - Resource not found - `500 Internal Server Error` - Server error ### Versioning - Version APIs when breaking changes are needed - Format: `/api/v1/`, `/api/v2/` - Example: `/api/v1/users`, `/api/v2/users` ### Documentation - Document all endpoints with OpenAPI/Swagger - Access docs at `/api-docs` when server running - Include request/response examples - Document authentication requirements ### Naming Conventions - Use camelCase for JSON keys - Use snake_case for database columns - Use kebab-case for URL paths ## Database Operations ### Migrations - Use migrations for all schema changes - **Never edit existing migrations** - create new ones - Test migrations on copy of production data - Include both up and down migrations - Name migrations descriptively: `20250112_add_user_email_index` ### Query Optimization - Implement proper indexes for frequently queried columns - Avoid N+1 queries - use joins or batch loading with Prisma `include` - Use `EXPLAIN ANALYZE` to analyze slow queries - Paginate large result sets (max 100 items per page) ### Transactions - Use transactions for multi-step operations - Example: ```typescript await prisma.$transaction(async (tx) => { await tx.user.update({ ... }); await tx.account.create({ ... }); }); ``` ## Error Handling ### Global Error Middleware - Implement global error handling middleware - Catch all errors in one place - Log errors with context (request ID, user ID, timestamp) ### Error Response Format Return consistent error response format: ```json { "error": { "code": "VALIDATION_ERROR", "message": "User-friendly message", "details": [ { "field": "email", "message": "Invalid email format" } ] } } ``` ### Error Classes - Use custom error classes for different error types - Examples: `ValidationError`, `AuthenticationError`, `NotFoundError` - Never expose stack traces to clients in production - Log full stack traces server-side ## Testing Requirements ### Unit Tests - Write unit tests for business logic (services, utils) - Mock external dependencies (database, APIs, Redis) - Test edge cases and error conditions - Aim for 80%+ code coverage ### Integration Tests - Write integration tests for API endpoints - Test full request/response cycle - Use test database (separate from dev/prod) - Reset database state between tests ### Best Practices - Use test databases, never production - Use factories/fixtures for test data - Test authentication and authorization - Test error scenarios ```bash # Run tests npm test # All tests npm run test:unit # Unit tests only npm run test:integration # Integration tests only npm run test:coverage # With coverage report ``` ## Security Practices ### Input Validation - Validate all input data with validation middleware - Use schema validation (Joi, Zod, class-validator) - Sanitize user input to prevent XSS ### Database Security - Use parameterized queries (Prisma handles this) - Prevents SQL injection - Never concatenate user input into queries ### Authentication & Authorization - Hash passwords with bcrypt (minimum 10 rounds) - Use JWT for stateless authentication - Implement refresh token rotation - Use environment variables for secrets ### Rate Limiting - Implement rate limiting on public endpoints - Example: 100 requests per 15 minutes per IP - Protect against brute force attacks ### CORS - Implement proper CORS policies - Whitelist allowed origins - Don't use wildcard (`*`) in production ## Performance Optimization ### Caching - Implement caching for frequently accessed data - Use Redis for session storage and data caching - Cache expensive computations - Set appropriate TTL (time-to-live) ### Database - Use database connection pooling (Prisma handles this) - Optimize queries with proper indexes - Monitor slow queries - Use read replicas for heavy read workloads ### Async Operations - Use async/await for I/O operations - Never block the event loop - Use worker threads for CPU-intensive tasks - Queue background jobs with RabbitMQ/Bull ## Logging - Use structured logging (Winston, Pino) - Log levels: ERROR, WARN, INFO, DEBUG - Include context: request ID, user ID, timestamp - Never log sensitive data (passwords, tokens) - Rotate log files in production ## Common Commands ```bash # Development npm run dev # Start dev server with hot reload npm test # Run all tests npm run test:watch # Run tests in watch mode npm run lint # Run ESLint npm run format # Format code with Prettier # Database npm run migrate # Run migrations npm run migrate:rollback # Rollback last migration npm run migrate:reset # Reset database (dev only) npm run seed # Seed database with test data npx prisma studio # Open Prisma Studio (DB GUI) # Production npm run build # Build TypeScript npm start # Start production server # Debugging npm run dev:debug # Start with debugger npm run logs # View application logs ``` ## API Documentation After starting the server, access API documentation at: ``` http://localhost:3000/api-docs ``` Swagger UI provides interactive API documentation with: - All endpoints listed - Request/response schemas - Try-it-out functionality - Authentication examples --- **Context**: Backend (Node.js/Express/TypeScript/PostgreSQL) **Lines**: ~200 (Backend-specific template with native format)