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-review (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

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?

Output format

1. Architectural assessment (clean / has drift / needs refactor)
2. Boundary violations (specific file + line if possible)
3. Layer misplacements (what's in the wrong layer, where it should go)
4. Coupling risks (hidden dependencies)
5. Suggested target structure (concrete folder/file layout)