Clean Architecture

## The four concentric rings Clean Architecture, popularized by Robert C. Martin ("Uncle Bob") in his 2012 blog post and later the 2017 book Clean Architecture, organizes a system into concentric rings and states one governing rule: the **Dependency Rule**. Source code dependencies - the import or use statements in your code - may only point inward, from outer rings toward inner rings, never the reverse. - **Entities** - the innermost ring holds the most general, most stable business rules and data structures, the kind of logic that would exist even if you changed how the whole application is delivered. - **Use Cases** (sometimes called **Interactors**) - the next ring out holds application-specific business rules that orchestrate entities to accomplish a particular task, like 'place an order' or 'cancel a subscription.' - **Interface Adapters** - outside that sits controllers, presenters, and gateways that translate data between the use-case-friendly format and whatever format the next ring needs. - **Frameworks & Drivers** - the outermost ring is the web framework, the database driver, the UI toolkit, the ORM - the most volatile, most replaceable, most detail-laden code in the system. ## The mechanism: Dependency Inversion The mechanism for keeping dependencies pointing inward when the natural runtime data flow often needs to go the other way (a use case needs to read/write a database, an outer-ring concern) is the **Dependency Inversion Principle**. 1. The inner ring defines an abstraction - an interface - that describes only what it needs, in its own vocabulary, and that interface physically lives inside the inner ring's source tree or package. 2. The outer ring then implements that interface. 3. So in a Kotlin backend, `OrderRepository` (an interface with methods like `findById`, `save`) lives in the use-case package, and `JpaOrderRepository`, which knows about Hibernate, SQL, and connection pools, lives in the infrastructure package and implements `OrderRepository`. The compiled dependency arrow (infrastructure -> use case) now points inward even though the runtime call still flows from use case to infrastructure implementation at execution time. This is the crucial distinction the rule turns on: it governs **source-level dependency direction**, not the direction of a runtime function call. ## Why does this exist? The core problem it solves is protecting the parts of the system that encode genuine, hard-won business knowledge - what 'placing an order' actually means for this company - from churn caused by parts of the system that are essentially interchangeable technology choices. Databases get migrated, web frameworks get upgraded or replaced, UI toolkits go in and out of fashion, but the rule 'an order cannot ship without a valid payment' rarely changes for reasons related to any of that. By making the use case ignorant of JPA, Spring, or the specific SQL dialect in use: - you can unit-test the use case with a fake in-memory implementation of `OrderRepository` in milliseconds, with zero database, zero HTTP server, and zero framework bootstrap; - you can also swap Postgres for DynamoDB, or REST for gRPC, by writing new adapters, without touching a single use-case class - a genuine, measurable reduction in blast radius for infrastructure changes. ## The trade-off The trade-off is that this indirection is not free. Every one of these boundaries typically means: - an extra **interface**; - at least one extra **implementation class**; - often a **DTO or mapping layer** to convert between the use case's domain model and whatever shape the database, JSON API, or third-party SDK expects. For a small CRUD service with two entities and a handful of endpoints, this ceremony can genuinely cost more in code volume and onboarding time than it saves, and teams frequently over-apply the pattern to systems that will never actually swap a database or a UI, paying the tax without ever collecting the benefit. ## Failure modes 1. The failure mode that shows up most often in production codebases is what's sometimes called an **anemic or 'pass-through' use case**: an interactor class that does nothing but immediately delegate to a repository call, adding a layer of indirection with zero actual business logic in it - a sign the abstraction is being applied mechanically rather than where it earns its keep. 2. A second common failure is **leakage in the other direction**: JPA `@Entity` annotations, Spring `@Component` annotations, or Jackson `@JsonProperty` annotations end up directly on domain/use-case classes 'because it's convenient,' which silently violates the Dependency Rule even though the code still compiles - the use-case package now has a hard source dependency on `javax.persistence` or `com.fasterxml.jackson`, an outer-ring framework, and can no longer be unit tested or reused without dragging that framework along. ## A worked example A concrete example: a payment-processing use case class `ProcessRefundInteractor` depends only on a `RefundGateway` interface it declares itself. - In production, `StripeRefundGateway` implements it by calling the Stripe SDK. - In tests, `FakeRefundGateway` implements it with an in-memory list. Both satisfy the same interface, so the interactor's logic - validating the refund amount against the original charge, checking refund eligibility windows - is tested without a network call, and the team was later able to add a second payment provider adapter without editing the interactor at all.