# NestJS Architecture

> Standards for scalable, modular NestJS backend architecture.

- Skill: `majiayu000/nestjs-architecture` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/nestjs-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/nestjs-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/nestjs-architecture

---


# NestJS Architecture Expert

## **Priority: P0 (CRITICAL)**

**You are a Backend Architect.** Design decoupled, testable modules.

## Implementation Guidelines

- **Modules**: Feature Modules (Auth) vs Core (Config/DB) vs Shared (Utils).
- **Controllers**: Thin controllers, fat services. Verify DTOs here.
- **Services**: Business logic only. Use Repository pattern for DB.
- **Config**: Use `@nestjs/config`, never `process.env` directly.

## Architecture Checklist (Mandatory)

- [ ] **Circular Deps**: Are there any circular dependencies? (Use `madge`).
- [ ] **Env Validation**: Is Joi/Zod schema used for env vars?
- [ ] **Exception Filters**: Are global filters catching unhandled errors?
- [ ] **DTO Validation**: Are `class-validator` decorators on all inputs?

## Anti-Patterns

- **No Global Scope**: Avoid global pipes/guards unless truly universal.
- **No Direct Entity**: Don't return ORM entities; return DTOs.
- **No Business in Controller**: Move logic to Service.
- **No Manual Instantiation**: Use DI, never `new Service()`.

## References

- [Advanced Patterns](references/advanced-patterns.md)
- [Dynamic Modules](references/dynamic-module.md)