---

name: NestJS Architecture description: Module organization, Dependency Injection patterns, and Project Structure. metadata: labels: [nestjs, architecture, modularity] triggers: files: ['**/*.module.ts', 'main.ts'] keywords: [Module, forRoot, forFeature, Dependency Injection]

NestJS Architecture Standards

Priority: P0 (FOUNDATIONAL)

Core architectural patterns and dependency injection standards for scalable NestJS applications.

Core Principles

1. Modularity: Every feature must be encapsulated in its own @Module.
   • Do: users.module.ts, auth.module.ts.
   • Don't: Everything in app.module.ts.
2. Dependency Injection (DI): Invert control. Never manually instantiate classes (e.g., new Service()).
   • Use: Constructor injection constructor(private readonly service: Service).
3. Scalability: Use Feature Modules for domain logic and Core/Shared Modules for reusable utilities.

Module Configuration

Dynamic Modules

• Modern Pattern: Use ConfigurableModuleBuilder class to auto-generate forRoot/register methods properly.
• Reference: See Dynamic Module Builder Implementation for the boilerplate code.
  • Conventions:
    • forRoot: Global configurations (Db, Config).
    • register: Per-instance configurations.
    • forFeature: Extending a module with specific providers/entities.

Circular Dependencies

• Avoid: Re-architect to move shared logic to a common module.
• Constraint: If unavoidable, use forwardRef(() => ModuleName) on both sides of the import.

Advanced Providers

• Factory Providers: Use useFactory heavily for providers dependent on configuration or async operations.
• Aliasing: Use useExisting to provide backward compatibility or abstract different implementations.

Scopes & Lifecycle

• Default: Singleton. Best performance.
• Request Scope: Use Scope.REQUEST sparingly.
  • Performance Warning: Request scope bubbles up. If a Service is request-scoped, every controller injecting it becomes request-scoped, triggering re-instantiation per request (~5-10% latency overhead).
• Multi-tenancy: If request-scope is needed (e.g. Tenant ID header), use Durable Providers (durable: true) with ContextIdFactory to reuse DI sub-trees.
• Shutdown: SIGTERM doesn't trigger cleanup by default.
  • Mandatory: Call app.enableShutdownHooks() in main.ts.

Structure & Organization

• Feature Modules: Domain logic (ShopModule, AuthModule). Encapsulated.
• Shared Module: Reusable providers (DateService, MathService) exported to other modules. Stateless.
• Core Module:
  • Role: Global infrastructure setup ONE TIME (Interceptors, Filters, Loggers).
  • Rule: Import CoreModule only in AppModule.
  • Contents: APP_INTERCEPTOR, APP_FILTER, APP_GUARD providers.

Reliability & Observability

• Health Checks: Mandatory for K8s/Docker.
  • Tool: Use @nestjs/terminus. Expose /health endpoint checking DB, Cache (Redis), and Memory.
• Structured Logging:
  • Warning: Default NestJS logger is unstructured text.
  • Standard: Use nestjs-pino for JSON-formatted logs with automatic req-id correlation and request duration tracking.
  • Context: Inject Logger into services to keep traces connected.