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

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.

• 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)

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)

• 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

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