Skip to main content
skill CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add giuseppe-trisciuoglio/developer-kit
/plugin install developer-kit-typescript@developer-kit
Open on GitHub

What 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-kit

This 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-code

3Manually: put the files in place

~/.claude/skills/clean-architecture/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/clean-architecture/

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.

clean-architecture wondelai clean-architecture — a skill that keeps business rules independent of framework and database by enforcing one rule: source code dependencies point inward. CX Codex +1 8,000installs clean-architecture codewithmukesh clean-architecture — a skill that lays out .NET code across four projects, keeps dependencies pointing inward, and shows where use case handlers belong. CX Codex +1 4,200installs clean-architecture ciembor This Claude Code skill applies clean architecture principles to decisions about separating business policy from implementation details. It activates for work on dependency direction, use cases, and application boundaries. CX Codex +1 645installs clean-architecture giuseppe-trisciuoglio Skill for designing layered Java 21+ and Spring Boot 3.5+ applications. Separates business logic from the framework by uniting Clean Architecture, Hexagonal Architecture, and Domain-Driven Design into one system. CX Codex +1 4,200installs clean-architecture pproenca clean-architecture — a skill with 42 rules from Robert C. Martin's book: it tells the agent which way dependencies should point and where layer boundaries belong. CX Codex +1 2,100installs nestjs-modular-monolith Felipe Rodrigues - github.com/felipfr nestjs-modular-monolith takes an agent from domain analysis to code: module boundaries, DDD, Clean Architecture and CQRS in a NestJS backend. CX Codex +1 353installs go-backend-clean-architecture rebyteai-template go-backend-clean-architecture scaffolds a Go backend in the current folder: Gin, MongoDB, JWT auth and Clean Architecture layers, from clone to first run. CX Codex +1 105installs android-clean-architecture affaan-m android-clean-architecture tells the agent how to split an Android or KMP project into layers: modules, dependency rules, UseCases, repositories, plus Room, SQLDelight and Ktor patterns. CX Codex +1 7,200installs architecture-patterns Seth Hobson architecture-patterns guides backend architecture with Clean Architecture, Hexagonal Architecture, and DDD. Use it when designing a service, untangling a monolith, or tracing dependency cycles. CX Codex +1 24,144installs architecture-advisor codewithmukesh architecture-advisor runs a questionnaire on domain, team and system lifetime, then recommends an architecture for your .NET project. Useful before you lay out folders. CX Codex +1 4,000installs V3 Core Implementation ruvnet V3 Core Implementation builds the claude-flow v3 core in TypeScript and hands each domain to the core-implementer subagent. CX Codex +1 1,100installs

From the same set191

The whole set →
nestjs-database-expert nestjs-database-expert — a subagent for Claude Code dedicated to database operations in NestJS, focusing on Drizzle ORM schemas, migrations, transactions, and query patterns. CX Codex ★ 372repo stars devkit.verify-skill devkit.verify-skill is a Claude Code command that checks a skill against DevKit requirements, its template, and dependencies. Run it before publishing or after edits. CX Codex +1 ★ 372repo stars aws-cloudformation-dynamodb aws-cloudformation-dynamodb — a Claude skill that supplies CloudFormation patterns for DynamoDB tables: keys, indexes, billing modes, TTL and streams. Handy when infrastructure lives in code. CX Codex +1 ★ 372repo stars devkit.java.write-unit-tests devkit.java.write-unit-tests generates JUnit 5 tests with Mockito and AssertJ assertions from a Java class path. Useful for testing Spring Boot services, controllers, and utility classes. CX Codex +1 ★ 372repo stars spring-boot-backend-development-expert spring-boot-backend-development-expert — a Claude subagent for Spring Boot work: implements REST endpoints, JPA layers and JWT security, and writes the matching tests. CX Codex ★ 372repo stars java-security-expert java-security-expert runs security audits for Java and Spring Boot applications, detects OWASP vulnerabilities, reviews OAuth2 flows, and checks compliance. CX Codex ★ 372repo stars general-code-reviewer The general-code-reviewer subagent checks code changes for bugs, security flaws, and quality problems, reporting only findings with a confidence score of at least 80. CX Codex ★ 372repo stars aws-cloudformation-vpc aws-cloudformation-vpc is a Claude Code skill with CloudFormation templates for setting up VPC infrastructure on AWS. CX Codex +1 ★ 372repo stars

Project sponsors

Companies that keep this analytics open