## Architecture Rules

- Modular architecture. Every feature is a NestJS module with its own controller, service, entities, and DTOs.
- Module boundaries: modules communicate through exported services. Never import a service directly from another module — import the module and use its exported provider.
- Dependency injection everywhere. Never use `new ServiceClass()`. Let NestJS IoC container manage lifecycle.
- Controller → Service → Repository layering. Controllers handle HTTP decorators and validation. Services contain business logic. Repositories (or TypeORM EntityManager) handle database queries.
- Global modules: `ConfigModule`, `DatabaseModule`, `AuthModule` (with guards). Register as global with `@Global()` or import in `AppModule`.
- Guards for authentication and authorization. `JwtAuthGuard` globally applied via `APP_GUARD`. `@Public()` decorator exempts specific endpoints.
- Interceptors for cross-cutting concerns: logging, response transformation, caching, timeout.
- Pipes for input transformation and validation. `ValidationPipe` globally with `whitelist: true, transform: true`.
- Exception filters for error formatting. Global `HttpExceptionFilter` formats all error responses consistently.
- DTOs for every endpoint: `CreateUserDto` (input), `UpdateUserDto` (partial input), `UserResponseDto` (output with `@Exclude` on sensitive fields).

## Coding Conventions

- TypeScript strict mode. No `any`. No `@ts-ignore`.
- NestJS decorators: `@Controller()`, `@Injectable()`, `@Module()`, `@Get()`, `@Post()`, `@Body()`, `@Param()`, `@Query()`.
- Class-based: services and controllers are classes with constructor injection. No functional patterns for NestJS providers.
- DTO validation: class-validator decorators on properties. `@IsString()`, `@IsEmail()`, `@MinLength(8)`, `@IsOptional()`.
- Entity naming: PascalCase class, singular name (`User`, not `Users`). Table name auto-derived (lowercase, configurable).
- File naming: kebab-case. `user.entity.ts`, `create-user.dto.ts`, `users.service.ts`, `jwt-auth.guard.ts`.
- Module structure: every module in `src/modules/<feature>/`. Module file: `<feature>.module.ts`.
- Controller routes: plural nouns (`/users`, `/posts`). RESTful: GET for reads, POST for creates, PATCH for partial updates, DELETE for deletes.
- Service methods: `create()`, `findAll()`, `findOne()`, `update()`, `remove()` for CRUD. Custom methods for complex operations.
- Swagger decorators: `@ApiTags()`, `@ApiOperation()`, `@ApiResponse()`, `@ApiBearerAuth()` on every controller and endpoint.
- Import order: NestJS core, NestJS modules, third-party, local modules, relative imports.
- Barrel exports: each module exports through its `module.ts`. No `index.ts` barrel files.
- Async/await for all async operations. No raw Promises or callbacks.

## Error Handling

- Global exception filter: `@Catch()` catches all exceptions. Formats response as `{ statusCode, message, error, timestamp, path }`.
- NestJS built-in exceptions: `NotFoundException`, `BadRequestException`, `UnauthorizedException`, `ForbiddenException`, `ConflictException`.
- Custom exceptions: extend `HttpException` or NestJS built-in exceptions. Add error codes for machine-readable identification.
- Validation errors: `ValidationPipe` with `exceptionFactory` returns structured field-level errors.
- TypeORM errors: catch in service layer. Unique violation (code `23505`) → `ConflictException`. Foreign key violation → `BadRequestException`.
- Never throw raw `Error()` in services. Use NestJS exception classes.
- Business rule violations: create custom exceptions (`InsufficientFundsException extends BadRequestException`).
- Logging: use NestJS `Logger` service. Inject with `private readonly logger = new Logger(UsersService.name)`.
- Unhandled promise rejections: handled by NestJS built-in exception zone. No process-level handlers needed.

## Testing Conventions

- Jest with `@nestjs/testing` `Test.createTestingModule()`.
- Unit tests: test services with mocked repositories. Use `jest.fn()` or `@golevelup/ts-jest` for mock providers.
- Controller tests: test with `Test.createTestingModule()`. Mock services. Assert decorator behavior via `supertest`.
- E2E tests: `INestApplication` with real database. Test full HTTP request lifecycle.
- Test file naming: `<name>.spec.ts` co-located with source. E2E tests in `test/` directory.
- Module testing setup:

- Mock repository: `{ find: jest.fn(), findOne: jest.fn(), save: jest.fn(), create: jest.fn() }`.
- Assert patterns: `expect(result).toBeDefined()`, `expect(service.create).toHaveBeenCalledWith(dto)`.
- Test database: separate PostgreSQL. Migrate before suite. Truncate between tests.
- Coverage: 90% for services, 80% for controllers, 70% for guards and interceptors.

## Database & TypeORM Patterns

- Entity definition: `@Entity()` decorator. `@Column()` for fields. `@PrimaryGeneratedColumn('uuid')` for IDs.
- Relations: `@ManyToOne`, `@OneToMany`, `@ManyToMany` with `@JoinColumn()` and `@JoinTable()`.
- Base entity: `BaseEntity` with `id`, `createdAt`, `updatedAt`, `deletedAt` columns. All entities extend it.
- Eager loading: use `relations` option in `find()`. Specify exactly which relations: `{ relations: ['posts', 'profile'] }`.
- QueryBuilder: use for complex queries. `this.repo.createQueryBuilder('user').where(...)`.
- Migrations: auto-generate with `migration:generate`. Review generated SQL. Never use `synchronize: true` in production.
- Transactions: `this.dataSource.transaction(async (manager) => { ... })`. Pass `manager` to all operations.
- Repository custom methods: extend `Repository<Entity>` with `@Injectable()`. Register in module providers.
- Soft deletes: `@DeleteDateColumn()` on base entity. Use `softDelete()` and `restore()`. Query with `withDeleted: true`.
- Pagination: `findAndCount()` with `skip` and `take`. Return `{ items, total, page, pages }`.
- Indexes: `@Index(['email'], { unique: true })` on entity class. Composite indexes as class decorator.

## Security

- JWT auth: Passport strategy validates token. Guard globally applied. `@Public()` exempts endpoints.
- Role-based access: `@Roles('admin')` decorator + `RolesGuard`. Check user role from JWT payload.
- Helmet: `app.use(helmet())` in bootstrap. Security headers.
- CORS: `app.enableCors({ origin: allowedOrigins })`. No wildcard in production.
- Rate limiting: `@nestjs/throttler` with `ThrottlerGuard` globally applied. `@SkipThrottle()` for internal endpoints.
- Validation whitelist: `ValidationPipe({ whitelist: true, forbidNonWhitelisted: true })` strips unknown properties.
- Password: bcrypt with 12 rounds. `@Exclude()` on password field in response DTO.

## What Claude Should Never Do

- Never use `new ServiceClass()` to create service instances. NestJS dependency injection manages all providers.
- Never import a service directly from another module's internal files. Import the module, then inject the exported service.
- Never use raw Express middleware (`app.use(fn)`) for authentication, validation, or authorization. Use NestJS Guards, Pipes, and Interceptors.
- Never use `synchronize: true` in TypeORM production configuration. Use migrations exclusively.
- Never use `@Res()` decorator to access the raw Express response unless absolutely necessary (it disables NestJS interceptors).
- Never put business logic in controllers. Controllers delegate to services.
- Never skip `class-validator` decorators on DTO properties. Every field must have validation.
- Never use `any` type in TypeScript. Define proper interfaces, DTOs, and entity types.
- Never create circular module dependencies. If A imports B and B imports A, extract shared logic into a third module.
- Never use `console.log`. Use NestJS `Logger` service for structured logging.
- Never skip Swagger decorators on API endpoints. Every endpoint must be documented.

## Project-Specific Context

- [YOUR PROJECT NAME] — update with your project details
- Database: PostgreSQL via [RDS / Cloud SQL / Supabase]
- Cache: Redis via [ElastiCache / Upstash]
- Queue: Bull with Redis backend
- Deployment: Docker → [Kubernetes / ECS / Cloud Run / Railway]
- Monitoring: [Sentry] for errors, [Prometheus + Grafana] for metrics
- CI/CD: GitHub Actions → test → build → Docker push → deploy