Clean Architecture

1The spiral of ever-more-expensive code

Every project starts fast, then each feature costs a little more than the last, until the team is wading through mud. Martin opens the book with the curves of a real company (anonymized) across eight releases:

• the cost per line of code in release 8 is 40 times that of release 1;
• the monthly payroll reaches 20 million dollars... and buys almost nothing;
• headcount explodes while productivity per developer creeps toward zero.

The lie everyone tells themselves, quoted as is: "We can clean it up later; we just have to get to market first!" (ch. 1). Except that "later" never comes: once you are on the market, there is a next deadline, a competitor to catch up with, a feature the customers demand. The pressure that justified dirtying the code yesterday justifies not cleaning it today, and so on all the way to the standstill. Hence the definition Martin builds the book on: "The goal of software architecture is to minimize the human resources required to build and maintain the required system" (ch. 1). Not elegance, not diagrams: the bill.

Chapter 2 names the trade-off: software has two values, behavior (urgent) and structure (important), and teams keep promoting the urgent over the important. Exactly backwards, says Martin.

2Three paradigms, three prohibitions

All three programming paradigms were discovered between 1958 and 1968. None since. And Martin defines them backwards from the usual brochure: each one removes a power from the programmer, none adds one.

• Structured (Dijkstra, 1968) removes goto, the instruction that jumped anywhere in the program. Without it, code reads top to bottom: your if, while and for are what is left once the wild jump is gone;
• Object-oriented (Dahl & Nygaard, 1966) removes wild indirect jumps: you no longer call "whatever code's address is lying around", you call a method, and the language guarantees it exists. Polymorphism, tamed;
• Functional (Church, 1936) removes assignment: once created, a value never changes again. And if nothing changes, whole families of bugs (shared state, concurrency) vanish with it.

"Each of the paradigms removes capabilities from the programmer. None of them adds new capabilities" (ch. 3). What is left to take away? Nothing, Martin bets: there will be no fourth paradigm. The practical lesson: a paradigm is a constraint you accept because it makes code predictable, not one more gadget.

3The SRP is not what you think it is

Two acronyms to lay down first. SOLID stands for the five object-oriented design principles popularized by Martin himself: Single responsibility, Open/closed, Liskov substitution, Interface segregation, Dependency inversion. The SRP (Single Responsibility Principle) is the first of the five, the most quoted, and the most distorted.

Martin says it himself: "a function should do one thing" is a different, lower-level principle, and it is NOT the SRP. The real definition: "A module should be responsible to one, and only one, actor" (ch. 7). An actor is a group of people who request the same kind of changes.

The book's example: an Employee class with three methods.

• calculatePay() answers to the CFO's people;
• reportHours() answers to the COO's people;
• save() answers to the DBAs.

Three actors in one class. The day finance asks for a tweak in a shared hours calculation, the operations reports silently go wrong; the book has the COO livid over millions lost to bad data (ch. 7). Splitting by actor means decoupling the angers.

The bad and the good split, before and after:

// ✗ BEFORE: one module, three bosses: their requests step on each other
class Employee {
  name
  hourlyRate
  hoursWorked

  calculatePay()   // finance
  reportHours()    // operations
  save()           // the DBAs

  regularHours()   // private, shared by the first two: the ch. 7 bomb
}

// ✓ AFTER: one module per boss, shared data set apart (ch. 7)

// the data alone, zero logic: just the employee's record
class EmployeeData {
  name
  hourlyRate
  hoursWorked
}

class PayCalculator { calculatePay(EmployeeData d) }   // finance
class HourReporter  { reportHours(EmployeeData d) }    // operations
class EmployeeSaver { save(EmployeeData d) }           // the DBAs

Look closely at what moved between before and after: not the data, the logic. The employee's record (name, hourly rate, hours) stays whole inside EmployeeData, a passive structure all three modules read on their own. The three methods, that is the three reasons to change, each moved in with their boss. Finance's request now only touches PayCalculator: the operations reports can no longer break silently, the code that produces them has not moved. And regularHours(), the shared calculation? Each module keeps its own version. Martin owns the duplication: two calculations that look alike today but will change for different reasons tomorrow are not real duplication. So the splitting criterion is not "what does what" but "who will ask to change it".

4OO's real superpower: turning the arrows around

Martin dismantles the classic definition of OO. Encapsulation? C did it perfectly with .h/.c files, and C++ actually damaged it by exposing private members in headers. Inheritance? A struct trick C programmers already simulated by hand. What is left: "OO is the ability, through the use of polymorphism, to gain absolute control over every source code dependency in the system" (ch. 5).

Concretely: without an interface, business code calls the database, so it depends on it; the import follows the call. With an interface, business code declares "I need something that knows how to save", and the database implements it. The call still flows from business to database at runtime, but the source-code dependency now points from the database toward the business rules. The arrow has flipped. The enormous consequence: the UI and the database become plugins to the business rules, swappable like printers.

5A good architect maximizes the decisions not made

The book's definition: architecture is the shape given to a system to ease its development, deployment, operation and maintenance; and the strategy is "to leave as many options open as possible, for as long as possible" (ch. 15). Hence the most famous line of the book: "A good architect maximizes the number of decisions not made" (ch. 15).

The lived proof: FitNesse, the testing wiki Martin built with his son in 2001. Instead of picking a database upfront, they wrote a WikiPage interface and stored pages in RAM, then in flat files. The result: "for 18 months, we did not have schema issues, query issues, database server issues, password issues, connection time issues" (ch. 17). The punchline: MySQL support was eventually written... by a customer, in a day, because the boundary was clean. Nobody else ever used it. The option was deleted. The postponed decision had become unnecessary.

6Four circles, one rule

The concentric-circles diagram became the most famous image of the book. Martin did not invent it from scratch: it synthesizes sibling architectures that were already saying the same thing. Alistair Cockburn's hexagonal architecture (2005, also called "ports & adapters"): the application core exposes standardized sockets, and each technology plugs into them like an appliance into a power strip. Ivar Jacobson's BCE (1992, for Boundary-Control-Entity): split every feature into three roles, what talks to the outside world, what orchestrates, what carries the business data. Same intuitions, different drawings; Martin merges them into four layers, inside out.

Take a car rental website to make each layer concrete:

• Entities: the business rules that would exist even without computers. "A driver must have held a license for 2 years", "a deposit is required above a certain price". The agency manager already enforced them with a paper notebook;
• Use cases: the rules specific to this application. "Book a vehicle" = check availability, compute the price, block the slot, trigger the email. The scenario, step by step, knowing nothing about the screen or the database;
• Interface adapters: the translators between inside and outside. The controller turning the HTTP request into a use-case call, the repository turning "block the slot" into an SQL query. All the project's SQL is confined here;
• Frameworks & drivers: Symfony, MySQL, the browser. Interchangeable technology, mostly glue.

And one law, the Dependency Rule: "Source code dependencies must point only inward, toward higher-level policies" (ch. 22). Concrete translation: a file may import files from its own circle or from circles further in, never the other way. The controller (adapter) may import the "Book a vehicle" use case; the use case may import the Driver entity; but the Driver entity imports nothing that comes from outside. And "know nothing" is meant strictly: not an import, not a class name, not even the word "MySQL" anywhere in the file.

The test fits in one line: open one of your entities and read its use statements at the top. If you see Symfony, Doctrine or Request in there, the rule is broken: your business rule is tied to a technology, and it will fall with it. No framework import in your entities. Ever.

// 1. Domain: pure PHP, zero framework use. The rules live here.
final class User {
  public function suspend(): void {
    if ($this->hasActiveSubscription()) {
      throw new CannotSuspendPayingUser();   // business rule
    }
    $this->status = Status::Suspended;
  }
}

// 2. Infrastructure: the Doctrine uses live HERE
#[ORM\Entity]
class DoctrineUser { /* id, columns, joins */ }

class DoctrineUserRepository implements UserRepository {
  public function save(User $u): void { /* translates User → DoctrineUser */ }
}

// 3. Security: Symfony's UserInterface is an adapter too
class SecurityUser implements UserInterface { /* wraps User */ }

Chapter 21's test, the quickest architecture review you'll ever run: open your project's top-level folder. Does it scream "accounting"... or does it scream "Rails"? An architecture should tell readers what the system DOES, not what it is built with.

7The kitten problem (your microservices are coupled)

2017: everyone is slicing everything into microservices, and the sales pitch is always the same: independent services, separately deployable, therefore decoupled. Martin asks the awkward question: decoupled with respect to which change? That is the only test that matters.

His counterexample: an Uber-like taxi aggregator, neatly split into four services: the customer UI, the driver finder, the vehicle selector, the dispatcher. On paper, each lives its own life. Then marketing announces a new product: kitten delivery to your door. Walk through what it implies: customer allergies (UI), driver allergies (finder), animal-friendly vehicle criteria (selector), delivery rules (dispatcher). All four services must change together and be redeployed in a coordinated way. Against that change, the split decoupled nothing at all: "Services that simply separate application behaviors are little more than expensive function calls" (ch. 27). Expensive, because a function call got replaced by a network call: slower, and it can fail.

The lesson is not anti-services, it is anti-reflex:

• a service is only a real boundary if the likely changes stay inside it. The practical test: take marketing's next request and count how many services it crosses;
• the boundaries that actually protect you are the four circles (idea 6): business, use cases, adapters. And they must exist inside each service too: a good service is a small clean monolith, not one big file behind an API;
• a good architecture lets a system be born a monolith, grow into deployable units, then services, if the need ever comes (ch. 16). The network split is an option you keep open, not a starting point;
• and the jab, in a footnote: "the number of micro-services will be roughly equal to the number of programmers" (ch. 27). Meaning: teams too often split to mirror the org chart (one team, one service), not the structure of the problem.

8Everything is a detail, and discipline won't save you

The end of the book hammers three nails with the same hammer:

• the database is a detail: a disk technology, not the center of your system;
• the web is a detail: "The GUI is a detail. The web is a GUI. So the web is a detail" (ch. 31). The industry has been oscillating between fat client and fat server since the 1960s; your core business should not swing with the pendulum;
• the framework is an asymmetric marriage: you commit for life, its author commits to nothing. "Don't marry the framework!" (ch. 32): use Spring, but no @Autowired in your business objects.

Then chapter 34, written by a guest (Simon Brown), ends the book with a cold shower. His observation: you can draw the prettiest circles in the world, but if every class in the project is public, any developer in a hurry can short-circuit the plan. Example: the controller is supposed to go through the "Book" use case, which enforces the rules. But nothing prevents writing a direct call to the repository in the controller, skipping the rules. It compiles, it works, it ships. The architecture only existed on the drawing, and in everyone's goodwill.

His answer: ask the compiler to stand guard. In Java, a class declared without the public keyword is only visible inside its own folder. Declare the repository that way, and the controller cannot call it directly anymore: the forbidden shortcut does not compile, instead of being an oversight to catch in code review. "The devil is in the implementation details" (ch. 34). PHP has no native equivalent; you get close with a tool like Deptrac, which fails the CI whenever a layer imports what it should not.