kayaman/clean-architecture

Clean Architecture

Reference: Clean Architecture (Martin), Get Your Hands Dirty on Clean Architecture (Hombergs), Fundamentals of Software Architecture (Richards & Ford)

When to Apply

• Structuring a new application's package/module layout
• Defining boundaries between domain logic and infrastructure
• Reviewing imports for dependency rule violations
• Deciding how data should cross layer boundaries
• Evaluating whether the architecture "screams" business purpose or framework choice
• Assessing component cohesion and coupling in a modular system

---

The Dependency Rule

The overriding rule: Source code dependencies MUST only point inward — from outer layers toward inner layers. Nothing in an inner circle can know anything about an outer circle: no names, no data formats, no function calls.

Dynamic polymorphism (DIP) creates source code dependencies that oppose the flow of control, allowing inner layers to define interfaces that outer layers implement.

---

The Four Layers

From innermost (most stable) to outermost (most volatile):

1. Entities (Enterprise Business Rules)

• Domain objects encapsulating business rules independent of any application
• Least likely to change when externalities change
• MUST NOT depend on any other layer
• MUST NOT import framework classes, database libraries, or HTTP concepts
• Examples: Order, Money, ShippingPolicy

2. Use Cases (Application Business Rules)

• Application-specific orchestration — direct entities to use their business rules
• Each use case represents one user goal or system operation
• MUST depend only on Entities
• MUST NOT know about delivery mechanism (HTTP, CLI, queue) or persistence technology
• SHOULD be named by business action: PlaceOrder, CancelSubscription, TransferFunds

3. Interface Adapters

• Controllers, presenters, gateways — convert data between use case format and external format
• MUST NOT contain business logic — only format conversion and delegation
• All SQL, HTTP serialization, and framework annotations are restricted to this layer
• Examples: REST controllers, repository implementations, view models, DTO mappers

4. Frameworks & Drivers

• Outermost layer: web frameworks, databases, UI, external services
• "The web is a detail. The database is a detail."
• SHOULD contain minimal code — mostly glue configuration wiring frameworks to adapters
• Changes here MUST NOT propagate inward

---

Data Crossing Boundaries

• MUST pass only simple data structures across boundaries: DTOs, primitives, or plain value objects
• MUST NOT pass Entities outward — map to a response DTO at the adapter layer
• MUST NOT pass database rows or ORM entities inward — map to domain objects at the adapter layer
• SHOULD NOT create identical DTOs for every layer boundary — map only where formats genuinely differ

| Direction | What Crosses | Example | |-----------|-------------|---------| | Inward (request) | Input DTO or command object | PlaceOrderCommand { customerId, items[] } | | Outward (response) | Output DTO or result object | OrderConfirmation { orderId, estimatedDelivery } | | Never | Entity, DB row, ORM model, framework object | Order entity, Hibernate proxy, Express Request |

---

Screaming Architecture

The top-level directory structure SHOULD reveal the system's business purpose, not its framework.

Good — screams "health clinic":

src/
  appointments/
  patients/
  billing/
  prescriptions/

Bad — screams "Spring Boot":

src/
  controllers/
  services/
  repositories/
  models/

• SHOULD organize top-level packages by business capability or use case
• MAY use technical sub-packages within a business package (e.g., appointments/adapter/, appointments/domain/)

---

Humble Object Pattern

Split behavior into two parts: a testable component with all the logic, and a humble component that is hard to test but contains minimal logic.

| Component | Testable? | Contains | |-----------|-----------|----------| | Presenter | Yes | Formats data, applies display logic, builds view model | | View | Humble (hard to test) | Renders the view model to screen — minimal logic | | Gateway | Yes (interface) | Defines data access contract | | Repository Impl | Humble | Executes SQL, calls ORM — tested via integration tests |

• SHOULD push all logic out of hard-to-test components into their testable counterparts
• SHOULD use the humble object boundary as a natural seam for unit vs integration testing

---

Component Design Principles

Cohesion Principles (what goes inside a component)

| Principle | Rule | Tension | |-----------|------|---------| | REP (Reuse/Release Equivalence) | The granule of reuse is the granule of release — group things released together | Too broad: components become bloated | | CCP (Common Closure) | Classes that change together belong together — SRP at component level | Too narrow: too many components | | CRP (Common Reuse) | Don't force users to depend on things they don't need — ISP at component level | Too strict: components fragment |

SHOULD balance these three forces: REP and CCP tend to make components larger; CRP makes them smaller. Early in development, favor CCP (group by change). As the system matures, shift toward CRP (minimize unnecessary dependencies).

Coupling Principles (relationships between components)

| Principle | Rule | |-----------|------| | ADP (Acyclic Dependencies) | The component dependency graph MUST have no cycles | | SDP (Stable Dependencies) | Depend in the direction of stability — volatile components depend on stable ones | | SAP (Stable Abstractions) | Stable components SHOULD be abstract; unstable components SHOULD be concrete |

• MUST break dependency cycles using DIP (introduce an interface) or extract a new shared component
• SHOULD measure instability (I = outgoing / (incoming + outgoing)) and abstractness (A = abstract classes / total classes)
• Components in the "zone of pain" (stable + concrete) are rigid; components in the "zone of uselessness" (unstable + abstract) are irrelevant

---

Common Pitfalls

| Pitfall | Why It Happens | Remedy | |---------|---------------|--------| | Over-layering CRUD apps | Applying 4 layers to simple data entry | Skip use case layer for trivial operations; use adapters directly | | Use cases as repository proxies | Use case does nothing but call repository.save() | If there's no business logic, the use case adds no value — simplify | | Mapping everything | Identical DTOs at every boundary | Map only where formats genuinely differ; don't cargo-cult mapping | | "Easy database swap" myth | Justifying layers by hypothetical DB migration | Layers exist for testability and independence, not DB swaps | | Framework in the domain | Annotations, framework types leak into entities | Entities MUST be plain objects with zero framework dependencies | | Designing components top-down | Trying to define all components before writing code | Component structure evolves as the codebase grows — don't over-plan |

---

Checklist

When designing or reviewing architecture, verify:

• [ ] Source code dependencies point inward — no inner layer imports from an outer layer
• [ ] Entities contain business rules and have zero framework dependencies
• [ ] Use cases orchestrate entities without knowing about HTTP, SQL, or UI
• [ ] Interface adapters convert between use case format and external format only
• [ ] Data crosses boundaries as DTOs or simple structures, never as entities or DB rows
• [ ] Top-level directory structure reveals business purpose (Screaming Architecture)
• [ ] Hard-to-test code is isolated in humble objects with minimal logic
• [ ] Component dependency graph has no cycles (ADP)
• [ ] Stable components are abstract; volatile components are concrete (SAP)
• [ ] Architecture complexity matches the problem — no over-layering for simple operations

Key References

| Book | Author(s) | Publisher | Year | |------|-----------|-----------|------| | Clean Architecture | Robert C. Martin | Pearson | 2017 | | Get Your Hands Dirty on Clean Architecture (2nd ed.) | Tom Hombergs | Packt | 2023 | | Fundamentals of Software Architecture | Mark Richards, Neal Ford | O'Reilly | 2020 | | Software Architecture: The Hard Parts | Ford, Richards, Sadalage, Dehghani | O'Reilly | 2021 | | Software Architecture in Practice (4th ed.) | Bass, Clements, Kazman | Addison-Wesley | 2024 | | A Philosophy of Software Design (2nd ed.) | John Ousterhout | Stanford | 2021 |