ClaudeForge/skill/examples/modular-backend-CLAUDE.md

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

# 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:

  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:

{
  "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

# 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

# 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)