Chapter 2: WriteFlow's wake-up call: When good architecture intentions aren't enough
Introduces WriteFlow as a case study and previews the chapter’s map for migrating a layered monolith to hexagonal architecture.
After this chapter you will be able to
- Architectural fit under changing requirements. Explain why WriteFlow’s layered monolith was a reasonable starting point but became strained as the business grew and changes were made locally under pressure.
- Article concern accumulation and costs. Describe how Article came to combine HTTP serialization, database mapping, and business validation, and what this meant for testing and adding integrations.
- Inbound request translation. Trace how ArticleController turns an HTTP POST containing JSON into a CreateArticleCommand and invokes the CreateArticleUseCase input port without passing HTTP details into the core.
- Handler and outbound work. Describe how CreateArticleHandler orchestrates author lookup, validation, valid Article creation, and persistence by calling output-port interfaces that secondary adapters implement.
- Inward dependency rule. Explain why dependencies point inward even when request and result data travel across the boundary: the controller and secondary adapters depend on port interfaces, while the core depends on no outside implementation.
- Core Reuse Through Adapters. Explain why a handler and its ports can serve different delivery channels, persistence technologies, or products without changing the core. Describe WriteFlow's REST API and Kafka consumer example.
- Repository interface ownership and inversion. Distinguish the repository interface's location in a typical layered architecture from its ownership in hexagonal architecture, and explain what that reversal enables.
- Decision ownership across components. Distinguish business decisions that belong in a domain entity or handler from external-facing decisions in a primary adapter and infrastructure decisions in a secondary adapter.
- Output port business language. Explain that an output port states what the handler needs in domain language while leaving the means of fulfillment to the secondary adapter.
- Incremental migration discipline. Explain why WriteFlow avoided a big-bang rewrite: each phase delivered working software, and the old and new paths ran in parallel until the new path was proven.
- Framework-free business rule extraction. Explain how to find WriteFlow’s domain logic and decide what belongs in the extracted domain package: look for rules about article validity wherever they currently live, then separate those rules from framework dependencies.
- Core-owned input and output ports. Explain how defining ports replaces WriteFlow’s direct calls with interfaces owned by the core: output ports for what the core needs from outside and an input port for what a controller needs from the core.
- Collaboration-sized port boundaries. Explain why WriteFlow’s first attempt at one output port per repository method was too fine-grained and state the section’s preferred level of abstraction.
- Facade adapters around existing code. Describe how WriteFlow puts its existing repository and controller behind the new port-based boundaries without deleting them. Explain that the repository adapter implements the output port and delegates to the old JPA repository, while the REST adapter maps requests to commands and invokes the input port.
- Parallel path verification. Explain why WriteFlow runs the old direct-call path and the new port-mediated path at the same time and compares their outputs before deleting code.
- Facade adapter logic boundary. Explain why a facade adapter should only translate between the new interface and old code, and where business logic found in the controller should go instead.
- Port-based handler extraction. Describe how WriteFlow extracted CreateArticleHandler from ArticleService and kept its orchestration behind port interfaces rather than framework dependencies.
- Fake hexagonal dependency trap. Distinguish genuine port-based dependency from the fake hexagonal pattern in which a handler calls an adapter directly.
- Port-based adapter replacement. Explain how WriteFlow replaces facade adapters one at a time with adapters built against the same port, changing configuration rather than the handler, domain entity, or port.
- Adapter swap boundary verification. Describe how to check an adapter swap for inward dependency leaks and why WriteFlow uses ArchUnit rather than relying on developers to notice them.
- Evidence for migration approval. Explain why a working prototype makes a stronger case for migration approval than an architecture diagram, and what the prototype should demonstrate.
- Timing of the migration proposal. Explain when to propose the migration and what to do if the system is already in crisis.
- Domain Ownership of Validation. Explain why putting article title validation in a REST adapter caused inconsistent rules across WriteFlow’s REST, Kafka, and GraphQL adapters, and why the team moved that validation into the domain entity.
- Use Case Shaped Output Ports. Explain why copying JPA repository methods into an output port made WriteFlow’s port hard to use with Elasticsearch, and how the team reframed the port around what handlers needed.
What it builds on
- Core concepts: Ports and adapters (chapter 1) · Introduces ports and adapters.
- The secret sauce: Dependency inversion (chapter 1) · Introduces dependency inversion.
Section by section
Introduction
Introduces WriteFlow as a case study and previews the chapter’s map for migrating a layered monolith to hexagonal architecture.
2.1 Meet WriteFlow: The system we will migrate
WriteFlow’s initially suitable layered architecture became a source of technical debt as growing requirements concentrated unrelated concerns in its Article entity.
- Architectural fit under changing requirements: Explain why WriteFlow’s layered monolith was a reasonable starting point but became strained as the business grew and changes were made locally under pressure.
Why it matters: The migration responds to changed demands, not to an inherently bad original design. - Article concern accumulation and costs: Describe how Article came to combine HTTP serialization, database mapping, and business validation, and what this meant for testing and adding integrations.
Why it matters: These concrete costs show why the team’s existing boundaries were no longer serving it.
Key terms: layered monolith, technical debt, Article, HTTP serialization, database mapping, business validation, Spring context
2.2 How a request travels through the hexagon
Traces an article-creation request through WriteFlow’s hexagon and shows how inward-pointing dependencies keep the core separate from HTTP and infrastructure.
- Inbound request translation: Trace how ArticleController turns an HTTP POST containing JSON into a CreateArticleCommand and invokes the CreateArticleUseCase input port without passing HTTP details into the core.
Why it matters: This boundary keeps HTTP-specific data out of article-creation logic. - Handler and outbound work: Describe how CreateArticleHandler orchestrates author lookup, validation, valid Article creation, and persistence by calling output-port interfaces that secondary adapters implement.
Why it matters: The handler can coordinate the use case without being tied to a particular author service or database. - Typed result and HTTP response: Explain how the handler’s Either<Error, Void> result returns to the controller, which maps success or a specific failure to an HTTP response.
Why it matters: The core can express an outcome without deciding which HTTP status the client receives. - Inward dependency rule: Explain why dependencies point inward even when request and result data travel across the boundary: the controller and secondary adapters depend on port interfaces, while the core depends on no outside implementation.
Why it matters: The dependency direction is the rule that preserves the hexagon’s independence as infrastructure changes.
Key terms: ArticleController, REST adapter, CreateArticleCommand, CreateArticleUseCase, input port, CreateArticleHandler, Author, Article, output port, secondary adapter
2.3 Reusable components: What you get for free
This section explains how infrastructure-independent handlers and ports can be reused by changing adapters.
- Core Reuse Through Adapters: Explain why a handler and its ports can serve different delivery channels, persistence technologies, or products without changing the core. Describe WriteFlow's REST API and Kafka consumer example.
Why it matters: It shows why separating the core from infrastructure pays off when an application needs another way to receive requests.
Key terms: handler, ports, adapters, CreateArticleUseCase, core
2.3.1 How these components compare to what you already know
This section connects familiar layered-architecture components to their hexagonal counterparts and explains why the key change is who defines the repository interface.
- Repository interface ownership and inversion: Distinguish the repository interface's location in a typical layered architecture from its ownership in hexagonal architecture, and explain what that reversal enables.
Why it matters: Interface ownership is what lets you change or fake infrastructure without changing the business logic.
Key terms: layered architecture, repository interface, core, adapter, Dependency Inversion Principle
2.3.2 Choosing the right component for your use case
This section gives a decision-based guide to placing logic in the core or adapters, defining output ports, and checking whether infrastructure has leaked inward.
- Decision ownership across components: Distinguish business decisions that belong in a domain entity or handler from external-facing decisions in a primary adapter and infrastructure decisions in a secondary adapter.
Why it matters: Placing each decision with the component responsible for it keeps business rules inside the core. - Output port business language: Explain that an output port states what the handler needs in domain language while leaving the means of fulfillment to the secondary adapter.
Why it matters: A port named for the need rather than the technology can remain stable when its implementation changes. - Adapter replacement placement test: Apply the adapter-replacement question to check whether logic has drifted toward infrastructure.
Why it matters: This quick check helps reveal infrastructure coupling when a component's placement is uncertain.
Key terms: domain entity, handler, primary adapter, secondary adapter, domain invariants, output port, domain language, abstraction is leaking, adapter, infrastructure
2.4 The WriteFlow migration: A step-by-step map
Introduces WriteFlow’s five-phase migration map and the rule that kept the migration safe: deliver working software in each phase rather than rewrite everything at once.
- Incremental migration discipline: Explain why WriteFlow avoided a big-bang rewrite: each phase delivered working software, and the old and new paths ran in parallel until the new path was proven.
Why it matters: This rule explains how the team could change the architecture without betting the whole system on a single rewrite.
Key terms: big bang rewrite, old path, new path
2.4.1 Phase 1: Extract the domain
Phase 1 identifies WriteFlow’s scattered article-validity rules and extracts them into a framework-free domain without reducing entities to data-only shells.
- Framework-free business rule extraction: Explain how to find WriteFlow’s domain logic and decide what belongs in the extracted domain package: look for rules about article validity wherever they currently live, then separate those rules from framework dependencies.
Why it matters: This test helps you find business rules even when the existing code has mixed them with framework concerns. - Behaviorful domain entities: Explain why extracting fields and getters alone is a trap: a domain entity must contain behavior that enforces its business invariants, rather than merely carry data.
Why it matters: Moving data without its rules would leave the new domain unable to protect article validity.
Key terms: business rules, domain, framework dependencies, ArticleService, ArticleController, JPA lifecycle callbacks, anemic shells, domain entity, invariants
2.4.2 Phase 2: Define the ports
Phase 2 makes WriteFlow’s implicit dependencies explicit as core-owned ports named for business collaborations rather than technologies or individual database operations.
- Core-owned input and output ports: Explain how defining ports replaces WriteFlow’s direct calls with interfaces owned by the core: output ports for what the core needs from outside and an input port for what a controller needs from the core.
Why it matters: Explicit, core-owned interfaces show which collaborations the application depends on without making the core name their implementations. - Business-language port names: Apply the section’s naming check: identify technology words in a port name and explain why the port should instead be named in domain language.
Why it matters: A business-language name keeps the interface focused on the collaboration rather than its current technology. - Collaboration-sized port boundaries: Explain why WriteFlow’s first attempt at one output port per repository method was too fine-grained and state the section’s preferred level of abstraction.
Why it matters: Choosing a collaboration-sized port avoids carrying database-operation boundaries into the core.
Key terms: input ports, output ports, ArticleRepository, AuthorOutputPort, CreateArticleUseCase, domain language, technology word, infrastructure details, collaboration surface, use case
2.4.3 Phase 3: Wrap existing code as facade adapters
Phase 3 introduces facade adapters so WriteFlow can use new ports while keeping existing code in place and checking the new path against the old one.
- Facade adapters around existing code: Describe how WriteFlow puts its existing repository and controller behind the new port-based boundaries without deleting them. Explain that the repository adapter implements the output port and delegates to the old JPA repository, while the REST adapter maps requests to commands and invokes the input port.
Why it matters: The team can introduce port boundaries without replacing working infrastructure all at once. - Parallel path verification: Explain why WriteFlow runs the old direct-call path and the new port-mediated path at the same time and compares their outputs before deleting code.
Why it matters: Comparing both paths gives the team evidence that the new route behaves correctly before they remove the old one. - Facade adapter logic boundary: Explain why a facade adapter should only translate between the new interface and old code, and where business logic found in the controller should go instead.
Why it matters: Keeping facades thin avoids creating a second home for business rules during migration.
Key terms: facade adapter, ArticleRepository output port, CreateArticleUseCase input port, CreateArticleCommand, old direct-call path, new port-mediated path, safe migration corridor, translation layer, business logic, handler
2.4.4 Phase 4: Refactor into handlers
Phase 4 moves WriteFlow’s orchestration from a service into a framework-free handler that depends on ports, making it fast to unit-test while exposing the risk of bypassing those ports.
- Port-based handler extraction: Describe how WriteFlow extracted CreateArticleHandler from ArticleService and kept its orchestration behind port interfaces rather than framework dependencies.
Why it matters: Moving orchestration behind ports lets the application logic stand apart from its infrastructure. - Direct handler test criterion: Explain how a direct unit test with mocked ports checks whether the handler is clean, and why that test can run quickly.
Why it matters: The direct-construction test makes an unwanted infrastructure dependency easy to spot. - Fake hexagonal dependency trap: Distinguish genuine port-based dependency from the fake hexagonal pattern in which a handler calls an adapter directly.
Why it matters: The boundary only protects the core when code actually depends on the port instead of its adapter.
Key terms: CreateArticleHandler, ArticleService, CreateArticleUseCase, ArticleRepository, AuthorOutputPort, output port, handler, ports, Spring context, mock implementations
2.4.5 Phase 5: Replace and verify
Phase 5 replaces WriteFlow’s temporary facade adapters with port-based adapters while checking that the core remains independent of adapter technology.
- Port-based adapter replacement: Explain how WriteFlow replaces facade adapters one at a time with adapters built against the same port, changing configuration rather than the handler, domain entity, or port.
Why it matters: A port makes an adapter replacement a local change instead of a project-wide rewrite. - Adapter swap boundary verification: Describe how to check an adapter swap for inward dependency leaks and why WriteFlow uses ArchUnit rather than relying on developers to notice them.
Why it matters: A configuration-only swap is not genuinely clean if the core quietly acquires an infrastructure dependency.
Key terms: facade adapters, ArticleRepository port, configuration toggle, ArchUnit, core package, dependency leak, JPA import
2.4.6 Making the case: The stakeholder conversation
This section explains how to make a credible case for the WriteFlow migration and when to propose it.
- Evidence for migration approval: Explain why a working prototype makes a stronger case for migration approval than an architecture diagram, and what the prototype should demonstrate.
Why it matters: A small working example gives stakeholders evidence of the migration's value before they commit time to it. - Timing of the migration proposal: Explain when to propose the migration and what to do if the system is already in crisis.
Why it matters: Choosing a stable moment gives the team room to migrate incrementally rather than compound an existing crisis.
Key terms: working prototype, one use case, adapter swap, stabilize first, incremental change, accidental complexity
2.4.7 What the WriteFlow team got wrong
The section uses two WriteFlow migration mistakes to show why business validation belongs in the domain and output ports should express the core’s needs rather than copy infrastructure.
- Domain Ownership of Validation: Explain why putting article title validation in a REST adapter caused inconsistent rules across WriteFlow’s REST, Kafka, and GraphQL adapters, and why the team moved that validation into the domain entity.
Why it matters: Keeping a business rule in the domain prevents each entry point from developing its own version. - Use Case Shaped Output Ports: Explain why copying JPA repository methods into an output port made WriteFlow’s port hard to use with Elasticsearch, and how the team reframed the port around what handlers needed.
Why it matters: A port designed around the handler’s needs is less likely to obstruct a change in infrastructure.
Key terms: business logic in adapters, article title validation, Always-Valid Domain Model, domain entity, output ports, JPA repository, ArticleRepository port, Elasticsearch, use-case needs
2.5 Summary
Where this is used later
- Why mapping exists: The boundary tax (chapter 5) · The mixed concerns provide context for why separating boundary representations entails mapping.
- What an input adapter is (and is not) (chapter 5) · Identifies the role of a driving input adapter.
- What lives inside the domain layer (chapter 3) · The domain's place within the hexagon.
- The use case contract (chapter 4) · The path a request takes through the hexagon.
- Orchestration without business logic leakage (chapter 4) · Develops the handler’s orchestration role.
- What an output adapter is (and is not) (chapter 5) · Develops how output adapters serve the core.
- Error mapping: from Error hierarchy to HTTP responses (chapter 5) · Develops the mapping from core errors to HTTP responses.
- Dependency rules: Who may import whom (chapter 7) · Enforces dependency boundaries as architecture rules.
Concepts explained in this chapter
- outbound portAn application-facing boundary that declares a service the application requires from an external system.
- hexagonal architectureAn application design pattern that isolates the application core behind ports and connects external technologies through adapters.
- driven adapterAn adapter that implements an output port and translates application requests into interactions with an external system.
- primary portAn interface exposing an application operation that an external caller can invoke.
- entityA domain object with an identity whose state and invariants are governed by domain rules.
- REST controllerAn adapter that accepts REST requests and translates them into calls to application input ports.
- application coreThe central part of an application containing its domain and application logic while remaining independent of external technologies.
- handlerA handler is an application component that processes a request and coordinates the interactions needed to fulfill it.
- EitherEither is a functional data type representing one of two alternatives, commonly a failure value or a successful result.
- application serviceA service that coordinates an application use case and its domain operations without containing infrastructure concerns.
- business logicThe rules and processing that express an application's business behavior independently of external technologies.
- invariantA condition that must remain true for a domain object or business state to be valid.
- adapterAn adapter that connects an application to an external service through an API.
- driving adapterA primary adapter translates an external trigger into a call to an application input port.
- ArchUnitArchUnit is a Java library for expressing and testing architectural constraints in code.
- portAn application boundary interface through which external actors or technologies interact with the application core.
- dependency inversionA design principle stating that high-level and low-level components should depend on abstractions rather than concrete implementation details.
- always-valid domain modelA domain-modeling approach that prevents objects from representing states that violate their invariants.
- domain validationBusiness invariant validation checks whether domain data and operations satisfy the rules that must remain true for valid business state.
- domain layerA software layer that contains business concepts, rules, and behavior independently of infrastructure frameworks.
- factoryA construction abstraction that creates objects while encapsulating their creation logic.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
