welcome

To get the most from this book, you should be comfortable writing Java (Spring Boot experience helps but isn't required) and have built at least one application where you felt the pain of tangled dependencies, untestable business logic, or a framework that swallowed your domain. If you've ever asked, "where does this code belong?" — this book is for you.

I wrote this book because I spent years watching teams adopt clean/hexagonal architectures through blog posts and conference talks, only to hit the same walls: annotations in the wrong layer, repositories coupled to Spring Data, domain logic leaking into controllers, tests that break when you change infrastructure. The pattern itself is simple — the execution is where teams struggle.

Decoupling by Design bridges that gap. Rather than discussing clean/hexagonal architecture in the abstract, we build a complete application called WriteFlow — an article publishing platform — from the domain core outward. Every chapter adds a concrete, working layer: domain entities with enforced invariants, use cases orchestrated through a command/query bus, adapters that keep frameworks at arm's length, ArchUnit rules that catch structural drift at test time, and a mechanical testing approach that makes verification boring in the best possible way.