What is clean-architecture?

This Claude skill provides a comprehensive framework for implementing Clean Architecture principles, enabling the creation of maintainable, testable, and scalable software. It guides developers in decoupling core business logic from external frameworks, databases, and UI components through a strict dependency rule and layered structure, ensuring long-term project health and technical flexibility.

When should I use clean-architecture?

clean-architecture is useful in the following scenarios: • Initial System Design: Establishing a robust folder structure and defining clear layer boundaries for new enterprise-grade applications. • Legacy Code Refactoring: Restructuring 'Big Ball of Mud' or monolithic codebases into decoupled modules to reduce technical debt and improve maintainability. • Technology Migration: Designing applications where core business rules are independent of specific web frameworks or databases, allowing for easier infrastructure swaps. • Enhanced Testing Strategy: Implementing a structure that facilitates high-coverage unit testing of domain logic without the need for complex mocks or I/O operations.

name	clean-architecture
description	Clean Architecture principles for maintainable, testable applications. Use when designing application structure or refactoring.

Clean Architecture

Layer Structure

┌─────────────────────────────────────────────┐
│ FRAMEWORKS & DRIVERS (Web, DB, External)    │
│ ┌─────────────────────────────────────────┐ │
│ │ INTERFACE ADAPTERS (Controllers, Repos) │ │
│ │ ┌─────────────────────────────────────┐ │ │
│ │ │ APPLICATION (Use Cases)             │ │ │
│ │ │ ┌─────────────────────────────────┐ │ │ │
│ │ │ │ DOMAIN (Entities)               │ │ │ │
│ │ │ └─────────────────────────────────┘ │ │ │
│ │ └─────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────┘ │
└─────────────────────────────────────────────┘

Dependency Rule

Dependencies point inward only.

Domain knows nothing about outer layers
Use Cases know Domain, nothing else
Adapters know Use Cases + Domain
Frameworks know everything

Layers

Domain (Entities)

Business objects with behavior
Validation rules
No framework dependencies
No I/O operations

Application (Use Cases)

Orchestrates domain objects
One use case = one action
Defines repository interfaces
Input/Output DTOs

Interface Adapters

Controllers: HTTP → Use Case
Repositories: Use Case → Database
Presenters: Use Case → Response format

Frameworks & Drivers

Web framework (Express, FastAPI, Fiber)
Database clients
External APIs
Configuration

Folder Structure

src/
├── domain/
│   └── entities/
├── application/
│   ├── use-cases/
│   └── interfaces/      # Repository interfaces
├── infrastructure/
│   ├── repositories/    # Interface implementations
│   └── external/        # API clients
└── interfaces/
    ├── http/            # Controllers, routes
    └── cli/             # CLI handlers

Key Patterns

Dependency Injection

UseCase depends on RepositoryInterface (not implementation)
Controller injects concrete Repository into UseCase

Use Case Structure

1. Validate input
2. Load entities via repository
3. Execute domain logic
4. Persist via repository
5. Return output DTO

Repository Interface

Defined in: application/interfaces/
Implemented in: infrastructure/repositories/

When to Apply

Use Clean Architecture when:

Application will grow/evolve
Multiple entry points (API, CLI, queue)
Team needs clear boundaries
Testing is priority

Skip for:

Simple CRUD apps
Prototypes/MVPs
Scripts/tools

Common Mistakes

Entities depending on ORM/framework
Use cases calling HTTP directly
Business logic in controllers
Skipping the interface layer
Over-engineering simple apps

Testing Strategy

Layer	Test Type	Mocks
Domain	Unit	None
Use Cases	Unit	Repositories
Adapters	Integration	External services
E2E	System	None

When & Why to Use This Skill

Use Cases