2 WriteFlow's wake-up call: When good architecture intentions aren't enough

WriteFlow begins as a sensible layered monolith, but growth quickly exposes its limits: business rules, framework annotations, persistence concerns, and API concerns all accumulate in the same places, making the system slow to test and hard to evolve. The chapter uses this realistic case to show that the problem is not bad engineering, but architecture that no longer matches the system’s needs. Hexagonal architecture is presented as the remedy because it separates the core from infrastructure and keeps dependencies pointed inward.

The chapter then explains how a request moves through the hexagon: a primary adapter translates incoming HTTP into a core-level command, an input port defines the use case, a handler orchestrates business flow, and output ports let the core ask the outside world for data or persistence without knowing implementation details. Secondary adapters fulfill those requests, while the adapter layer also maps core results back to external responses. This structure makes the core easy to test, infrastructure easy to swap, and boundaries explicit instead of implicit.

Finally, the chapter maps a safe migration path for moving a real system to this style without a risky rewrite. The WriteFlow team extracts domain logic, defines ports, wraps old code behind facades, refactors orchestration into pure handlers, and replaces adapters one at a time while verifying boundaries. It also highlights common mistakes, such as putting business logic in adapters or defining ports that merely mirror JPA methods, and stresses the importance of stakeholder buy-in, incremental delivery, and automated boundary checks to keep the architecture honest.

WriteFlow v1: layered architecture showing Article entity carrying @Entity, @JsonProperty, and @Table annotations simultaneously. Arrows show how a single change to Article ripples through all layers.

A single HTTP POST /articles request flowing through WriteFlow's hexagonal architecture: REST adapter → input port → handler → output port → secondary adapter. Arrows show both the flow of control and the direction of dependencies, which always point inward toward the core.

The request flow from figure 2.2, annotated with component type labels: Primary Adapter, Input Port, Handler, Domain Entity, Output Port, Secondary Adapter. Each label links to the corresponding row in table 2.1.

The WriteFlow five-phase migration map: Phase 1 Extract → Phase 2 Define → Phase 3 Wrap → Phase 4 Refactor → Phase 5 Replace. Each phase box contains its primary goal and a chapter reference.

• WriteFlow's migration from a tightly coupled layered architecture to hexagonal architecture followed five incremental phases—Extract, Define, Wrap, Refactor, Replace—each delivering working software before the next phase began. No big bang rewrite. No production risk.
• The migration decision is as much a stakeholder conversation as a technical one. The strongest argument is a working prototype showing millisecond handler tests and a successful adapter swap, not a diagram. Lead with numbers, not principles.
• Hexagonal architecture produces six standard component types: primary adapters, input ports, handlers, domain entities, output ports, and secondary adapters. Table 2.1 maps each one to its responsibility and to the chapter where it is built in this book.
• For teams coming from layered architecture, the components are familiar (controllers, services, repositories) but the critical difference is ownership. The core defines the port interfaces. Adapters conform to the core's terms. That single reversal, the Dependency Inversion Principle in practice, is what makes the core independently testable and the adapters independently swappable.
• The two most common migration mistakes are business logic leaking into adapters and ports designed around infrastructure methods rather than domain needs.
• ArchUnit is not optional. Without automated boundary enforcement, dependency leaks return within weeks.

FAQ