clean-architecture

What this skill does

# Clean Architecture Framework

A disciplined approach to structuring software so that business rules remain independent of frameworks, databases, and delivery mechanisms. Apply these principles when designing system architecture, reviewing module boundaries, or advising on dependency management.

## Core Principle

**Source code dependencies must point inward -- toward higher-level policies.** Nothing in an inner circle can know anything about something in an outer circle. This single rule, applied consistently, produces systems that are testable, independent of frameworks, independent of the UI, independent of the database, and independent of any external agency.

**The foundation:** Software architecture is about drawing lines -- boundaries -- that separate things that matter from things that are details. Business rules are what matter. Databases, web frameworks, and delivery mechanisms are details. When details depend on policies (not the other way around), you can defer decisions, swap implementations, and test business logic in isolation.

## Scoring

**Goal: 10/10.** When reviewing or creating software architecture, rate it 0-10 based on adherence to the principles below. A 10/10 means full alignment with all guidelines; lower scores indicate gaps to address. Always provide the current score and specific improvements needed to reach 10/10.

## The Clean Architecture Framework

Six principles for building systems that survive the passage of time:

### 1. Dependency Rule and Concentric Circles

**Core concept:** The architecture is organized as concentric circles. The innermost circle contains Entities (enterprise business rules). The next circle contains Use Cases (application business rules). Then Interface Adapters. The outermost circle contains Frameworks and Drivers. Source code dependencies always point inward.

**Why it works:** When high-level policies don't depend on low-level details, you can change the database from MySQL to MongoDB, swap a web framework, or replace a REST API with GraphQL -- all without touching business logic. The system becomes resilient to the most volatile parts of the technology stack.

**Key insights:**
- The Dependency Rule is the overriding rule: inner circles cannot mention outer circle names (classes, functions, variables, data formats)
- Data that crosses boundaries must be in a form convenient for the inner circle, never in a form dictated by the outer circle
- Dependency Inversion (interfaces defined inward, implemented outward) is the mechanism that enforces the rule
- The number of circles is not fixed -- four is typical, but you may have more; the rule stays the same
- Frameworks are details, not architecture -- they belong in the outermost circle

**Code applications:**

| Context | Pattern | Example |
|---------|---------|---------|
| **Layer direction** | Inner circles define interfaces; outer circles implement them | `UserRepository` interface in Use Cases; `PostgresUserRepository` in Adapters |
| **Data crossing** | DTOs or simple structs cross boundaries, not ORM entities | Use Case returns `UserResponse` DTO, not an ActiveRecord model |
| **Framework isolation** | Wrap framework calls behind interfaces | `EmailSender` interface hides whether you use SendGrid or SES |
| **Database independence** | Repository pattern abstracts persistence | Business logic calls `repo.save(user)`, never raw SQL |
| **Dependency direction** | Import arrows on a diagram always point inward | Controller imports Use Case; Use Case never imports Controller |

See: [references/dependency-rule.md](references/dependency-rule.md)

### 2. Entities and Use Cases

**Core concept:** Entities encapsulate enterprise-wide business rules -- the most general, highest-level rules that would exist even if no software system existed. Use Cases contain application-specific business rules that orchestrate the flow of data to and from Entities.

**Why it works:** By separating what the business does (Entities) from how the application orchestrates it (Use Cases), you can reuse Entities across multiple applications and change application behavior without altering core business rules.

**Key insights:**
- Entities are not database rows -- they are objects (or pure functions) that encapsulate critical business rules and data
- Use Cases describe application-specific automation rules; they orchestrate Entities but do not contain enterprise logic
- Use Cases accept Request Models and return Response Models -- never framework objects
- Each Use Case represents a single application operation (e.g., `CreateOrder`, `ApproveExpense`)
- The Interactor pattern: a Use Case class implements an input boundary interface and calls an output boundary interface
- Changes to a Use Case should never affect an Entity; changes to an Entity may require Use Case updates

**Code applications:**

| Context | Pattern | Example |
|---------|---------|---------|
| **Entity design** | Encapsulate critical business rules with no framework dependencies | `Order.calculateTotal()` applies tax rules; knows nothing about HTTP |
| **Use Case boundary** | Define Input Port and Output Port interfaces | `CreateOrderInput` interface; `CreateOrderOutput` interface |
| **Request/Response** | Simple data structures cross the boundary | `CreateOrderRequest { items, customerId }` -- no ORM models |
| **Single responsibility** | One Use Case per application operation | `PlaceOrder`, `CancelOrder`, `RefundOrder` as separate classes |
| **Interactor** | Use Case class implements Input Port, calls Output Port | `PlaceOrderInteractor implements PlaceOrderInput` |

See: [references/entities-use-cases.md](references/entities-use-cases.md)

### 3. Interface Adapters and Frameworks

**Core concept:** Interface Adapters convert data between the format most convenient for Use Cases and Entities and the format required by external agencies (database, web, devices). Frameworks and Drivers are the outermost layer -- glue code that connects to the outside world.

**Why it works:** When the web framework, ORM, or message queue is confined to the outermost circles, replacing any of them becomes a localized change. The database is a detail. The web is a detail. The framework is a detail. Details should be plugins to your business rules, not the skeleton of your application.

**Key insights:**
- Controllers translate HTTP requests into Use Case input; Presenters translate Use Case output into view models
- Gateways implement repository interfaces defined by Use Cases -- the Use Case defines the contract, the gateway fulfills it
- The database is a detail: business rules don't need to know whether data is stored in SQL, NoSQL, or flat files
- The web is a detail: business rules don't know they're being delivered over HTTP
- Treat frameworks with suspicion -- they want you to couple to them; keep them at arm's length
- Plugin architecture: the system should be structured so that frameworks plug into business rules, not the reverse

**Code applications:**

| Context | Pattern | Example |
|---------|---------|---------|
| **Controller** | Translates delivery mechanism to Use Case input | `OrderController.create(req)` builds `CreateOrderRequest` and calls Interactor |
| **Presenter** | Translates Use Case output to view model | `OrderPresenter.present(response)` formats data for JSON/HTML |
| **Gateway** | Implements repository interface using a specific DB | `SqlOrderRepository implements OrderRepository` |
| **Framework boundary** | Framework code calls inward, never called by inner circles | Express route handler calls Controller; Controller never imports Express |
| **Plugin architecture** | Main component wires dependencies at startup | `main()` instantiates concrete classes and injects them |

See: [references/adapters-frameworks.md](references/adapters-frameworks.md)

### 4. Component Principles

**Core concept:** Components are the units of deployment. Three cohesion principles govern what goes i