liveBook · Manning

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

What you will learn in chapter 2 of Clean Applications with Hexagonal Architecture

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

What it builds on

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Concepts explained in this chapter

← Chapter 1: Taming complexity with hexagons Chapter 3: Building the domain core →

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.