Clean architecture

--- name: clean-architecture description: 'Structure software around the Dependency Rule: source code dependencies point inward from frameworks to use cases to entities. Use when the user mentions "architecture layers," "dependency rule," "ports and adapters," "hexagonal architecture," "use case boundary," "onion architecture," "screaming architecture," or "framework independence." Also trigger when decoupling business logic from databases or frameworks, defining module boundaries, or debating where to place business rules. Covers component principles, boundaries, and SOLID. For code quality, see clean-code. For domain modeling, see domain-driven-design.' license: MIT metadata: author: wondelai version: "1.2.0" --- # 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, databases, and any external entity. 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. Rate any architecture on a scale of 0:10 against the principles below. Report the current score and the specific improvements needed to reach 10/10. ### 1. Dependency Rule and Concentric Circles Core concept: Organize the architecture as concentric circles:Entities (enterprise business rules) at the innermost layer, followed by Use Cases (application business rules), then Interface Adapters, with Frameworks and Drivers at the outermost layer. Source code dependencies always point inward. Why it works: When high-level policies do not depend on low-level details, you can swap the database, web framework, or webAPIstyle without touching the business logic:the system becomes resilient to the most volatile parts of the stack. Key insights: - Inner circles cannot reference names from outer circles:no classes, functions, variables, or data formats from outside - Data crossing a boundary must be in the form most convenient for the inner circle; it must never be dictated by the outer circle - Dependency Inversion (interfaces defined inward, implemented outward) is the mechanism that enforces this rule - The number of circles is not fixed:four is typical; the rule remains 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 |UserRepositorys interfaces in Use Cases;PostgresUserRepositorys in Adapters | | Data crossing | DTOs cross boundaries, not ORM entities | Use Case returns aUserResponses a DTO, not an ActiveRecord model | | Dependency direction | Import arrows 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: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) allows you to 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 that encapsulate 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) - The Interactor pattern: a Use Case class implements an input boundary inte