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.