CLAUDE.md for NestJS: 13 Rules That Make AI Write Modular, Production-Ready TypeScript

Every feature lives in its own module. No cross-module imports of services — 
use the module's exports. Shared utilities go in a SharedModule. Never import 
a repository from another module directly.

All request bodies use DTOs decorated with class-validator. No raw body access 
(req.body). ValidationPipe is global. Whitelist: true. ForbidNonWhitelisted: true.

Stack: [TypeORM / Prisma — pick one]. All DB access goes through repository 
classes injected via DI. No direct EntityManager calls in services. 
No raw SQL except in named query methods with explicit typing.

Response transformation (serialization, envelope wrapping) lives in interceptors. 
Services return domain objects. Controllers return service output directly — 
the interceptor handles the rest.

Authentication and authorization use Guards, not middleware. JwtAuthGuard is 
applied via @UseGuards(). No manual JWT decoding in controllers or services. 
CurrentUser decorator extracts user from request.

A GlobalExceptionFilter is registered in main.ts. Services throw domain 
exceptions (NotFoundException, ForbiddenException, etc.) — never format 
error responses manually. No try/catch in controllers.

All environment variables accessed through ConfigService. No direct 
process.env references outside config modules. ConfigModule is global. 
Validation schema defined with Joi or zod.

No circular dependencies between modules. Use forwardRef() only when 
genuinely unavoidable — document why. Prefer event-based decoupling 
(EventEmitter2) over circular injection.

Side effects (emails, webhooks, analytics) go through Bull queues — never 
called synchronously from request handlers. Processors live in dedicated 
processor classes, not inline in services.

All controllers decorated with @ApiTags(). All DTOs decorated with @ApiProperty(). 
@ApiResponse() on all non-200 responses. SwaggerModule configured in main.ts. 
Never skip swagger decorators on new endpoints.

Unit tests use Test.createTestingModule() with all dependencies mocked. 
E2e tests use the full application module (no mocks). Test files colocated 
with the feature module: feature.service.spec.ts, feature.e2e-spec.ts.

Use NestJS Logger class injected in each service: private readonly logger = 
new Logger(ServiceName.name). No console.log. Log context always includes 
service name. Errors logged with stack traces.

Services that hold connections implement OnModuleInit and OnModuleDestroy. 
No open handles in tests — verify with --detectOpenHandles. 
Redis, queue, and DB connections closed in onModuleDestroy.

# CLAUDE.md

## Stack
- Framework: NestJS (latest stable)
- ORM: [TypeORM / Prisma]
- Queue: Bull + Redis
- Validation: class-validator + class-transformer
- Auth: Passport + JWT

## Architecture rules
- Module boundaries are inviolable — no cross-module service imports
- All request bodies use DTOs with class-validator decorators
- ValidationPipe is global: whitelist: true, forbidNonWhitelisted: true
- Repository pattern for all DB access — no raw queries except named methods
- Response transformation lives in interceptors, not services
- Guards for auth — never middleware or manual JWT decoding
- GlobalExceptionFilter handles all errors — no try/catch in controllers
- ConfigService only — no direct process.env access
- Side effects (email, webhook, analytics) go through Bull queues
- Swagger decorators are mandatory on all controllers and DTOs
- Unit tests mock all providers; e2e tests use full module
- Logger class in every service — no console.log
- OnModuleInit/OnModuleDestroy for all connection-holding services

## File conventions
- feature/feature.module.ts
- feature/feature.controller.ts
- feature/feature.service.ts
- feature/dto/create-feature.dto.ts
- feature/entities/feature.entity.ts
- feature/feature.service.spec.ts

## What's forbidden
- Circular module dependencies (use EventEmitter2 instead)
- Raw process.env outside config modules
- console.log anywhere
- try/catch in controllers
- Direct EntityManager calls in services