Robert C. Martin put out his Clean Architecture post in 2012, and the whole pattern rests on one constraint: source code dependencies point only inward. Business rules shouldn’t depend on the web framework or the database, and the UI shouldn’t matter to them either.
He drew it as concentric layers. From the center out you get entities, use cases, interface adapters, and frameworks and drivers.
Those four circles are schematic. His post allows more than four and treats only the Dependency Rule as fixed.
Teams mostly reach for it on long-lived business applications, where the database and web framework change more often than the business rules do.
What Is Clean Architecture?

The idea comes from a blog post called “The Clean Architecture” that Robert C. Martin (known as Uncle Bob) published on 13 August 2012. His book Clean Architecture: A Craftsman’s Guide to Software Structure and Design followed from Pearson in September 2017.
Code gets arranged in concentric layers, and business rules end up separated from frameworks, the user interface, and the database. Source code dependencies point only inward, which is the part everything else hangs on.
It targets a recurring problem in software architecture: business logic that can’t be tested or changed without also touching the database and the web framework.
Martin didn’t invent the layering from scratch. His post names Alistair Cockburn’s hexagonal architecture and Jeffrey Palermo’s onion architecture among the designs it merges into one diagram, and it says they all share one objective, separation of concerns.
According to the post, each of those designs gives you a system that doesn’t depend on any framework and can be tested without the UI, database, or web server. It also stays independent of the UI, the database, and any external agency.
Martin’s own summary of the payoff is short. When an outer part such as the database or the web framework goes obsolete, it gets replaced with minimal fuss.
The Four Layers of Clean Architecture
Going from the inside out, Martin’s original diagram has entities, then use cases, then interface adapters, then frameworks and drivers. Policy lives in the inner layers and mechanism in the outer ones.
| Layer | Holds | Typical contents |
|---|---|---|
| Entities | Enterprise-wide business rules | Business objects, core rules |
| Use cases | Application-specific business rules | Interactors that orchestrate entities |
| Interface adapters | Format conversion for the outside world | Controllers, presenters, gateways, SQL |
| Frameworks and drivers | Tools and details | Database, web framework, glue code |
Why the layers sit in this order

The order follows rate of change.
Entities are the least likely to change when something external does. A new page flow or a security tweak should never reach them.
Use cases change when the way the application operates changes, but a new database, UI, or framework shouldn’t touch them. Interface adapters sit one ring further out and convert data between the form the use cases prefer and the form the database or the web needs.
The outermost ring is mostly glue code. Martin treats the web and the database as details that belong on the outside.
The interface adapters ring is the busiest. Martin places the whole MVC pattern of a GUI there (presenters, views, controllers), along with every line of SQL.
How many layers does clean architecture have?
Four is the diagram, not the law. Martin calls the circles schematic and allows more than four. The one thing he fixes is that source code dependencies always point inward.
Other sources reshape the layers to fit their platform. Microsoft’s architecture guide for ASP.NET Core names the pattern Clean Architecture and splits the code into Application Core, Infrastructure, and UI projects, and the eShopOnWeb reference application is organized that way. The Android Developers guide to app architecture, rebuilt in December 2021, recommends at least two layers, UI and data, with an optional domain layer for use cases or interactors.
The sources disagree on more than the count. In Android’s guide the domain layer depends on the data layer, while under Martin’s rule the dependency runs the other way: the use case layer declares the interface and the data code implements it.
A feedback issue on the dotnet/docs repository goes further. It objects that Microsoft’s page introduces layer names (Application Core, Infrastructure, UI) that aren’t part of Martin’s Clean Architecture, and that it merges hexagonal, ports-and-adapters, onion, and clean architecture under one name.
Layer names and counts vary by platform. What separates a clean architecture from a layered app that just has four folders is the direction of the dependencies.
How Does the Dependency Rule Work?

Source code dependencies can point in one direction only, inward. Code in an inner circle can’t know anything about code in an outer circle.
Inner circles are policy, outer circles are mechanism, and abstraction rises as you move toward the center. The rule holds however many circles a project draws.
Martin’s post is specific about what an inner circle can’t mention. That rules out functions and classes declared in an outer circle, along with variables or any other named entity from out there. Data formats generated by an outer framework are off limits too, and that last one catches people.
A row structure returned by a database framework looks harmless. Pass it to a use case, though, and the inner circle now depends on that framework.
A use case class that imports the web framework’s request type breaks the rule, and so does one that accepts a database row structure straight from the persistence framework. The fix is for the controller to unpack the request and hand the use case plain values, and for the gateway to convert database rows into a form the use case already uses.
One problem follows immediately. A use case still has to push results outward, and an inner circle can’t call an outer one by name.
How Data and Control Cross Layer Boundaries
Control moves outward and inward as a request is handled, but source code dependencies always point inward. The Dependency Inversion Principle reconciles the two. The inner layer declares an interface, the outer layer implements it, and only plain data structures cross the boundary.
Control flow versus source code dependency

Martin’s diagram shows the conflict. Control starts in the controller, runs through the use case, and ends in the presenter, yet every source code dependency points inward toward the use case.
The use case never calls the presenter directly. It calls an interface declared in its own circle (the use case output port), and the presenter in the outer circle implements that interface.
Martin relies on dynamic polymorphism for this, so the source code dependency opposes the flow of control at exactly the boundary and nowhere else.
Something still has to choose the real implementations at startup. That wiring is the job of dependency injection, and Microsoft’s ASP.NET Core architecture guide credits the framework’s built-in support for it as one reason this structure suits non-trivial monolithic applications.
What data crosses a boundary
Simple data structures cross boundaries, such as basic structs or simple data transfer objects. Plain function arguments work too.
Entities and database rows don’t cross. Data always arrives in the form most convenient for the inner circle, never in the form the outer framework happened to produce.
How one request travels through the layers
Take a single request and follow it in.
- The controller, in the interface adapters layer, converts the incoming web request into plain input data.
- It then calls the use case through an input port, an interface owned by the use case layer.
- The use case interactor loads what it needs through a gateway interface, also declared in the inner layer, and applies the business rules to the entities.
- The result goes to the output port, a second interface in the use case layer.
- The presenter in the outer circle implements that output port and formats the result for the view.
Every arrow in the source code of that sequence points toward the use case, while the request itself travels outward and back.
How to Structure a Project Using Clean Architecture

Give each layer its own module or project and keep the inner ones unaware of the outer ones. Then add an architecture test that fails the build when a dependency points outward. Folders named after layers don’t hold the rule by themselves.
Folder or module layout
Microsoft’s ASP.NET Core architecture guide describes the folder-only approach in a single project and names its weakness. Nothing indicates which classes in which folders should depend on which others.
Layer folders in one project are the cheapest to set up and the simplest to deploy, but there’s no mechanism that rejects a reference pointing the wrong way. One project or module per layer fixes that, because the reference graph itself shows the layers, and a module can hide everything except its public interface (Android’s modularization guide calls this strict visibility control).
In ASP.NET Core, Application Core references nothing, while Infrastructure and UI both reference Application Core. Program.cs is the composition root that wires implementations to interfaces, and the UI project sometimes needs a reference to Infrastructure for that wiring. Microsoft’s guide says to confine such references to the root.
Spring Boot’s reference documentation (version 4.1.2) requires no particular layout. Its sample is grouped by feature, with customer and order packages that each hold their own controller, service, and repository, and it points to Spring Modulith for teams that want a domain-based structure enforced.
On Android, Gradle modules carry the layers. The guide (updated March 2026) warns that too many small modules turn build complexity and boilerplate into a burden.
Enforcing the Dependency Rule
Nothing enforces the rule for free.
Code Maze’s .NET comparison (updated August 2026) says neither clean nor onion architecture checks itself, and the compiler will accept a domain project that references a database driver without complaint.
Without a check, the rule rests on code review. NetArchTest’s documentation notes that this discipline tends to break down as projects grow and developers come and go.
| Tool | Platform | What it checks |
|---|---|---|
| ArchUnit 1.5.1 | Java, bytecode analysis | Packages, classes, layers, slices, cycles, plus a built-in onion architecture check |
| NetArchTest | .NET Standard 2.0 | Namespace and type dependencies, naming, design conventions |
Both run inside an ordinary unit test framework. Put them in the same build pipeline as the other tests, so a violating commit fails like any broken test.
- Start with a single rule: no type in the inner project depends on a type in the outer project.
- Run it through the unit test framework the team already uses.
- Make a violation fail the build instead of printing a warning.
- On an existing codebase, freeze the current violations and fail only on new ones (ArchUnit’s FreezingArchRule does this).
The tools have a failure mode of their own. A rule aimed at a package that was later renamed matches zero classes and passes forever, which is why ArchUnit fails such rules by default.
Common structural mistakes

| Mistake | Symptom | Fix |
|---|---|---|
| Layer folders, no check | Any class can reference any other | Split into projects, add an architecture test |
| UI creates Infrastructure types directly | Outer layers coupled at compile time | Go through interfaces, wire only in the composition root |
| Too many tiny modules | Build and boilerplate overhead outweigh the gain | Consolidate until the overhead drops |
The first two rows follow Microsoft’s guide and the third follows Android’s modularization guide. Layer folders with no check are the failure most code reviews miss.
What Clean Architecture Makes Easier to Test and Change

Business rules can be tested without a database, web server, or UI, and the cost of replacing infrastructure stays in the outer layers. Microsoft’s guide ties the first benefit to a single fact: the application core has no dependency on infrastructure.
What can be tested without infrastructure
In a plain layered app, dependencies run top to bottom and the business logic layer depends on data access. Testing it often requires a test database (Microsoft’s guide).
When the core depends on nothing outward, the application core is covered by unit testing in isolation, while the infrastructure implementations get integration tests against real external dependencies.
Fakes stand in for infrastructure at test time. Microsoft says this typically makes tests easier to write and faster to run, and Android’s domain layer guidance recommends fake repositories for the same reason.
What changes when infrastructure changes
Palermo’s 2008 onion architecture post claims the industry has changed data access techniques at least every three years. That’s why he wanted the database outside the application core.
Under this structure, swapping persistence touches one place. The infrastructure project gets a new implementation of the same interface. The application core stays untouched, and the UI project doesn’t notice, because it only sees interfaces.
Microsoft’s guide uses a SQL Server database replaced by a cloud-based store or a web API as its example.
What the evidence shows
Published evidence is thin, and most of it is self-reported or drawn from a single project.
A November 2023 paper in Springer’s Communications in Computer and Information Science series looked at a native Android project and reports duplication falling from 4.8% to 3.5% and technical debt from 6.3% to 1.3% between two sprints. A May 2026 conference paper from Sabaragamuwa University of Sri Lanka asked 106 participants about perceived effects, and it opens by saying empirical evidence is insufficient.
NDepend’s April 2021 post is a vendor case. Separating UI code from domain code in NDepend.Core, more than 300 classes, took 8 days, with 92% test coverage catching a dozen regressions.
None of the three isolates the pattern. The Android result covers two sprints of one project, the survey measures opinion, and NDepend credits its existing layering and tests as much as the target structure.
The drop in technical debt is the strongest number, and it’s still one project.
Clean Architecture vs Hexagonal and Onion Architecture

All of them point dependencies toward the business logic. Where they differ is in how much each original text actually specifies. Hexagonal fixes only the boundary, onion also orders the rings inside the core, and clean adds named layers with use cases as explicit elements.
| Pattern | Origin | What it specifies |
|---|---|---|
| Traditional N-layer | Common default | UI, business logic, data access; compile-time dependencies run top to bottom |
| Hexagonal (Ports and Adapters) | Cockburn, January 2005 | Ports and adapters isolate the application from devices and databases; core structure left open |
| Onion | Palermo, July 2008 | All coupling toward a central domain model; ring count varies |
| Clean | Martin, 2012 | Dependency Rule, named layers, use cases as explicit elements |
Cockburn’s stated intent for hexagonal architecture is an application that users, programs, automated tests, or batch scripts can drive equally, developed and tested apart from its run-time devices and databases. Herberto Graça’s 2017 reread of the original points out that it says nothing about layers, so how to structure the code inside the hexagon is left open.
Palermo’s July 2008 post on onion architecture places the domain model at the center and puts repository interfaces in the first ring around it. The number of rings in the core varies, and UI, infrastructure, and tests sit on the edge.
Palermo himself says onion and hexagonal share one premise: externalize infrastructure and write adapter code so it never becomes tightly coupled.
Sources split on how much the remaining difference matters. Code Maze (updated August 2026) says onion arranges code by layer and clean arranges it by use case, so a new feature is a new use-case class under clean and a new method on an existing service under onion. The same article concedes that most teams could adopt either.
Microsoft’s guide lists hexagonal, ports-and-adapters, onion, and clean as names one architecture has gone by. ArchUnit ships a single onion architecture check that it describes as also covering hexagonal and ports and adapters.
Read together, the sources support treating clean versus onion as a convention choice more than an architecture choice. Code Maze’s own rule of thumb is clean when the business rules are the hard part, and onion when the layering is and the team wants fewer conventions.
When Clean Architecture Is Not Worth the Cost

Skip it for simple CRUD apps and prototypes. Small microservices and internal tools usually don’t need it either, since one well-organized project is faster to build and as maintainable. Use it when the domain has complex rules, the project will live for years, several teams share the codebase, or testability is a hard requirement. That’s the split in Milan Jovanović’s decision framework (August 2026).
Where it fails to pay off
Jovanović’s example of over-engineering is a five-endpoint CRUD API split into four projects. Prototypes and MVPs fall into the same trap, as do admin dashboards.
A small microservice that sends emails or resizes images doesn’t need four projects and a domain model, according to Jovanović.
Palermo scoped his own pattern the same way in 2008. He called it not appropriate for small websites and appropriate for long-lived business applications and applications with complex behavior.
Microsoft’s guide makes the point from the other side. Every new ASP.NET Core project starts as an all-in-one project, and the guide ties that structure’s problems to growth in size and complexity.
Pros and cons
On the plus side, business rules run under test without a database or web server (Microsoft’s guide), and infrastructure can be replaced without touching the core (Microsoft, Palermo). Jovanović adds that boundaries stay clear when several teams share one codebase.
The upfront cost is extra projects, abstractions, and mapping code, and on a simple project that cost is pure overhead. Nothing enforces the direction either, so it needs architecture tests. Use cases that only forward a call add complexity for little benefit.
That last point comes from Android’s domain layer guidance (updated March 2026). It warns that forcing every UI call through a use case adds that complexity, and advises adding use cases only when required.
Decision questions and lighter alternatives
Jovanović frames the decision as questions. Does the domain have complex business rules? Will the project live 2+ years? Do multiple teams share the codebase? Is testability a hard requirement? A yes to most of them points to clean architecture.
A yes to most of the opposite set (mostly CRUD, prototype or MVP, small focused microservice, internal tool you would replace rather than maintain) points to a simpler structure. Mixed answers lean toward starting simple.
A single project with feature folders covers small apps, prototypes, microservices, and internal tools. A simple three-layer architecture (presentation, business, data) gives you some separation with less ceremony. Vertical slice architecture organizes code by feature instead of by layer, and it suits medium-complexity apps whose features are independent.
Decide from the project, not from team habit. A team that knows clean architecture well still pays its cost on every feature.
Clean Architecture FAQ
Is clean architecture the same as Clean Code?
No. Clean Code covers how to write readable functions and classes, while clean architecture covers which project may reference which. They’re independent: a clean architecture solution can contain unreadable methods, and a single-project console app can follow Clean Code to the letter.
Does clean architecture replace MVC?
It contains MVC instead. In Microsoft’s ASP.NET Core guide, controllers, views, view models, and middleware all sit in the UI layer, the outermost ring. MVC organizes that layer, and the Dependency Rule governs how the layer relates to the core.
Does clean architecture fit domain-driven design?
Yes. Microsoft’s guide says applications that follow dependency inversion and domain-driven design principles tend to arrive at the same architecture. Its Application Core holds entities, aggregates, domain services, and domain events.
Does it make sense for mobile and other client-side apps?

In adapted form, yes. Android’s architecture guidance makes the domain layer optional and says to add it only for complex or reused logic. It also warns that its “domain layer” differs in meaning from the one in clean architecture.
Which programming languages can use clean architecture?
Any language with interfaces or an equivalent abstraction. The core defines abstractions and outer layers implement them. Documented ecosystems include C# with ASP.NET Core and Java with Spring Boot, plus Kotlin on Android. ArchUnit handles rule enforcement for Java and NetArchTest does it for .NET.
Introducing Clean Architecture Into an Existing Codebase
An existing codebase gets there one boundary at a time, starting with the domain and without a rewrite. NDepend’s April 2021 refactor treated the 60 UI-dependent classes that no other NDepend.Core code used as its first candidates.
Domain types with no framework references move into their own project first, and the architecture rule for that boundary goes in the same day. Infrastructure goes behind interfaces next, starting with types nothing else uses.
The rule comes second because it keeps the finished boundary from eroding while the next one moves.
Milan Jovanović’s trigger for starting is concrete: business logic appearing in controllers, or database code appearing in the domain. Until one of those happens, a single project organized by feature folders is enough.
This position reflects sources checked on 29 October 2026, and controlled studies showing no maintainability difference would change it.
- Claude Code PyCharm Setup: Using the Agent Inside JetBrains - November 15, 2026
- Notepad++ for Mac: Does It Exist and What to Use Instead - November 13, 2026
- What Communications Teams Should Ask Before Commissioning a Mobile App - November 12, 2026



