Uncle Bob Craft: Clean Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Uncle Bob Craft: Clean Architecture is a methodology within this project dedicated to applying Robert C. Martin's architectural principles to code review and production. It focuses on maintaining clear boundaries between different levels of software and ensuring that source code dependencies point only inward toward higher-level policies. This approach is designed to produce systems that are independent of frameworks, UI, and databases, making them easier to test and maintain over time.
This system aggregates principles from Clean Architecture, Clean Code, and The Clean Coder to evaluate software structure, dependency direction, and the separation of concerns. It complements other project standards like Clean Code by providing higher-level architectural criteria for reviewing and writing code.
Sources: bundled-skills/uncle-bob-craft/SKILL.md:14-25, bundled-skills/uncle-bob-craft/README.md:3-8
The Dependency Rule
The primary axiom of Clean Architecture is the Dependency Rule. This rule states that source code dependencies must point only inward toward higher-level policies. Components in inner circles (layers) must not have any information about components in outer circles. Specifically, names declared in an outer circle must not be mentioned by the code in an inner circle, including functions, classes, and variables.
The following diagram illustrates the inward flow of dependencies across the standard architectural layers:
The diagram shows the standard layer hierarchy where all arrows point toward the core Entities.
Sources: bundled-skills/uncle-bob-craft/reference.md:11-20, bundled-skills/uncle-bob-craft/references/clean-architecture.md:5-15
Core Layers and Responsibilities
The architecture is divided into four primary layers, each with a specific responsibility and allowed dependency direction:
| Layer | Responsibility | Allowed Dependencies |
|---|---|---|
| Entities | Encapsulate Enterprise-wide business rules and core objects. | Nothing (Innermost layer). |
| Use Cases | Orchestrate the flow of data to and from entities; contain application-specific rules. | Entities. |
| Interface Adapters | Convert data from the format most convenient for use cases/entities to the format most convenient for external agencies (web, DB). | Use Cases, Entities. |
| Frameworks & Drivers | Tools like Databases and Web Frameworks; generally where the most volatile code resides. | Interface Adapters. |
Sources: bundled-skills/uncle-bob-craft/reference.md:22-29, bundled-skills/uncle-bob-craft/references/clean-architecture.md:18-35
SOLID Principles in Architecture
Within the Uncle Bob Craft framework, SOLID principles are applied specifically to manage architectural boundaries and component relationships:
- SRP (Single Responsibility Principle): A module should have one, and only one, reason to change, typically centered around a single actor.
- OCP (Open/Closed Principle): Systems should be easy to extend without requiring modification to existing core logic, achieved through the use of boundaries and abstractions.
- LSP (Liskov Substitution Principle): Architectural components must be substitutable by their subtypes or implementations to maintain stability.
- ISP (Interface Segregation Principle): Use case boundaries should use narrow, client-specific interfaces rather than depending on large, general-purpose ones.
- DIP (Dependency Inversion Principle): Code should depend on abstractions (interfaces) rather than concretions, especially when crossing a boundary from a higher-level layer to a lower-level one.
Sources: bundled-skills/uncle-bob-craft/reference.md:31-38, bundled-skills/uncle-bob-craft/references/clean-architecture.md:38-48
Component Design Principles
Components are the smallest units of deployment. The project follows Uncle Bob's criteria for component cohesion and coupling to ensure a clean structural evolution.
Cohesion Principles (REP, CCP, CRP)
These principles help decide which classes belong in which components:
- REP (Reuse/Release Equivalence Principle): The granule of reuse is the granule of release.
- CCP (Common Closure Principle): Gather into components those classes that change for the same reasons and at the same times.
- CRP (Common Reuse Principle): Don't force users of a component to depend on things they don't need.
Coupling Principles (ADP, SDP, SAP)
These principles govern the relationships between components:
- ADP (Acyclic Dependencies Principle): Allow no cycles in the component dependency graph.
- SDP (Stable Dependencies Principle): Depend in the direction of stability.
- SAP (Stable Abstractions Principle): A component should be as abstract as it is stable.
Sources: bundled-skills/uncle-bob-craft/references/clean-architecture.md:50-65, bundled-skills/uncle-bob-craft/reference.md:40-42
Data Flow and Execution
When a request enters the system, it typically passes through the layers in a structured manner. While the dependency points inward, the control flow often crosses these boundaries in the opposite direction using the Dependency Inversion Principle.
Sequence illustrating a typical data flow through architectural layers while respecting the Dependency Rule via input/output models.
Sources: bundled-skills/uncle-bob-craft/references/clean-architecture.md:68-75, bundled-skills/uncle-bob-craft/SKILL.md:120-130
Implementation Heuristics and Smells
During code reviews and development, the following "smells" indicate a violation of Clean Architecture principles:
- Rigidity: A change in the database schema forces changes in the core business entities.
- Fragility: Modifying the UI causes tests in the Use Case layer to fail.
- Immobility: Business logic is so coupled to a specific framework (e.g., Spring or Django) that it cannot be reused.
- Viscosity: It is easier to add a hack (like passing a web request object into a use case) than to follow the dependency rule.
- Needless Complexity: Introducing interfaces and factories where no boundary or variation exists.
Sources: bundled-skills/uncle-bob-craft/SKILL.md:54-65, bundled-skills/uncle-bob-craft/reference.md:118-128
Conclusion
Uncle Bob Craft: Clean Architecture provides a rigorous framework for ensuring that the project's business logic remains isolated from technical details. By adhering to the Dependency Rule and utilizing SOLID principles at an architectural level, the system remains flexible, testable, and resilient to changes in external technologies like databases or web frameworks. The ultimate goal is to keep high-level policies stable while allowing low-level details to vary as needed.
Sources: bundled-skills/uncle-bob-craft/SKILL.md:145-155, bundled-skills/software-architecture/SKILL.md:43-55