clean-architecture

---
name: clean-architecture
description: Use when discussing architecture layers, the dependency rule, hexagonal/onion/screaming architecture, where business logic should live, decoupling from a database, or module boundaries and SOLID.
category: Engineering Knowledge
version: 1.0.0
tools: []
---

# 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 an outer circle. This single rule produces systems that are testable and independent of frameworks, UI, database, and any external agency. Business rules are what matter; databases, web frameworks, and delivery mechanisms are details — when details depend on policies, you can defer decisions, swap implementations, and test business logic in isolation.

## Scoring

**Goal: 10/10.** Score by how many Quick Diagnostic checks the architecture satisfies, then map to a 0-10 band: nearly all pass = **9-10** (Dependency Rule holds, business logic is framework- and DB-independent); most pass = **6-8** (core is testable but some details leak inward); few pass = **3-5** (framework or persistence dictates structure); almost none pass = **0-2** (no boundaries — business rules live in controllers and ORM models). Report the score, the failed diagnostic checks, and the specific inversion needed to fix each.

### 1. Dependency Rule and Concentric Circles

**Core concept:** Organize the architecture as concentric circles — Entities (enterprise business rules) innermost, then Use Cases (application business rules), then Interface Adapters, with Frameworks and Drivers outermost. Source code dependencies always point inward.

**Why it works:** When high-level policies don't depend on low-level details, you can swap the database, web framework, or API style without touching business logic — the system becomes resilient to the most volatile parts of the stack.

**Key insights:**
- Inner circles cannot mention outer circle names — no classes, functions, variables, or data formats from outside
- Data crossing a boundary must be in the form most convenient for the inner circle, never dictated by the outer
- Dependency Inversion (interfaces defined inward, implemented outward) is the mechanism that enforces the rule

**Code applications:**

| Context | Pattern | Example |
|---------|---------|---------|
| **Layer direction** | Inner circles define interfaces; outer implement | `UserRepository` interface in Use Cases; `PostgresUserRepository` in Adapters |
| **Data crossing** | DTOs cross boundaries, not ORM entities | Use Case returns `UserResponse` DTO, not an ActiveRecord model |

### 2. Entities and Use Cases

**Core concept:** Entities encapsulate enterprise-wide business rules — rules that would exist even without software. Use Cases contain application-specific rules that orchestrate the flow of data to and from Entities.

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

**Key insights:**
- Entities are not database rows — they are objects or pure functions encapsulating critical business rules
- Use Cases accept Request Models and return Response Models — never framework objects
- Each Use Case is a single application operation (`CreateOrder`, `ApproveExpense`)

**Code applications:**

| Context | Pattern | Example |
|---------|---------|---------|
| **Entity design** | Critical business rules, zero framework dependencies | `Order.calculateTotal()` applies tax rules; knows nothing about HTTP |
| **Request/Response** | Simple data structures cross the boundary | `CreateOrderRequest { items, customerId }` — no ORM models |

### 3. Interface Adapters and Frameworks

**Core concept:** Interface Adapters convert data between the form convenient for Use Cases/Entities and the form required by external agencies. Frameworks and Drivers are the outermost layer — glue code to the outside world.

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

**Key insights:**
- Controllers translate HTTP into Use Case input; Presenters translate Use Case output into view models
- Gateways implement repository interfaces defined by Use Cases — the inner circle defines the contract, the outer fulfills it
- Business rules never know whether data lives in SQL, NoSQL, or flat files, or that delivery is HTTP

**Code applications:**

| Context | Pattern | Example |
|---------|---------|---------|
| **Controller** | Delivery mechanism → Use Case input | `OrderController.create(req)` builds `CreateOrderRequest`, calls Interactor |
| **Presenter** | Use Case output → view model | `OrderPresenter.present(response)` formats for JSON/HTML |

### 4. Component Principles

**Core concept:** Components are the units of deployment. Three cohesion principles govern what goes inside a component; three coupling principles govern relationships between components.

**Why it works:** Poorly composed components create ripple effects where one change forces redeployment of unrelated code; the principles keep changes localized and releases independent.

**Key insights:**
- REP (Reuse/Release Equivalence): classes in a component must be versionable and releasable as a unit
- CCP (Common Closure): classes that change for the same reason at the same time belong together — SRP for components
- CRP (Common Reuse): don't force users to depend on classes they don't use

**Code applications:**

| Context | Pattern | Example |
|---------|---------|---------|
| **Component grouping** | Group classes that change together (CCP) | All order-related Use Cases in one component |
| **Breaking cycles** | Apply DIP to invert a dependency edge | Extract an interface into a new component to break the cycle |

### 5. SOLID Principles

**Core concept:** Five class-and-module-level principles — Single Responsibility, Open-Closed, Liskov Substitution, Interface Segregation, Dependency Inversion — the mid-level building blocks that make the Dependency Rule possible.

**Why it works:** Each principle addresses a specific way dependencies go wrong, preventing the rigidity, fragility, and immobility that turn codebases into legacy nightmares.

**Key insights:**
- SRP: a module has one reason to change — it serves one actor (not "does one thing")
- OCP: extend behavior by adding new code, not modifying existing code — strategy and plugin patterns
- LSP: subtypes must be usable through the base interface without the client knowing — violated by unexpected exceptions or ignored methods

**Code applications:**

| Context | Pattern | Example |
|---------|---------|---------|
| **SRP violation** | Class serves multiple actors | `Employee` handles pay (CFO), reporting (COO), persistence (CTO) |
| **OCP via strategy** | New behavior through new classes | Add `ExpressShipping` implementing `ShippingStrategy`; `Order` untouched |

### 6. Boundaries and Boundary Anatomy

**Core concept:** A boundary is a line between things that matter and things that are details, implemented through polymorphism: dependencies cross pointing inward while control flow may cross either way.

**Why it works:** Every boundary buys the option to defer a decision or swap an implementation; strategic boundary placement determines whether a system is a joy or a pain to maintain over years.

**Key insights:**
- Full boundaries use reciprocal interfaces on both sides; partial boundaries use a simpler strategy or facade
- Humble Object pattern: split boundary code into a hard-to-test part (close to the boundary) and an easy-to-test part (the logic)
- Services are not automatically architectural boundaries — a microservice with a fat shared data model is a monolith with network calls

**Code applications:**

| Context | Pattern | Example |
|---------|---------|---------|
| **Full vs. partial boundary** | Reciprocal ports, or a lone strategy | Use Case defines `PlaceOrderInput`/`PlaceOrderOutput`; simpler cases take a `ShippingStrategy` |
| **Humble Object** | Separate testable logic from infrastructure | `PresenterLogic` (testable) produces `ViewModel`; `View` (humble) renders it |

## Common Mistakes

| Mistake | Why It Fails | Fix |
|---------|-------------|-----|
| **ORM leaking into business logic** | Entities couple to the schema; DB changes rewrite business rules | Separate domain entities from persistence models; map at the adapter layer |
| **Business rules in controllers** | Untestable without HTTP; duplicated across endpoints | Move logic into Use Case Interactors; controllers only translate and delegate |
| **Framework-first architecture** | Framework dictates structure; swapping means a rewrite | Treat the framework as a plugin; structure code by business capability |
| **Circular component dependencies** | Changes ripple unpredictably; no independent releases | Apply DIP or extract a shared abstraction component |

## Quick Diagnostic

| Question | If No | Action |
|----------|-------|--------|
| Can you test business rules without DB, web server, or framework? | Rules coupled to infrastructure | Extract entities and use cases behind interfaces; mock outer layers |
| Do all source dependencies point inward? | Dependency Rule violated | Introduce boundary interfaces; invert the offending dependency |