1 Taming complexity with hexagons

This chapter introduces hexagonal architecture as a practical response to accidental complexity, the kind of mess that grows when shortcuts, framework coupling, and leaky abstractions accumulate over time. Rather than treating complexity as inevitable, it argues that the real problem is weak boundaries: when business logic is tied directly to databases, APIs, user interfaces, and other infrastructure, every change ripples outward and maintenance becomes increasingly expensive. The chapter frames architecture as a way to protect the core of the system so that changes remain local, tests stay fast, and the application can evolve without constant fear of breaking unrelated parts.

At the center of the approach is a clear separation between the application core and everything outside it. The core contains the domain rules, entities, and use cases, while ports define the contracts it exposes or requires. Adapters sit at the edges and translate between external technologies and those core contracts. Input ports represent what the application can do, output ports represent what it needs, and adapters implement the technical details such as REST controllers, repositories, message consumers, or external service clients. This structure relies on dependency inversion so that dependencies always point inward: the core defines the abstractions, and the external world depends on them, not the other way around.

The chapter also shows why this matters in modern systems and how the model works in practice through an article-creation example. A request enters through a driving adapter, is translated into a command, handled by a use case in the core, may invoke output ports for persistence or external data, and then returns through the boundary with explicit error handling. The result is a system that is easier to test, easier to swap infrastructure in and out of, and clearer for teams to evolve over time. The chapter closes by acknowledging trade-offs: hexagonal architecture adds structure and upfront boilerplate, so it is most valuable when systems are expected to grow, integrate with many technologies, or outlive their first implementation.

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