25 Chapters·6 Parts·Companion Repo

Hexagonal Architecture in Python.

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

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

Gabriel Anhaia

Senior Software Engineer · Berlin

Sound familiar?

→A business rule lives in three FastAPI route handlers, and they have started to disagree?
→Your tests need a database before they can say anything about pricing?
→A CLI or a second payment provider means editing the code that holds the rules?
→Every architecture article reads like Java with the semicolons removed?
→Clean, Onion, Hexagonal: everyone has a diagram, and nobody has counted what each one costs?

This book fixes that — the Python way.

What's inside

25 chapters. 6 parts. Zero filler.

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.

Part I — The Problem

3 chapters

The framework that ate the business. Five architectures, one question. Python without a compiler to stop you.

Part II — Thinking in Hexagons

4 chapters

A domain that imports nothing. Ports as Protocols the core writes. Adapters on both sides. The dependency rule as a build failure.

Part III — Building the Booking Service

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.

Part IV — The Other Architectures, Built

4 chapters

The same feature as Clean, Onion, layered and vertical slices. All five pass the same fourteen scenarios, then get counted.

Part V — Production Patterns

5 chapters

Testing the hexagon. The unit of work and the double-booking race. Errors across boundaries. The outbox. Observability.

Part VI — Evolution

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

You'll be able to:

Tell from a codebase's imports which architecture it really is
Model a domain in plain Python, with frozen dataclasses that import nothing
Write adapters that translate and decide nothing, wired in one composition root
Make the dependency rule a build failure with import contracts and strict typing in CI
Test the core in milliseconds, and prove your fakes honest against real PostgreSQL
Handle the unit of work, the double-booking race, the outbox and tracing
Pick an architecture from two facts about your service, and know when that pick stops being right
Migrate a framework-shaped app to a hexagon in steps that each ship

Tested code, not toy examples

Companion Repository

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
Gabriel Anhaia

About the author

Gabriel Anhaia

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

Stop fighting your codebase.
Structure it.

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.

See the book

Work in PHP too? Decoupled PHP applies the same boundaries to Laravel and Symfony codebases.