# CLAUDE.md: NestJS 11 API

## Commands
- `npm run start:dev` · `npm run test` · `npm run test:e2e` · `npm run lint` · `npm run build`

## Structure
- One module per feature: `src/<feature>/{<feature>.module.ts, .controller.ts, .service.ts, dto/, entities/}`. Generate with `npx nest g resource <feature>`.
- Controllers are thin: parse input, call a service, return a DTO. Business logic lives in services.
- Validate every input with `class-validator` DTOs and a global `ValidationPipe({ whitelist: true, forbidNonWhitelisted: true, transform: true })`.
- Config through `@nestjs/config` with a validated schema; inject `ConfigService`, never read `process.env` in services.
- Throw Nest HTTP exceptions (`NotFoundException`, ...) from services only when the service is HTTP-specific; otherwise throw domain errors and map them in an exception filter.
- Auth with guards (`@UseGuards`) and custom decorators for the current user. Don't check auth inside handlers.
- Document endpoints with `@nestjs/swagger` decorators on DTOs.
- Database access goes through the repository/ORM the project already uses (Prisma, TypeORM or Drizzle); no raw SQL strings with interpolation.

## Testing
- Unit test services with `Test.createTestingModule` and mocked providers.
- E2E tests with `supertest` against the app built from `AppModule`.

## Don't
- Don't create circular module imports; if you need `forwardRef`, restructure instead.

## Done when
Lint, unit tests, e2e tests and build all pass.