--- name: nestjs-architecture description: Design NestJS module boundaries and provider ownership. Use only when structuring feature/core/shared modules, controller-service boundaries, or provider lifetime; defer JWT/security, caching, and unrelated request-pipeline recipes. metadata: triggers: files: - '**/*.module.ts' - 'main.ts' keywords: - NestFactory - Module - Controller - Injectable --- # NestJS Architecture Expert ## **Priority: P0 (CRITICAL)** Design feature modules with singleton-first providers and explicit request-pipeline choices. ## Decision Map - **Module role**: Feature Modules (Auth) vs Core (Config/DB) vs Shared (Utils). Feature owns its controllers, application services, and adapters. Shared exports stateless helpers only. - **Provider scope**: default singleton. Use request scope only for tenant context, request-local caching, or request tracking. Treat request scope as a measured exception. - **Pipeline choice**: middleware for raw HTTP concerns, guard for access decisions, pipe for validation/transforms, interceptor for cross-cutting request/response behavior, filter for error translation. ## Recipe 1. **Create bounded feature**: module + controller + application service + persistence adapter. 2. **Keep controller thin**: Thin controllers, fat services. No business in Controller. Move logic to Service. 3. **Register dependencies once**: imports for modules, providers for services, exports only for true consumers. `@InjectRepository()` dependencies need `TypeOrmModule.forFeature([...])`. 4. **Validate at edges**: DTO validation pipes for incoming data; never trust raw payloads in services. 5. **Check circular imports**: check circular dependencies with `madge`; refactor contracts first and use `forwardRef()` only as last resort. ## Verify - [ ] Feature module owns one business capability, not a mixed grab bag. - [ ] Providers are singleton unless request scope has a written reason. - [ ] Guard/pipe/interceptor/filter placement matches the request lifecycle. - [ ] Config uses `@nestjs/config` or a typed config layer, not scattered `process.env`. - [ ] Dependency Integrity: DB repositories, queues, and clients are registered in the module graph, not manually instantiated. ## Anti-Patterns - **No request scope by default**: Singleton first; justify heavier scope. - **No business logic in controllers**: Delegate orchestration to services/use cases. - **No entity leakage**: Don't return ORM entities; return DTOs or response models. - **No manual instantiation**: Use DI; never `new Service()` inside Nest code. ## References - [Framework Map](../references/framework-map.md) - [Advanced Patterns](references/advanced-patterns.md) - [Dynamic Modules](references/dynamic-module.md) ## Module-boundary checklist - Separate Feature Modules (Auth) from Core (Config/DB) and Shared (Utils); keep controllers thin and do not return ORM entities directly.