Reading Notes: Get Your Hands Dirty on Clean Architecture

Most software engineers already know what Clean Architecture and Hexagonal Architecture are. We know the diagrams. We know the buzzwords: dependency inversion, ports and adapters, domain-centric design. And yet — many real-world systems still end up fragile, hard to test, and painful to change.

Tom Hombergs’ Get Your Hands Dirty on Clean Architecture is valuable precisely because it tackles this gap. This is not a philosophical book. It is a hands-on guide for applying Clean Architecture in real applications, with real tradeoffs, real constraints, and real Java/Spring examples.

Why Clean Architecture Only Matters When You Actually Use It

The core message is simple:

Clean Architecture only works if you shape your code around use cases, not frameworks.

The Real Problem with Layered Architecture

Traditional layered architecture looks neat on paper:

Controller → Service → Repository → Database

But in practice, it often degrades into something far messier. Hombergs explains how layered systems tend to drift toward:

• Database-driven design
• Domain objects becoming thin reflections of tables instead of modeling business rules
• Shortcut dependencies that bypass domain logic
• Hidden intent where we no longer know what the system actually does
• Low testability because business logic is smeared across layers
• Team friction due to unclear ownership of shared service classes

The issue is not that layers are “wrong.” The issue is that layers don’t protect the domain by default.

Dependency Inversion Is the Real Architecture

The heart of Clean/Hexagonal Architecture is dependency inversion, not fancy folder names. Hombergs reframes the architecture like this:

• Domain and use cases live at the center
• Frameworks are implementation details
• All dependencies point inward

Instead of the domain depending on Spring, JPA, or HTTP, the domain defines ports (interfaces), and infrastructure provides adapters (implementations).

This single move unlocks most benefits:

• Frameworks become replaceable
• Business logic becomes testable
• Architecture becomes enforceable by structure

Clean Architecture is less about what you use and more about what depends on what.

Making Architecture Visible in Code

If you can’t see the architecture in the folder structure, it will erode. Hombergs compares two styles:

• Package-by-layer (controller, service, repository)
• Package-by-feature (account, payment, transfer)

He strongly favors architecturally expressive, feature-first packages, where:

• Each feature contains its domain, application, and adapters
• Use cases are easy to find
• Boundaries are visible without reading the code
• Dependency injection is treated as assembly, not justification for coupling everything together

What a Proper Use Case Looks Like

A key strength of the book is its treatment of use cases as first-class citizens. A well-designed use case:

• Has explicit input and output models
• Validates both input constraints and business invariants
• Prevents invalid states using constructors, value objects, and strong domain modeling
• Coordinates domain objects instead of acting as a “god service”

The book is pragmatic: you can use rich or anemic domain models — but you must be intentional. Clean Architecture is not dogma; it’s discipline.

Adapters Stay Thin — or They Rot

Adapters are where frameworks touch your system (web controllers, persistence repositories, messaging consumers, external APIs). Hombergs is strict on one thing:

Adapters should translate and delegate — never contain business logic.

Good adapters:

• Map between DTOs and use-case models
• Call ports, not implementations
• Are sliced by use case (not one giant controller or repository)

This keeps business rules centralized and prevents infrastructure from leaking inward.

Testing Gets Easier When Boundaries Are Real

With clean boundaries in place, testing stops being painful. The book promotes a practical test pyramid:

• Unit tests for domain logic and use cases
• Integration tests for adapters
• Few end-to-end tests for critical paths

Because dependencies point inward, most logic can be tested without Spring, databases, or HTTP. Testing becomes faster, cheaper, and more reliable — not because of better tools, but because of better design.

Mapping Is a Tradeoff — Choose Consciously

Hombergs lays out several mapping strategies:

• No mapping
• Two-way mapping
• One-way mapping
• Full isolation

Each has tradeoffs between speed, simplicity, and decoupling. The important lesson is not which strategy to choose, but that mapping decisions should be explicit, not accidental.

Assembly Is Not Business Logic

Another underappreciated insight:

Wiring is not behavior.

The book clearly separates:

• Business logic (domain + use cases)
• Assembly (Spring config, scanning, wiring)

Whether you use plain Java, Spring component scanning, or Java configuration, the key rule remains: assembly must stay outside the core.

Preventing Architecture Erosion

Clean Architecture fails silently if not enforced. Hombergs suggests practical safeguards:

• Package visibility rules
• Architecture tests
• Module boundaries
• Build-time checks

Architecture is not a one-time decision — it’s a continuous constraint.

Shortcuts Are Inevitable — But Dangerous

Shortcuts will happen, but treat them like broken windows:

• Decide intentionally
• Document the shortcut
• Understand the cost

Examples include:

• Sharing models across use cases
• Using domain entities as API models
• Skipping ports “for now”

Sometimes acceptable. Often risky. Always worth revisiting.

The Final Philosophy

The book closes with a refreshing stance:

• No single architecture fits all systems
• Domain is king
• Experience is queen
• Everything else depends on context

Clean Architecture is not about purity. It’s about keeping change cheap as the system grows.

Why This Book Is Worth Reading

Get Your Hands Dirty on Clean Architecture succeeds because it focuses on application, not ideology.

If you’ve ever:

• Drawn clean architecture diagrams but struggled to implement them
• Ended up with “service” classes doing everything
• Wanted better tests without mocking the world

…this book will feel uncomfortably familiar — and genuinely helpful.

Clean Architecture only matters when it shapes your daily coding decisions. This book shows you how to make that happen.