clean-architecture · giuseppe-trisciuoglio, developer-kit-typescript — Claude Code skill for NestJS architecture
Guides Clean Architecture, DDD, and Hexagonal Architecture in NestJS/TypeScript projects. Use it to shape domain models or separate business rules from framework code.
MIT ★ 372 updated 2026-09-10
/plugin marketplace add giuseppe-trisciuoglio/developer-kit
/plugin install developer-kit-typescript@developer-kitWhat clean-architecture does
The skill lays out domain, application, and infrastructure layers, with adapters at the boundaries. It covers entities, value objects, aggregates, domain events, and repository ports. Dependencies point toward the domain, keeping business rules apart from NestJS and database code.
For the application layer, it describes use cases with DTOs and an execute method; adapters provide concrete implementations of ports. It also covers wiring dependencies through NestJS modules, enforcing invariants, and placing transactions in the application layer. Domain tests can run as plain unit tests without a NestJS testing module. That means domain entities should stay free of framework dependencies.
What it helps with
- organize a NestJS project into domain, application, and infrastructure layers
- model entities and value objects around business rules
- define repository ports and connect adapters
- move business workflows into focused use cases
- separate domain logic from NestJS and TypeORM
Example prompts for the agent
- Restructure this NestJS project with Clean Architecture and map its files to the right layers.
- Design an order domain model with an aggregate, value objects, and domain events.
- Create a use case with a repository port and a TypeORM adapter.
How to install clean-architecture
1Plugin marketplace
/plugin marketplace add giuseppe-trisciuoglio/developer-kit/plugin install developer-kit-typescript@developer-kitThis installs the whole developer-kit-typescript plugin with all its skills
2Skills CLI (Vercel)
npx skills add giuseppe-trisciuoglio/developer-kit --skill clean-architecture -a claude-code3Manually: put the files in place
~/.claude/skills/clean-architecture/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/clean-architecture/
1Skills CLI (Vercel)
npx skills add giuseppe-trisciuoglio/developer-kit --skill clean-architecture -a codex2Manually: put the files in place
.agents/skills/clean-architecture/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add giuseppe-trisciuoglio/developer-kit --skill clean-architecture -a cursor2Manually: put the files in place
.cursor/skills/clean-architecture/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install giuseppe-trisciuoglio/developer-kit plugins/developer-kit-typescript/skills/clean-architecture2Manually: put the files in place
.github/skills/clean-architecture/SKILL.md1Skills CLI (Vercel)
npx skills add giuseppe-trisciuoglio/developer-kit --skill clean-architecture -a gemini-cli2Platform CLI
gemini skills install https://github.com/giuseppe-trisciuoglio/developer-kit --path plugins/developer-kit-typescript/skills/clean-architectureManually: put the files in place
.devin/skills/clean-architecture/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about clean-architecture
How do I install clean-architecture in Claude Code?
Run /plugin marketplace add giuseppe-trisciuoglio/developer-kit, then /plugin install developer-kit-typescript@developer-kit.
What does clean-architecture do?
It guides NestJS/TypeScript implementations of Clean Architecture, DDD, and Ports & Adapters. The skill covers architectural layers, domain models, use cases, and adapters.
Should domain entities depend on NestJS?
No. The domain layer is meant to remain independent of NestJS, TypeORM, and HTTP; dependency injection belongs in the outer layers.
Source text
SKILL.md · MIT
---
name: clean-architecture
description: Provides implementation patterns for Clean Architecture, Domain-Driven Design (DDD), and Hexagonal Architecture (Ports & Adapters) in NestJS/TypeScript applications. Use when structuring complex backend systems, designing domain layers with entities/value objects/aggregates, implementing ports and adapters, creating use cases, or refactoring from anemic models to rich domain models with dependency inversion.
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---
# Clean Architecture, DDD & Hexagonal Architecture for NestJS
## Overview
This skill provides comprehensive guidance for implementing Clean Architecture, Domain-Driven Design (DDD), and Hexagonal Architecture patterns in NestJS/TypeScript applications. It covers the architectural layers, tactical patterns, and practical implementation examples for building maintainable, testable, and loosely-coupled backend systems.
## When to Use
- Architecting complex NestJS applications with long-term maintainability
- Refactoring from tightly-coupled MVC to layered architecture
- Implementing rich domain models with business logic encapsulation
- Designing testable systems with swappable infrastructure
- Creating microservices with clear bounded contexts
- Separating business rules from framework code
- Implementing event-driven architectures with domain events
## Instructions
### 1. Understand the Architectural Layers
Clean Architecture organizes code into concentric layers where dependencies flow inward. Inner layers have no knowledge of outer layers:
```
+-------------------------------------+
| Infrastructure (Frameworks, DB) | Outer layer - volatile
+-------------------------------------+
| Adapters (Controllers, Repositories)| Interface adapters
+-------------------------------------+
| Application (Use Cases) | Business rules
+-------------------------------------+
| Domain (Entities, Value Objects) | Core - most stable
+-------------------------------------+
```
The Hexagonal Architecture (Ports & Adapters) pattern complements this:
- **Ports**: Interfaces defining what the application needs
- **Adapters**: Concrete implementations of ports
- **Domain Core**: Pure business logic with zero dependencies
### 2. Learn DDD Tactical Patterns
Apply these patterns in your domain layer:
- **Entities**: Objects with identity and lifecycle
- **Value Objects**: Immutable, defined by attributes
- **Aggregates**: Consistency boundaries with aggregate roots
- **Domain Events**: Capture state changes
- **Repositories**: Abstract data access for aggregates
### 3. Organize Your Project Structure
Structure your NestJS project following Clean Architecture principles:
```
src/
+-- domain/ # Inner layer - no external deps
| +-- entities/ # Domain entities
| +-- value-objects/ # Immutable value objects
| +-- aggregates/ # Aggregate roots
| +-- events/ # Domain events
| +-- repositories/ # Repository interfaces (ports)
| +-- services/ # Domain services
+-- application/ # Use cases - orchestration
| +-- use-cases/ # Individual use cases
| +-- ports/ # Input/output ports
| +-- dto/ # Application DTOs
| +-- services/ # Application services
+-- infrastructure/ # External concerns
| +-- database/ # ORM config, migrations
| +-- http/ # HTTP clients
| +-- messaging/ # Message queues
+-- adapters/ # Interface adapters
+-- http/ # Controllers, presenters
+-- persistence/ # Repository implementations
+-- external/ # External service adapters
```
### 4. Implement the Domain Layer
Create pure domain objects with no external dependencies:
1. **Value Objects**: Immutable objects validated at construction
2. **Entities**: Objects with identity containing business logic
3. **Aggregates**: Consistency boundaries protecting invariants
4. **Repository Ports**: Interfaces defining data access contracts
### 5. Implement the Application Layer
Create use cases that orchestrate business logic:
1. Define input/output DTOs for each use case
2. Inject repository ports via constructor
3. Implement business workflows in the `execute` method
4. Keep use cases focused on a single responsibility
### 6. Implement Adapters
Create concrete implementations of ports:
1. **Persistence Adapters**: Map domain objects to/from ORM entities
2. **HTTP Adapters**: Controllers that transform requests to use case inputs
3. **External Service Adapters**: Integrate with third-party services
### 7. Configure Dependency Injection
Wire everything together in NestJS modules:
1. Register use cases as providers
2. Provide repository implementations using interface tokens
3. Import required infrastructure modules (TypeORM, etc.)
### 8. Apply Best Practices
Follow these principles throughout implementation:
1. **Dependency Rule**: Dependencies only point inward. Domain knows nothing about NestJS, TypeORM, or HTTP.
2. **Rich Domain Models**: Put business logic in entities, not services. Avoid anemic domain models.
3. **Immutability**: Value objects must be immutable. Create new instances instead of modifying.
4. **Interface Segregation**: Keep repository interfaces small and focused.
5. **Constructor Injection**: Use NestJS DI in outer layers only. Domain entities use plain constructors.
6. **Validation**: Validate at boundaries (DTOs) and enforce invariants in domain.
7. **Testing**: Domain layer tests require no NestJS testing module - pure unit tests.
8. **Transactions**: Keep transactions in the application layer, not domain.
## Examples
For detailed code examples covering all aspects of Clean Architecture implementation, see:
- **[references/examples.md](references/examples.md)** - Complete examples including:
- Value Objects (Email, Money)
- Entities with Business Logic (OrderItem)
- Aggregate Roots with Domain Events (Order)
- Repository Ports (Interfaces)
- Use Cases (Application Layer)
- Repository Adapters (Infrastructure)
- Controller Adapters (HTTP)
- Module Configuration (DI setup)
## Best Practices
For comprehensive guidance on Clean Architecture best practices, including:
- **Core Principles**: Dependency Rule, Rich Domain Models, Immutability, Interface Segregation
- **Testing Strategies**: Unit testing domain, integration testing application, E2E testing adapters
- **Performance Considerations**: Aggregate design, caching strategy, lazy loading
See **[references/best-practices.md](references/best-practices.md)**
## Constraints and Warnings
Important constraints, common pitfalls, and implementation warnings:
- **Architecture Constraints**: Dependency rule violations, domain purity requirements, interface location rules
- **Common Pitfalls**: Leaky abstractions, anemic domain models, wrong layer dependencies, missing ports
- **Implementation Warnings**: Mapping overhead, learning curve, boilerplate code, transaction boundaries
- **Performance Considerations**: Aggregate size, database queries, caching strategies
See **[references/constraints.md](references/constraints.md)**
## Quick Start
1. Read the architectural layers overview above
2. Review the [examples.md](references/examples.md) for implementation patterns
3. Study [best-practices.md](references/best-practices.md) for core principles
4. Check [constraints.md](references/constraints.md) to avoid common pitfalls
5. Start implementing your domain layer with pure TypeScript classes
6. Add application layer use cases to orchestrate business logic
7. Implement adapters for infrastructure concerns
8. Configure dependency injection in NestJS modules
## References
- `references/examples.md` - Complete code examples for all layers
- `references/best-practices.md` - Comprehensive best practices and principles
- `references/constraints.md` - Constraints, pitfalls, and warnings
© Giuseppe Trisciuoglio · MIT · giuseppe-trisciuoglio/developer-kit
Similar skills
All skills for Backend and APIs →clean-architecture by other authors comes first.