liveBook · Manning

What you will learn in Clean Applications with Hexagonal Architecture

Building maintainable microservices and modular monoliths

by Enrique Medina Montenegro · Manning Early Access Program (MEAP)

Chapter by chapter

Chapter 1: Taming complexity with hexagons

The introduction explains how hard-wired dependencies create accidental complexity and presents hexagonal architecture as a way to contain the effects of change.

1.1 What is hexagonal architecture · 1.1.1 Core concepts: Ports and adapters · 1.1.2 The secret sauce: Dependency inversion · 1.2 Why hexagonal architecture matters · 1.2.1 An uncomfortable truth · 1.2.2 The illusion of decoupling · 1.2.3 Less of a revelation, more of a confirmation · 1.2.4 A pattern that changed everything · 1.2.5 Comparison with other patterns · 1.2.6 When NOT to use hexagonal architecture · 1.3 How hexagonal architecture works · 1.3.1 Key Takeaways · 1.4 What you need to get started · 1.5 How this book teaches hexagonal architecture · 1.6 Summary

What you learn in chapter 1 →

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.

2.1 Meet WriteFlow: The system we will migrate · 2.2 How a request travels through the hexagon · 2.3 Reusable components: What you get for free · 2.3.1 How these components compare to what you already know · 2.3.2 Choosing the right component for your use case · 2.4 The WriteFlow migration: A step-by-step map · 2.4.1 Phase 1: Extract the domain · 2.4.2 Phase 2: Define the ports · 2.4.3 Phase 3: Wrap existing code as facade adapters · 2.4.4 Phase 4: Refactor into handlers · 2.4.5 Phase 5: Replace and verify · 2.4.6 Making the case: The stakeholder conversation · 2.4.7 What the WriteFlow team got wrong · 2.5 Summary

What you learn in chapter 2 →

Chapter 3: Building the domain core

The introduction argues that WriteFlow’s migration should begin with a framework-independent domain core whose business rules prevent invalid states.

3.1 What lives inside the domain layer · 3.2 Three principles that shape the domain · 3.3 The Always-Valid Domain Model · 3.3.1 What not to do: Validation after construction · 3.3.2 The recommended approach: validateThenCreate · 3.3.3 An alternative: canBeCreated · 3.3.4 A note on records · 3.4 Value objects: Making implicit concepts explicit · 3.5 Domain services · 3.6 Factories · 3.7 Model identity: Filling the gap · 3.8 Two kinds of validation · 3.8.1 Input validation with the Validation monad · 3.9 Guard clauses · 3.10 Summary

What you learn in chapter 3 →

Chapter 4: The honest hexagon: Use cases, commands, and the case against exceptions

Introduces the application layer’s coordinating role and explains why use case contracts should make failure explicit without changing what commands return on success.

4.1 The use case contract · 4.1.1 Input ports: The hexagon's public API · 4.1.2 The anatomy of a use case · 4.2 The incomplete contract · 4.2.1 The cost of using exceptions for expected failures · 4.2.2 The hidden cost in a hexagonal architecture · 4.2.3 A deliberately provocative question · 4.3 Either: An honest signature · 4.3.1 What Either says that the void did not · 4.3.2 The Error hierarchy · 4.3.3 Returning multiple validation failures at once · 4.3.4 Commands and queries as typed input · 4.4 The Application handler · 4.4.1 From use case interface to handler implementation · 4.4.2 Orchestration without business logic leakage · 4.4.3 Cross-cutting concerns at the boundary · 4.5 The command bus · 4.5.1 Why a bus? From one handler to many · 4.5.2 The Command Bus in the Architecture Kernel · 4.5.3 Spring wiring: Handlers as beans · 4.5.4 Decorating the bus: Logging and metrics · 4.6 The query bus · 4.6.1 Queries are not commands · 4.6.2 QueryHandler and QueryBus · 4.6.3 CQS in practice · 4.7 Domain events: A first look · 4.7.1 When the primary task is done, then what? · 4.7.2 Generating events in the domain, publishing in the application layer · 4.7.3 Forward: The full event story · 4.8 Summary

What you learn in chapter 4 →

Chapter 5: Crossing the boundaries: Adapters, repositories, and the mapping problem

This introduction explains how input and output adapters connect WriteFlow’s completed application core to the outside world, and why repositories are an unusual kind of output port.

5.1 Input adapters: Driving the hexagon · 5.1.1 What an input adapter is (and is not) · 5.1.2 Error mapping: from Error hierarchy to HTTP responses · 5.2 Output adapters: Serving the hexagon · 5.2.1 What an output adapter is (and is not) · 5.2.2 Role interfaces versus header interfaces · 5.2.3 Implementing an external service adapter · 5.2.4 DTOs as the currency of the boundary · 5.3 Repositories: A privileged kind of output port · 5.3.1 Why repositories are different: Domain entities cross the boundary · 5.3.2 Repository interface design: read-side vs write-side · 5.3.3 Spring Data reinterpretation: Wrapping the framework · 5.3.4 Persistence mapping in practice · 5.4 The mapping problem: A journey toward full isolation · 5.4.1 Why mapping exists: The boundary tax · 5.4.2 Strategy 1: No mapping · 5.4.3 Strategy 2: One-way mapping · 5.4.4 Strategy 3: Two-way mapping · 5.4.5 Strategy 4: The full bridge · 5.4.6 Choosing a strategy: Trade-offs at a glance · 5.5 Summary

What you learn in chapter 5 →

Chapter 6: The running hexagon: From pieces to system

The introduction explains why WriteFlow’s independently built hexagonal components need runtime assembly to become a working application.

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

What you learn in chapter 6 →

Chapter 7: Enforcing the architecture as executable specification

The introduction explains why Maven module boundaries need ArchUnit tests to catch class-level architectural violations and keep WriteFlow’s intended architecture visible and enforceable.

7.1 Why tests, not just modules · 7.1.1 Where the tests live · 7.2 The configuration foundation · 7.2.1 Externalized properties · 7.2.2 WriteFlow's rule configuration · 7.3 Dependency rules: Who may import whom · 7.3.1 The shared kernel boundary · 7.3.2 The domain boundary · 7.3.3 The handler's wider scope · 7.3.4 The adapter inversion: No reaching into core · 7.4 Annotation rules: The right stereotype in the right place · 7.4.1 Forbidden annotations · 7.4.2 Required annotations · 7.4.3 The domain's allowlist · 7.5 Structural rules: Shape enforcement · 7.5.1 Ports must be interfaces · 7.5.2 Commands and queries must implement their marker · 7.5.3 The validateThenCreate contract · 7.5.4 No public default constructor · 7.5.5 Generic type validation on use cases · 7.6 Naming conventions: Making intent visible · 7.7 Executing the rules: The test suite · 7.7.1 The test class pattern · 7.7.2 WriteFlow's complete test inventory · 7.8 Living with violations: The freeze mechanism · 7.9 Summary

What you learn in chapter 7 →

Chapter 8: Testing the hexagon with behavioral verification

The introduction explains why structural checks of WriteFlow’s hexagon must be complemented by behavioral tests.

8.1 From shape to behavior · 8.2 The testing recipe · 8.2.1 The BDD contract · 8.2.2 Naming intent with @DisplayName · 8.2.3 The tooling foundation · 8.3 Commands and queries: Always the same test · 8.3.1 Testing valid command creation · 8.3.2 Testing the validation path · 8.3.3 The universal pattern · 8.4 Handlers: Mock ports, verify interactions · 8.4.1 The handler test scaffold · 8.4.2 Testing the happy path · 8.4.3 Testing the not-found path · 8.4.4 Testing the persistence failure path · 8.4.5 The universal pattern · 8.5 REST controllers: The input adapter recipe · 8.5.1 The controller test scaffold · 8.5.2 Testing the happy path · 8.5.3 Testing the bus failure path · 8.5.4 Testing a query endpoint · 8.5.5 The universal pattern · 8.6 Adapters with external dependencies · 8.6.1 Persistence adapters: Mocking the infrastructure layer · 8.6.2 Technology-specific adapters: Testing with real implementations · 8.6.3 External API adapters: Mocking construction · 8.6.4 HTTP adapters: MockRestServiceServer · 8.6.5 The heterogeneity principle · 8.7 What not to test · 8.8 Summary

What you learn in chapter 8 →

Chapter 9: Building WriteFlow: The complete implementation

The introduction explains how WriteFlow’s previously built parts will form a runnable application and why two consumers of one domain event run in different transaction phases.

9.1 What we are building · 9.2 The domain core · 9.2.1 Value objects: The smallest always-valid things · 9.2.2 The status: A two-state lifecycle · 9.2.3 The Article aggregate: Creation, reconstitution, and behaviour · 9.2.4 The domain event: A primitive-typed, cross-boundary contract · 9.2.5 What the domain guarantees · 9.3 The ports · 9.3.1 Commands and queries carry primitives, not domain types · 9.3.2 Input ports: The use cases the application offers · 9.3.3 The read-side DTO · 9.3.4 Output ports: What the application needs from the world · 9.3.5 The contracts are complete · 9.4 The handlers · 9.4.1 Creating a draft: The simplest handler · 9.4.2 Publishing: The handler at the heart of the chapter · 9.4.3 One event, two phases: The listeners · 9.4.4 Reading: The query handler · 9.4.5 The two paths at runtime · 9.5 Adapters: Wiring the core to the outside world · 9.5.1 The persistence adapter · 9.5.2 The transactional outbox · 9.5.3 The event bridge and the notification fake · 9.5.4 The REST driving adapter · 9.5.5 The edges are built, nothing is connected · 9.6 Assembly: The composition root · 9.6.1 The bootstrap class · 9.6.2 Wiring beans by stereotype, not by name · 9.6.3 Standing up the buses and registering handlers · 9.6.4 Profile and runtime configuration · 9.6.5 The application is whole · 9.7 Verification: Proving the hexagon holds · 9.7.1 Reusing the chapter 7 checker library · 9.7.2 Extending the library with a project-specific rule · 9.7.3 Behavioral tests: Applying the chapter 8 recipes · 9.7.4 The whole gate · 9.8 Summary

What you learn in chapter 9 →

Chapter 10: When hexagons talk: Integration modes and the external architecture

This introduction frames external integration as a set of boundary decisions that teams must make explicitly, whether designing a new hexagon or examining an existing system.

10.1 Two directions at one boundary · 10.2 What crosses the boundary: Requests and facts · 10.3 The three integration modes · 10.3.1 Synchronous calls · 10.3.2 Event-driven integration · 10.3.3 Orchestrated integration · 10.4 Choosing a mode · 10.5 The rules that survive every mode · 10.6 An example of external architecture for WriteFlow · 10.7 Summary

What you learn in chapter 10 →

Chapter 11: Synchronous boundaries: Anti-corruption layers and distributed read models

This introduction frames the model, availability, and data-ownership challenges of synchronous calls between bounded contexts.

11.1 Two hexagons, one call · 11.2 The anti-corruption layer · 11.3 Inbound: When the CMS calls WriteFlow · 11.4 Outbound: Translating into the neighbor's model · 11.5 Bounding the availability cost · 11.6 Reading data another context owns · 11.7 Choosing a read strategy · 11.8 The rules that hold at a synchronous boundary · 11.9 Summary

What you learn in chapter 11 →

Concepts explained in this book

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.