Ports and Adapters, Clean Architecture, Onion Architecture, and Domain-Driven Design, Compared on One Async Codebase.
One async service, built five ways, then measured instead of argued about. Python 3.14, FastAPI, Pydantic v2 and SQLAlchemy 2.1, with every version pinned and every listing in a repo you can run.
Kindle · Paperback · Hardcover

“Architecture is about which way the dependencies point between the business rules and everything outside them, and nothing else.”

Gabriel Anhaia
Senior Software Engineer · Berlin
Sound familiar?
This book fixes that — the Python way.
What's inside
A meeting-room booking service grows an HTTP API, a CLI, a Kafka consumer and a scheduled job, then gets rebuilt four more ways. The hexagon comes to 364 lines. The vertical slices do it in 261. Clean is the heaviest at 536. The book prints all of it, including what does not favor the hexagon.
3 chapters
The framework that ate the business. Five architectures, one question. Python without a compiler to stop you.
4 chapters
A domain that imports nothing. Ports as Protocols the core writes. Adapters on both sides. The dependency rule as a build failure.
6 chapters
A layout that tells the truth. Modeling bookings. Use cases. An HTTP API, a CLI and a Kafka consumer. SQLAlchemy 2 behind the ports.
4 chapters
The same feature as Clean, Onion, layered and vertical slices. All five pass the same fourteen scenarios, then get counted.
5 chapters
Testing the hexagon. The unit of work and the double-booking race. Errors across boundaries. The outbox. Observability.
3 chapters + conclusion
When not to do any of this. Migrating a framework-shaped app in steps that each ship. From one hexagon to many.
After reading
Tested code, not toy examples
A free public repository holds every file the book prints, all five architecture variants and the recorded output of every command. You need Docker with Compose and nothing else.
github.com/gabrielanhaia/hexagonal-python-examples
About the author
Senior Software Engineer in Berlin with fifteen years in technology. He builds and runs backend systems and AI services, and has worked in the electronics industry and on avionics.
Also the author of Hexagonal Architecture in Go, Decoupled PHP and creator of Hermes IDE, an open-source AI-native terminal.
Build services that last
25 chapters, five architectures, one codebase. Every listing runs.
Kindle · Paperback · Hardcover
Same architecture, another language
Ports and adapters in Go: Hexagonal Architecture in Go.
Work in PHP too? Decoupled PHP applies the same boundaries to Laravel and Symfony codebases.