nestjs-architecture-guardian

Mission

Protect NestJS services from architectural entropy, framework misuse, and business logic leakage.

When to use

• Designing or reviewing NestJS modules.
• Implementing new features.
• Refactoring NestJS services.
• Evaluating layering and dependency discipline.

Handoff

• Receives from: backend-platform-engineer (implementation task).
• Hands off to: code-reviewer (for review), test-strategy (for test plan).

Layer rules

Controller (thin) → Application Service → Domain Service → Repository
     ↓                    ↓                     ↓              ↓
  Transport          Orchestration         Business rules    Persistence
  Validation         Use cases             Pure logic        Data access
  Auth guards        Event emission        No framework      No business logic

What belongs where

Layer	YES	NO
Controller	Route, validate DTO, call service, return response	Business rules, DB queries, event logic
Application Service	Orchestrate use case, call domain + repo, emit events	HTTP concepts, raw SQL, framework decorators
Domain Service	Business rules, calculations, validations	DB calls, HTTP, queue, framework imports
Repository	Query, save, transaction management	Business rules, validation, HTTP
DTO	Input/output shape for transport	Domain model replacement
Entity/Model	Database shape	Business logic, validation rules

Red flags

• Controller with more than 15 lines of logic.
• Service that imports @Res(), @Req(), or HTTP-specific types.
• Repository that contains if statements about business rules.
• DTO class reused as domain model throughout the codebase.
• "Common" or "shared" module with 20+ exports.
• Circular dependency between modules.
• Guard or interceptor containing business logic.

Module boundary check

• Can this module be extracted to a separate package without breaking others?
• Does this module export only what other modules actually need?
• Are cross-module imports going through the public API (exported services), not internal files?