nestjs-starter: Instructions file for Claude Code

CLAUDE.md

This file gives Claude Code complete context to work in this repository without scanning source files each session.

Stack

NestJS 11 · Prisma 7 + @prisma/adapter-pg (pg Pool, no Prisma binary engine) · PostgreSQL · Redis (ioredis via CacheService) · BullMQ · JWT (passport-jwt, argon2) · nestjs-pino · nestjs-i18n · Sentry · Swagger (non-production only) · TypeScript 6 · Node ≥20

Commands

npm run dev               # nest start --watch
npm run build             # nest build → dist/
npm start                 # node dist/main
npm test                  # jest --coverage --runInBand --forceExit
npm run lint:fix          # eslint --fix
npm run format            # prettier --write
npm run db:generate       # prisma generate --config prisma/prisma.config.ts
npm run db:migrate        # prisma migrate dev
npm run db:migrate-prod   # prisma migrate deploy
npm run seed:admin        # npm run cli -- seed:admin
npm run remove:admin      # npm run cli -- remove:admin

Directory Structure

src/
├── app/
│   ├── app.module.ts           ← root module (see Module Wiring below)
│   ├── controllers/
│   │   └── health.controller.ts
│   └── enums/
│       └── app.enum.ts         ← APP_ENVIRONMENT enum
├── common/
│   ├── common.module.ts        ← imports ConfigModule + all infra; exports DatabaseModule, CacheModule
│   ├── config/                 ← registerAs() factories; never import elsewhere directly
│   │   ├── index.ts            ← barrel: [AppConfig, AuthConfig, DocConfig, RedisConfig, SeedConfig]
│   │   ├── app.config.ts       ← 'app.*' keys
│   │   ├── auth.config.ts      ← 'auth.accessToken.*' / 'auth.refreshToken.*' keys
│   │   ├── doc.config.ts       ← 'doc.*' keys
│   │   ├── redis.config.ts     ← 'redis.*' keys
│   │   └── seed.config.ts      ← 'seed.admin.*' keys
│   ├── bullmq/                 ← BullMqModule (shared Redis connection)
│   ├── cache/
│   │   ├── cache.module.ts
│   │   ├── constants/cache.constant.ts   ← REDIS_CLIENT token
│   │   └── services/cache.service.ts     ← CacheService (ioredis wrapper)
│   ├── database/
│   │   ├── database.module.ts            ← provides + exports DatabaseService, UserRepository
│   │   ├── services/database.service.ts  ← PrismaClient via PrismaPg adapter
│   │   ├── repositories/user.repository.ts
│   │   ├── interfaces/user.interface.ts  ← UserEntity, CreateUserInput, UpdateUserInput
│   │   └── enums/role.enum.ts           ← re-exports Prisma Role as UserRole
│   ├── doc/
│   │   └── decorators/
│   │       ├── doc.api-endpoint.decorator.ts  ← @ApiEndpoint (THE decorator for all methods)
│   │       ├── doc.response.decorator.ts
│   │       ├── doc.generic.decorator.ts
│   │       └── doc.paginated.decorator.ts
│   ├── logger/
│   │   └── services/logger.service.ts
│   ├── message/
│   │   └── services/message.service.ts   ← i18n resolution
│   ├── request/
│   │   ├── request.module.ts             ← registers 3 APP_GUARDs
│   │   ├── constants/request.constant.ts ← PUBLIC_ROUTE_KEY, ROLES_KEY
│   │   ├── decorators/
│   │   │   ├── auth-user.decorator.ts    ← @AuthUser()
│   │   │   ├── public.decorator.ts       ← @PublicRoute()
│   │   │   └── roles.decorator.ts        ← @AllowedRoles([...])
│   │   ├── guards/
│   │   │   ├── jwt-access.guard.ts
│   │   │   ├── jwt-refresh.guard.ts      ← used only on refresh endpoint
│   │   │   └── roles.guard.ts
│   │   └── interfaces/request.interface.ts  ← IAuthUser, IRequest
│   └── response/
│       ├── response.module.ts
│       ├── dtos/
│       │   ├── response.success.dto.ts    ← ApiSuccessResponseDto<T>
│       │   ├── response.generic.dto.ts    ← ApiGenericResponseDto
│       │   ├── response.paginated.dto.ts
│       │   └── response.error.dto.ts
│       ├── filters/response.exception.filter.ts
│       ├── interceptors/response.interceptor.ts
│       └── services/
│           ├── response.serializer.service.ts
│           └── response.sentry.service.ts
├── modules/
│   ├── auth/
│   │   ├── auth.module.ts
│   │   ├── controllers/auth.public.controller.ts
│   │   ├── dtos/
│   │   │   ├── auth.login.dto.ts    ← UserLoginDto
│   │   │   ├── auth.signup.dto.ts   ← UserCreateDto extends UserLoginDto
│   │   │   └── auth.response.dto.ts ← TokenDto, AuthResponseDto, AuthRefreshResponseDto
│   │   ├── providers/
│   │   │   ├── jwt-access.strategy.ts
│   │   │   └── jwt-refresh.strategy.ts
│   │   └── services/auth.service.ts
│   └── user/
│       ├── user.module.ts
│       ├── controllers/
│       │   ├── user.public.controller.ts  ← GET /v1/user/profile, PUT /v1/user
│       │   └── user.admin.controller.ts   ← DELETE /v1/admin/user/:id
│       ├── dtos/
│       │   ├── user.dto.ts        ← UserResponseDto, UserGetProfileResponseDto, UserUpdateProfileResponseDto
│       │   └── user.update.dto.ts ← UserUpdateDto
│       └── services/user.service.ts
├── workers/
│   ├── worker.module.ts
│   └── schedulers/midnight.scheduler.ts
└── migration/
    ├── migration.module.ts
    └── seeds/user.seed.ts