Nestjs Clean Arch

NestJS Clean Architecture Plugin

A comprehensive development toolkit for NestJS projects following Clean Architecture. Provides guided workflows, architecture enforcement, and scaffolding automation.

Features

Component	Count	Purpose
Skills	9	Architecture guide, greenfield/brownfield/bugfix workflows, CASL, exceptions, Swagger, testing, library docs
Agents	8	Architecture reviewer, feature scaffolder, CASL advisor, API docs writer, migration manager, performance analyzer, seed generator, test generator
MCP Servers	2	Serena (code intelligence), Context7 (library docs)
Hooks	4	Session context loader, dangerous command guard, auto-format on edit, post-stop validation
Rules	5	Domain purity, use-case structure, controller thinness, presenter enforcement, migration

Installation

Option 1: Local Plugin Directory

# From your NestJS project root
cp -r path/to/nestjs-clean-arch-plugin .
# Then start Claude Code — it will auto-discover the plugin

Option 2: Agent CLI Flag

copilot --plugin-dir /path/to/nestjs-clean-arch-plugin

claude --plugin-dir /path/to/nestjs-clean-arch-plugin

Post-Install: Copy Rules

Rules are project-level configuration files. Copy them to your project's .claude/rules/ directory:

mkdir -p .claude/rules
cp nestjs-clean-arch-plugin/rules/*.md .claude/rules/

Components

Skills

nestjs-clean-architecture

Core reference guide for the architecture. Covers all 5 layers (Domain → Use Cases → Adapters → Infrastructure → Modules), naming conventions, CASL authorization, and common pitfalls.

Triggers: "how should I structure...", "which layer...", "clean architecture", "implement a feature"

greenfield-workflow

Step-by-step 12-phase workflow for building new features from scratch. Includes pre-flight checklist, decision trees, and a complete worked example (Comment entity).

Triggers: "add a new feature", "create new entity", "new resource", "greenfield"

brownfield-workflow

Impact analysis and modification workflow for safely changing existing features. Covers 6 change types (field addition, new endpoint, relation, enum, logic change, refactor).

Triggers: "add a field", "modify existing", "extend feature", "add endpoint", "brownfield"

bugfix-workflow

5-phase diagnosis methodology (Reproduce → Locate → Understand → Fix → Verify) with layer-specific debugging strategies and a catalog of common bugs.

Triggers: "fix a bug", "failing test", "not working", "error", "debug"

casl-authorization

Step-by-step guide for implementing CASL-based authorization. Covers ability interfaces, factory rules, @CheckPolicies decorator, ownership vs. role-based checks, and test mocking.

Triggers: "add authorization", "CASL", "check policies", "forbidden", "permission"

exception-handling

Guide for injecting and using the IException interface across use cases. Covers all 5 exception types, ExceptionsModule wiring, error code conventions, and test mocking patterns.

Triggers: "throw exception", "not found", "bad request", "IException", "error handling"

swagger-api-docs

OpenAPI/Swagger documentation guide. Covers custom decorators (ApiResponseType, ApiCreatedResponseType), DTO and presenter @ApiProperty rules, and pre-commit checklist.

Triggers: "swagger", "openapi", "api docs", "ApiProperty", "document endpoint"

testing-patterns

Complete testing reference. Covers use case, controller, and infrastructure tests; AAA pattern; naming conventions (inputX, mockX, actualX, expectedX); Symbol token injection; and Docker test commands.

Triggers: "write tests", "unit test", "spec file", "mock", "test pattern"

context7-mcp

Fetches up-to-date library documentation and code examples via the Context7 API. Automatically activates when asking about frameworks, libraries, or API references.

Triggers: "How do I configure NestJS...", "TypeORM query for...", "What are the Jest methods..."

---

Agents

architecture-reviewer (cyan)

Reviews code changes for Clean Architecture violations. Checks dependency direction, domain purity, naming conventions, and missing layers. Reports with severity levels (🔴 Critical / 🟡 Warning / 🔵 Info).

Usage: "Review my changes for architecture violations"

feature-scaffolder (green)

Generates all boilerplate files for a new feature/entity: domain entity, repository interface, use cases, TypeORM entity, repository implementation, DTOs, presenters, controller, module, stubs, and tests.

Usage: "Scaffold a Comment entity with content, taskId, userId fields"

casl-policy-advisor (magenta)

Designs and implements CASL authorization for new or existing entities. Reads existing ability files, adds TSubject entries and factory rules, applies @CheckPolicies, and updates tests.

Usage: "Add CASL authorization to the Comment entity"

api-docs-writer (yellow)

Audits and writes Swagger/OpenAPI documentation across DTOs, presenters, and controllers. Classifies documentation gaps, applies correct decorator ordering, and produces a before/after audit report.

Usage: "Add Swagger docs to the Comment module"

migration-manager (blue)

Manages the full TypeORM migration lifecycle: audits entity-to-migration drift, generates migration names, runs and reverts migrations inside Docker, and diagnoses failures. Enforces the immutability rule (never edit committed migrations).

Usage: "Generate a migration for the Comment entity"

performance-analyzer (red)

Scans repositories for database query anti-patterns (N+1, missing pagination, over-fetching, JS-side filtering, unstable pagination). Assigns severity levels and writes corrected TypeORM code with index recommendations.

Usage: "Analyze the Task repository for performance issues"

seed-generator (blue)

Generates database seed data using typeorm-extension. Reads existing factories and seeders to match style, creates factory and seeder files, and updates main.ts with correct dependency sequencing.

Usage: "Generate seed data for the Comment entity"

test-generator (magenta)

Discovers missing spec files by mirroring src/ against test/, then generates fully self-contained unit tests for use cases, controllers, and repositories. Follows AAA pattern, uses Symbol tokens, and covers happy and error paths.

Usage: "Generate missing tests for the Comment module"

---

MCP Servers (.mcp.json)

Server	Type	Purpose
oraios/serena	stdio	Code intelligence — semantic symbol search, references, overview, rename. Powers the architecture-reviewer and bugfix diagnosis.
context7	http	Library documentation — fetches current docs for NestJS, TypeORM, Jest, class-validator, etc. Requires CONTEXT7_API_KEY env var.

---

Hooks (hooks/hooks.json)

load-project-context (SessionStart)

Loads project context at session start: checks Docker container status (app-api), reads current Git branch and staged files, counts migration files, and prints a summary with quick-reference Docker commands.

guard-dangerous-bash (PreToolUse)

Guards against destructive Bash commands before execution:

• DENY: rm -rf targeting src/, test/, dist/
• DENY: DROP TABLE, DROP DATABASE, TRUNCATE TABLE, DROP SCHEMA public
• ASK: migration:revert, git push --force, git reset --hard

format-changed-files (PostToolUse)

Automatically runs Prettier and ESLint on files after they are created or edited. Formats .ts, .js, .json, .md files and reports lint errors.

Post-stop validation (Stop)

After Claude stops, validates that new use cases have corresponding test files and that schema-changing files include a migration reminder.

---

Rules (Copy to .claude/rules/)

Rule	Scope	Enforces
DOMAIN-PURITY.md	src/domain/**/*.ts	No framework/ORM imports in domain layer
USE-CASE-STRUCTURE.md	src/use-cases/**/*.ts	1 class, 1 execute(), Symbol injection
CONTROLLER-THIN.md	*.controller.ts	No business logic, delegate to use cases
PRESENTER-REQUIRED.md	*.controller.ts	Always wrap responses with Presenter class
DATABASE-MIGRATION.md	N/A	Migration commands and conventions

Architecture Overview

src/
├── domain/          # Pure TypeScript — no framework imports
├── use-cases/       # 1 file = 1 class = 1 execute()
├── adapters/        # Controllers, DTOs, Presenters
├── infrastructure/  # TypeORM entities, repository implementations
└── modules/         # NestJS DI wiring only

Dependencies always point inward: infrastructure → domain ← use-cases

Prerequisites

• NestJS project with TypeScript
• Docker (commands run inside app-api container)
• Node.js with Prettier and ESLint configured
• TypeORM for database layer
• uvx installed (for Serena MCP — pip install uvx)
• CONTEXT7_API_KEY environment variable set (for Context7 MCP)

License

MIT