chapter six

6 The running hexagon: From pieces to system

 

This chapter covers

  • Organizing hexagonal code into Maven modules
  • Wiring ports to adapters with Spring dependency injection
  • Resolving technology-agnostic transactions at runtime
  • Delivering domain events within transaction boundaries
  • Publishing integration events through the outbox pattern
  • Separating framework wiring from application core logic

We have built every piece of WriteFlow's hexagonal architecture in isolation. The domain model guards its invariants. Commands and queries carry validated input through the bus. Handlers orchestrate without owning business logic.

Adapters translate at the boundary. Repositories persist and reconstitute domain state. Each piece is independently testable, replaceable, and comprehensible.

None of them can run.

In a real project, you rarely build every piece in complete isolation and only assemble at the end. You usually move iteratively: carve out one use case, define its ports, implement the adapters it needs, wire it, and repeat. This book separates the pieces first for teaching purposes, so the role of each part is clear before we connect them into a running system.

6.1 Code organization: Modules that enforce boundaries

6.2 Assembly time: Wiring the hexagon

6.2.1 The bootstrap

6.2.2 Discovering hexagonal stereotypes

6.2.3 Wiring the command and query buses

6.2.4 Manual bean registration for external infrastructure

6.3 Transactionality: Boundaries the framework resolves

6.3.1 The technology-agnostic annotation

6.3.2 The Either problem: No exception, no rollback?

6.3.3 The bridge: Three components

6.3.4 Where transaction boundaries live

6.3.5 Readonly and CQS

6.4 Domain events: The full lifecycle

6.4.1 The adapter

6.4.2 When listeners execute: The transactional question

6.5 Integration events: When domain events are not enough

6.5.1 Domain events vs. integration events

6.5.2 From domain event to integration event

6.5.3 The outbox pattern: A brief introduction

6.6 Summary