nestjs-architecture

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.