1 Taming complexity with hexagons

Hexagonal architecture is presented as a practical response to the slow decay of software systems caused by accidental complexity. The chapter argues that codebases become hard to change when business logic is tightly wired to frameworks, databases, user interfaces, and external services, because even small changes then ripple across the system. Rather than treating architecture as decoration, the pattern is framed as a way to keep the most important parts of the application protected, stable, and easier to reason about over time.

At its core, the approach separates the application into an inner business core and an outer ring of technology-specific adapters. The core defines ports, which are interfaces for what the application can accept and what it needs, while adapters implement those ports on the outside. This means controllers, repositories, message consumers, and external clients can all be swapped without forcing changes in the domain logic, because dependencies are inverted and always point inward toward the core.

The chapter also shows how this structure works in practice through an article-creation flow: a REST controller translates requests into a command, an input port hands that command to a handler, the handler enforces rules and coordinates the domain, and output ports reach out to persistence or other services through adapters. The main benefits are stronger testability, clearer contracts, easier substitution of infrastructure, and a framework-agnostic core that can survive migrations and integration changes. At the same time, the text is pragmatic about trade-offs: hexagonal architecture adds boilerplate and discipline, so it is most valuable when systems are expected to grow, integrate heavily, or evolve for a long time.

Without an architectural structure, technical debt compounds exponentially. Hexagonal architecture keeps costs manageable by isolating change impact.

The core defines ports (interfaces). Adapters implement them. Dependencies always point inwards.

In traditional, layered architectures, dependencies flow downwards, whereas in the hexagonal architecture, dependencies flow inward.

Metaphor of lasagna leaking technical constraints of the data model into all the layers.

Abstraction of a fake boundary pretending to protect the core and failing to do so.

Hexagonal Architecture for Article creation -- complete component diagram with flow.

• Hexagonal Architecture isolates core business logic from external concerns using Ports (interfaces) and Adapters (implementations), with dependencies always flowing inward via the Dependency Inversion Principle.
• The pattern solves accidental complexity, the maintainability decay that plagues growing codebases, by keeping domain logic framework-agnostic, testable in isolation, and swappable at the boundaries.
• Real-world use cases include SaaS products needing multiple interfaces, technology migrations without touching business logic, and testing transformations from slow integration tests to fast unit tests.
• Think of it as a pipeline that follows a clear flow: any request (in whatever flavor) arrives at a Primary Input Adapter, which calls an Input Port (an interface). The Handler implements it by orchestrating validation, domain creation, and persistence or any other external dependencies via Output Ports (again, interfaces). Results flow back as typed Either<Error, Void|DTO> values -- no hidden exceptions.
• Key patterns include the Always-Valid Domain Model, functional error handling with Either, CQRS, and architectural testing with ArchUnit. The book uses Java + Spring Boot + Vavr + additional aid libraries, but the principles apply universally to them.
• This is pragmatic architecture, not dogma. You will learn when to apply patterns rigorously, when to compromise, and how to introduce hexagonal architecture gradually to legacy codebases.

FAQ