Clean Architecture
Organise code into concentric dependency rings so business logic never depends on frameworks, databases, or UI.
★★★★★5/5Inside a codebase — classes, modules, files
Interactive visualization
LiveThe Dependency Rule
Source-code dependencies must always point inward. Nothing in an inner circle can know about something in an outer circle — not a function name, class, variable, or framework type.
Click any ring to explore its responsibility.
Click any concentric ring to explore its role and responsibilities.
How it works
Clean Architecture, introduced by Robert C. Martin (Uncle Bob), arranges code into four concentric layers: Entities, Use Cases, Interface Adapters, and Frameworks & Drivers. The Dependency Rule is absolute — source-code dependencies must always point inward. Nothing in an inner layer knows anything about an outer layer.
Entities encapsulate enterprise-wide business rules. Use Cases orchestrate data flow to and from Entities. Interface Adapters convert data between Use Cases and delivery mechanisms. Frameworks & Drivers are the outermost circle: databases, web frameworks, and external APIs.
This separation lets you swap a REST API for gRPC, replace a SQL database with a NoSQL one, or test Use Cases without spinning up a web server.
Why it matters
Most software rot starts when business rules leak into framework code. Clean Architecture keeps the core testable, portable, and framework-independent — critical as systems grow.
✓ When to use
- →Long-lived products where frameworks and databases may change
- →Teams where different layers are owned by different groups
- →When comprehensive unit testing of business logic is required
- →Monoliths that may need to be decomposed into microservices later
✗ When NOT to use
- →Small scripts or one-off tools
- →Prototype / MVP with tight deadlines
- →Simple CRUD apps with no meaningful business logic
Trade-offs
Business logic is framework-independent and highly testable
More initial boilerplate and indirection
Replacing databases or frameworks is safe and isolated
Over-engineering risk for simple domains
Clear ownership boundaries between teams
Learning curve for developers new to the pattern
In production
Recommendation engine core logic isolated from delivery infrastructure
Checkout domain isolated from payment gateway providers
Fare calculation engine independent of platform and persistence layers
Industry adoption
Related principles
Layered (N-Tier) Architecture
LiveOrganise code into horizontal layers (Presentation, Business Logic, Data Access) where each layer only calls the one below it.
Domain-Driven Design
Model software around the core business domain using a shared language between developers and domain experts.
Hexagonal Architecture
Place the domain at the centre and connect all I/O (HTTP, database, messaging) through explicit ports and adapters — so the core is framework-free and infinitely testable.
CQRS
LiveSeparate the model used to read data (Query) from the model used to write data (Command) — each optimised independently.