Clean architecture arrives in a team as a diagram, concentric circles with entities at the center and frameworks at the edge, and the diagram is usually met with one of two reactions that are both wrong. The enthusiast implements the full ceremony in a CRUD application, six interfaces between the database and the controller, and the team spends its velocity on mapping layers nobody needed. The skeptic declares it enterprise theater, writes the ORM entities directly into the HTTP handlers, and the team spends the third year unable to change anything without breaking everything. The mature position sits between the reactions, the dependency rule is the valuable core, and the ceremony is a dial the team sets per module based on what the module actually risks. This article builds that position, the rule and why it pays, the pragmatic layering that keeps small systems honest, and the signals that tell a team when to turn the dial up.
The dependency rule as the one idea worth the whole pattern
The pattern's many diagrams reduce to one rule, and the rule is directional. Source code dependencies point inward. The entities, the business rules and the use cases, depend on nothing. The adapters, the database, the HTTP layer, the message queues, depend on the use cases. The use cases never depend on the adapters, never import the ORM types, never see the HTTP request, and the consequence is the whole point, the business logic is testable without the infrastructure and replaceable underneath without touching the logic:
# domain/order.py
class Order:
def __init__(self, items):
self.items = items
def total_with_shipping(self):
return sum(i.price for i in self.items) + self.shipping_for(self.subtotal())
# usecase/place_order.py
class PlaceOrder:
def __init__(self, orders, payment): # ports, interfaces
self.orders = orders
self.payment = payment
def execute(self, command):
order = Order(command.items)
self.payment.charge(order.total_with_shipping())
self.orders.save(order)The use case names its dependencies as interfaces, a repository and a payment port, and the concrete adapters, the ORM repository, the payment provider client, are injected from outside. The unit test constructs the use case with fakes in five lines, and the third year's migration to a new payment provider touches the adapter and the composition root, never the use case. That is the entire value proposition, dependencies that point the way change flows, and every layer, wrapper and naming convention in the pattern's literature exists to serve that one rule or is cargo.
The maintenance payoff that arrives in year three
The pattern's costs are paid monthly and its benefits arrive as avoided catastrophes, which is why the debate is eternal, the costs are visible and the benefits are counterfactual. The visible costs are the mapping layers, the domain model to the persistence model to the transport model, the interface indirections, and the ceremony in a codebase of five entities is genuinely absurd. What the third year buys with those costs is observable in the changes that hurt. The payment provider migration touches the adapter and the wiring. The ORM upgrade touches the repositories. The API redesign touches the transport layer. The business rule change, the discount calculation the finance team keeps refining, touches one use case and its tests, and nothing else in the system moves.
The testability payoff compounds quietly. The use case suite runs in milliseconds without a database, so it runs on every save, so the business rules, the code the company actually owns, are exercised thousands of times a day by the developers who change them. The adapter tests are thin, the integration layer proves the wiring, and the split is the reason the suite stays fast as the system grows, because only the outer ring is slow. The teams that never draw the boundary discover the same arithmetic in reverse, the only meaningful tests need the whole stack, the suite takes half an hour, it stops running on save, and the business rules evolve unguarded from that day on.
The pragmatic dial between the extremes
The honest implementation sets the ceremony per module, and the dial has three recognized settings. The first is the trivial module, the CRUD entity with no invariants, no interesting rules, a table and a form. The full layering here is ceremony, and the pragmatic answer is a thin slice, the repository, the service method, the handler, honest three layer code with the dependency direction intact, one file per concern at most, no interfaces until a second implementation exists. The second is the money module, the pricing, the ledger, the workflow, where the rules are the product and the volatility is real, the adapters are payment providers, storage engines and frameworks with turnover history, and here the full pattern pays, the ports are explicit, the domain model is framework free, and the mapping cost is the insurance premium on the module that cannot quietly break.
The third setting is the boundary module, the shared kernel between teams, where the interface is other people's code, and the discipline is the published contract, the ports defined in the owning module and implemented in the consuming ones, which is the dependency inversion applied at organizational scale. The codebase that sets the dial per module reads like a portfolio of risk decisions, heavy where the rules and the churn justify it, light where speed is the requirement, and the architecture document that explains the dial settings per module is worth more than any diagram of circles.
The signals that turn the dial up
The dial turns up on evidence, and the evidence has a vocabulary. The module whose tests need the database to express a business rule is asking for a boundary. The module where a provider change, a queue, a storage engine, a third party client, broke business code last quarter is asking for a port. The module the team fears to touch, the one where the on-call engineer checks the blast radius before every change, is asking for the whole rule, because that fear is the measured cost of inverted dependencies, paid in review hours and incident budget. The signal to ignore is fashion, the new team member who wants the full ceremony everywhere because the diagram was persuasive, and the answer is the portfolio review, show the risk, show the volatility, and let the dial setting argue from evidence the way every other engineering decision argues.
The composition root where the wiring lives
The pattern's least discussed piece is the one that makes the dependency rule executable, the single place where interfaces meet implementations. The composition root, one module at the outermost edge, constructs every concrete adapter and injects it into every use case:
# main.py, the only file that imports both sides
orders_repo = SqlOrderRepository(session_factory)
payment = StripePaymentAdapter(api_key)
place_order = PlaceOrder(orders=orders_repo, payment=payment)
app.add_url_rule('/orders', view_func=make_order_endpoint(place_order))The file is deliberately ugly, it knows every concrete class by name, and that ugliness is the architecture's keystone, because it is the only file in the system where the ORM, the payment client and the use cases appear together. Delete it and the system cannot start, read it and the entire runtime dependency graph is one page. The teams that scatter this wiring across the codebase lose the rule without noticing, an import here, a global there, and the domain's independence becomes a claim rather than a property, so the composition root belongs in the team's review vocabulary, one file, at the edge, owning every new.
The test that proves the seam
The boundary's value is captured in one test, and the test is short enough to print in full:
def test_place_order_charges_total_plus_shipping():
orders = FakeOrderRepository()
payment = FakePayment()
use_case = PlaceOrder(orders=orders, payment=payment)
use_case.execute(OrderCommand(
items=[Item(sku='k-1', price=100),
Item(sku='k-2', price=250)]))
assert payment.charged == [356]
assert orders.saved[0].items[0].sku == 'k-1'No database, no HTTP, no container, and the test asserts the business outcome, the charge that includes shipping, the persistence that happened. It runs in milliseconds, so it runs constantly, and the fake adapters are one class each because the ports they implement were designed to be fakeable, the repository's save and the payment's charge, nothing more. The test is the deliverable the whole pattern exists to make possible, the business rule under constant guard, and its absence in a codebase is the fastest diagnostic that the boundary is drawn on the whiteboard and not in the source.
The failure modes on both ends of the dial
The pattern fails at both extremes and the failures are worth naming. The ceremony extreme produces the anemic inversion, six layers where every layer is a field for field copy of the neighbor, the use cases that add no rule, the interfaces with one implementation and no second ever coming, and the tell is the commit that changes one business rule and touches twelve files, which is the ceremony tax paid with no insurance purchased. The anemic extreme produces the omniscient service, the business logic smeared through the handlers and the SQL, the tests that need the world, and the tell is the incident review that cannot say whether the defect was in the rule or the plumbing, because there is no seam where one stops and the other starts.
The repair for both is the same move, find the module's actual rules, the code the company owns because the competitor's version differs, and draw exactly one boundary around it, inward dependencies, a port per external concern, and the rest of the ceremony stays or goes based on whether any second implementation exists. That one boundary delivers the testing and the change isolation benefits at maybe a tenth of the full pattern's surface area, and the modules that grow beyond it announce themselves with the signals above.
The working rules for the portfolio
The dial settings become team policy when written, and the working list is short:
- Adopt the dependency rule as direction, inward, and treat every diagram that does not explain it as decoration;
- Set ceremony per module, full ports and domain model where rules and volatility justify, thin slices for CRUD;
- Draw the first boundary around the money module, the rules the company owns, and prove the seam with tests that need no infrastructure;
- Introduce an interface when the second implementation is foreseeable, and delete it when it never came;
- Keep the use case free of framework imports, and enforce it in review rather than in a linter argument;
- Revisit the dial per module yearly, evidence moves it, fashion does not.
The architecture that survives years is not the one with the most layers, it is the one whose dependencies point the way change actually flows, rules at the center guarded by fast tests, infrastructure at the edge where replacement is routine, and a team that knows which modules deserve the ceremony because it can name the risk each layer is insuring. That knowledge, not the diagram, is what the pattern was selling all along.
A word on the naming zoo, because the pattern arrives wearing different labels in different books, clean, hexagonal, onion, ports and adapters, and the differences are mostly geography, where the circles are drawn and what the arrows are called. All of them state the dependency rule, all of them put the business rules behind interfaces, and the team choosing between the labels should spend its debate budget on the dial settings, which modules earn which ceremony, instead of the label, which the next maintenance engineer will ignore anyway. The codebase that can point to its money module, name the two adapters it survived, and run its business rules without a database has whatever architecture the labels were describing, and the codebase that cannot has none of them.