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.
After this chapter you will be able to
- Control at the integration boundary. Explain why WriteFlow cannot control an external system’s timing or view of events, even though its domain still decides what is allowed. Describe the questions the team asks for each interaction.
- Inbound and outbound directions. Distinguish inbound from outbound integration by who starts the interaction, which adapter handles it, and whether the external system is a driving or driven actor.
- Waiting and failure responsibilities. Describe who waits and who owns the response or failure handling in inbound and outbound synchronous interactions, and state the external coordinator’s responsibility in an orchestrated integration.
- Request and fact meanings. Distinguish a request, which asks another system to do work or provide information, from a fact, which reports something that has already happened. Explain why the CMS asking WriteFlow to reopen an article is a request.
- Meaning versus integration mode. Explain why classifying a message as a request or fact does not by itself determine how it travels. Describe the timing and recovery questions used to choose a mode, including the limit of handler-level sequencing.
- Integration mode responsibilities. Distinguish synchronous calls, events, and external orchestration by who waits and who is responsible for continuing the work. Explain why waiting ties progress to another system’s availability, while handing work off allows later action and may require recovery after failure.
- Synchronous call flow. Trace a synchronous call through WriteFlow in either direction and explain why the caller waits.
- Need for an immediate answer. Explain why the CMS interaction is synchronous in the example and what change would call for an asynchronous request instead.
- Event Flow Across Boundaries. Trace how an integration event leaves a hexagon and how an event from another system enters it.
- Subscriber Independence and Delivery Costs. Explain the independence event-driven integration gives publishers and the delivery uncertainties consumers must handle.
- Internal and external orchestration. Distinguish a handler’s internal orchestration from an external coordinator’s orchestration, and explain why a sequence involving a second service no longer fits one local transaction.
- Saga and compensation. Explain why cross-service steps become a durable saga of local transactions and business compensations rather than one atomic transaction.
- External coordinator responsibilities. Describe what the external coordinator owns, how it calls the hexagon, and the operational cost of using it.
- Request and fact timing. Distinguish a request that needs a synchronous call from a fact that belongs in an event, based on whether the use case must wait for a result.
- Process lifetime and coordination. Explain when steps remain within a handler, when reactions to events suffice, and when a process needs external orchestration.
- Domain authority across modes. Explain why changing integration mode does not change who decides whether an action is allowed, using WriteFlow’s article-reopening request as an example.
- Application ownership of outgoing facts. Distinguish a domain event from the application layer’s decision to publish an integration event, including who chooses its external shape.
- Adapter mechanics and policy boundaries. Describe what adapters own at an external boundary and distinguish their mechanics from application and domain policies.
- Contract map structure. Describe how a contract map represents WriteFlow’s external architecture: the hexagon and its neighbors, with one line per interaction recording direction, request-or-fact intent, mode, and contract ownership.
- Owned and consumed contracts. Distinguish contracts WriteFlow publishes and owns from contracts it consumes, and explain why owned contracts must remain stable while changes to consumed contracts are absorbed in adapters.
What it builds on
- Core concepts: Ports and adapters (chapter 1) · The hexagon’s boundary separates the core from its external interactions.
- Input adapters: Driving the hexagon (chapter 5) · Input adapters receive requests that drive use cases.
- Output adapters: Serving the hexagon (chapter 5) · Output adapters serve needs initiated by the hexagon.
- Domain events vs. integration events (chapter 6) · The distinction between domain events and integration events.
- The outbox pattern: A brief introduction (chapter 6) · The earlier introduction to the outbox pattern.
- Publishing: The handler at the heart of the chapter (chapter 9) · The handler’s local publish path.
- Transactionality: Boundaries the framework resolves (chapter 6) · The limits of a local transaction boundary.
- What an input adapter is (and is not) (chapter 5) · Input adapters as a way for outside actors to drive the hexagon.
Section by section
Introduction
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.
- Control at the integration boundary: Explain why WriteFlow cannot control an external system’s timing or view of events, even though its domain still decides what is allowed. Describe the questions the team asks for each interaction.
Why it matters: These questions make assumptions about an external interaction visible before the team chooses how to integrate it. - Shared ownership of integration decisions: Explain why the use-case, integration, and external-contract stakeholders agree on what must happen now or later and who owns each contract before implementation.
Why it matters: Agreement on timing and ownership keeps an integration from relying on conflicting assumptions. - New and legacy starting points: Distinguish how a team starts integration design for a new hexagon from how it starts with a legacy system.
Why it matters: The right starting point helps a team design a new boundary or make an existing one visible.
Key terms: boundary, domain, contract map, interaction’s mode, use case, integration, external contract, ownership, new hexagon, legacy system
10.1 Two directions at one boundary
This section shows how to identify who starts each WriteFlow integration and use that direction to locate the adapter, name the external actor’s role, and assign response and failure responsibilities.
- Inbound and outbound directions: Distinguish inbound from outbound integration by who starts the interaction, which adapter handles it, and whether the external system is a driving or driven actor.
Why it matters: Identifying the initiator tells you which side of the hexagon needs an adapter without mistaking every outbound interaction for an event. - Roles assigned per interaction: Explain why the same external system can be a driving actor in one interaction and a driven actor in another, without treating direction as a permanent property of the system.
Why it matters: Classifying each exchange separately keeps a two-way relationship from being forced into one adapter role. - Waiting and failure responsibilities: Describe who waits and who owns the response or failure handling in inbound and outbound synchronous interactions, and state the external coordinator’s responsibility in an orchestrated integration.
Why it matters: Direction reveals where waiting and failure responsibility sit before an integration mode is selected.
Key terms: inbound integration, outbound integration, input adapter, output adapter, driving actor, driven actor, interaction, synchronous interactions, timeout, retries
10.2 What crosses the boundary: Requests and facts
The section distinguishes requests from facts in WriteFlow’s external messages, then explains why message meaning and integration mode are separate decisions.
- Request and fact meanings: Distinguish a request, which asks another system to do work or provide information, from a fact, which reports something that has already happened. Explain why the CMS asking WriteFlow to reopen an article is a request.
Why it matters: Classifying the message by meaning is the first decision at an external boundary. - Request handling at the boundary: Trace how the section’s direct outbound request uses a handler, output port, and adapter, and describe how an inbound request reaches a handler. State where direct-call mechanics and failures belong.
Why it matters: It keeps communication mechanics out of the use case while showing how requests enter and leave the hexagon. - Facts as external events: Describe how WriteFlow communicates a fact and why its validity does not depend on a subscriber. Relate an outbound fact to an integration event.
Why it matters: A reported event can inform other systems without making WriteFlow wait for or depend on particular listeners. - Meaning versus integration mode: Explain why classifying a message as a request or fact does not by itself determine how it travels. Describe the timing and recovery questions used to choose a mode, including the limit of handler-level sequencing.
Why it matters: It prevents the message’s meaning from being mistaken for a fixed transport or sequencing choice.
Key terms: request, fact, handler, output port, output adapter, input adapter, command, query, event, integration event
10.3 The three integration modes
Introduces three ways systems communicate across a boundary, distinguished by who waits and who continues the work.
- Integration mode responsibilities: Distinguish synchronous calls, events, and external orchestration by who waits and who is responsible for continuing the work. Explain why waiting ties progress to another system’s availability, while handing work off allows later action and may require recovery after failure.
Why it matters: The distinction helps you choose whether another system must answer now, can act later, or needs a coordinator to track a longer process.
Key terms: synchronous call, event, external orchestration, coordinator
10.3.1 Synchronous calls
This section explains how synchronous calls cross WriteFlow’s boundary, when their wait is necessary, and what that wait costs.
- Synchronous call flow: Trace a synchronous call through WriteFlow in either direction and explain why the caller waits.
Why it matters: Following the call in both directions makes the wait—and who bears it—clear. - Need for an immediate answer: Explain why the CMS interaction is synchronous in the example and what change would call for an asynchronous request instead.
Why it matters: Whether the caller needs the answer to continue is the deciding question in this example. - Cost of waiting: Explain the time coupling of a synchronous call and the limit of adapter mitigations.
Why it matters: The cost of waiting matters even when a direct call is the right choice.
Key terms: synchronous call, input adapter, output port, output adapter, handler, CMS, WriteFlow’s decision, synchronous, asynchronous request flow, coupling in time
10.3.2 Event-driven integration
Event-driven integration publishes facts across a hexagon’s boundary, allowing independent reactions while accepting delayed and potentially repeated delivery.
- Event Flow Across Boundaries: Trace how an integration event leaves a hexagon and how an event from another system enters it.
Why it matters: The direction of the event determines which adapter connects it to the hexagon. - Durable Outbox Handoff: Explain why WriteFlow records an event in an outbox alongside the state change.
Why it matters: The outbox lets WriteFlow retain an event for later delivery without holding up the handler. - Subscriber Independence and Delivery Costs: Explain the independence event-driven integration gives publishers and the delivery uncertainties consumers must handle.
Why it matters: This trade-off helps you judge when independent subscribers are worth delayed and uncertain delivery.
Key terms: integration event, output adapter, input adapter, use case invocation, outbox, durable record, same transaction, state change, subscribers, eventually consistent
10.3.3 Orchestrated integration
This section explains when a sequence must move beyond a single hexagon into durable external orchestration, and how the coordinator works with the hexagon.
- Internal and external orchestration: Distinguish a handler’s internal orchestration from an external coordinator’s orchestration, and explain why a sequence involving a second service no longer fits one local transaction.
Why it matters: It helps you recognize when a local handler remains sufficient and when a cross-service process needs another owner. - Saga and compensation: Explain why cross-service steps become a durable saga of local transactions and business compensations rather than one atomic transaction.
Why it matters: It explains how a multi-service operation can recover without claiming an atomic commit that it does not have. - External coordinator responsibilities: Describe what the external coordinator owns, how it calls the hexagon, and the operational cost of using it.
Why it matters: It keeps long-running process control outside the hexagon without moving business decisions out of it. - Business and technical processes: Distinguish business-visible processes from technical service coordination and describe how they can nest.
Why it matters: The distinction clarifies whether the coordinated sequence is part of business policy or an implementation detail. - Delayed and repeated updates: Explain what eventual consistency means for consumers after a successful write.
Why it matters: It prevents a successful local write from being mistaken for immediate agreement across systems.
Key terms: internal orchestration, external orchestration, handler, external coordinator, two-phase commit, eventual consistency, local transactions, compensating action, saga, driving actor
10.4 Choosing a mode
This section explains how to choose an integration mode for each boundary-crossing interaction based on when an answer is needed and whether a process needs durable coordination.
- Request and fact timing: Distinguish a request that needs a synchronous call from a fact that belongs in an event, based on whether the use case must wait for a result.
Why it matters: The need to wait for an answer is the first test for choosing a boundary interaction. - Process lifetime and coordination: Explain when steps remain within a handler, when reactions to events suffice, and when a process needs external orchestration.
Why it matters: A process does not need an external coordinator merely because it has several steps. - Per-interaction mode selection: Describe why a system can use several modes and how WriteFlow's publish path combines an inbound request, local handler steps, and a published fact without a coordinator.
Why it matters: Choosing per interaction lets one use case combine immediate work with later reactions. - Mode selection pitfalls: Explain the availability cost of defaulting to synchronous calls and why a coordinator should own order rather than every notification or business decision.
Why it matters: These pitfalls explain why the easiest familiar mechanism may be the wrong choice.
Key terms: request, fact, synchronous call, event, internal orchestration, external orchestration, handler, coordinator, per interaction, WriteFlow
10.5 The rules that survive every mode
The section assigns boundary decisions to the domain, application layer, and adapters regardless of integration mode, and explains how a correlation ID can cross without exposing its contents to the core.
- Domain authority across modes: Explain why changing integration mode does not change who decides whether an action is allowed, using WriteFlow’s article-reopening request as an example.
Why it matters: A new way of connecting systems must not become a way around business rules. - Application ownership of outgoing facts: Distinguish a domain event from the application layer’s decision to publish an integration event, including who chooses its external shape.
Why it matters: It keeps decisions about external publication out of the domain model. - Adapter mechanics and policy boundaries: Describe what adapters own at an external boundary and distinguish their mechanics from application and domain policies.
Why it matters: Separating mechanics from policy makes it possible to name who owns each boundary decision. - Opaque correlation ID envelope: Trace how a correlation ID passes through the hexagon without the application layer or domain inspecting it.
Why it matters: Interactions can be linked to their outcomes without making the core understand transport metadata.
Key terms: domain, invariants, use case, Either, application layer, domain event, integration event, adapter, retries, timeouts
10.6 An example of external architecture for WriteFlow
This section turns WriteFlow’s external interactions into a contract map that shows how it communicates with neighbors and who owns each contract.
- Contract map structure: Describe how a contract map represents WriteFlow’s external architecture: the hexagon and its neighbors, with one line per interaction recording direction, request-or-fact intent, mode, and contract ownership.
Why it matters: The map makes the system’s external relationships explicit before they are buried in adapters. - Owned and consumed contracts: Distinguish contracts WriteFlow publishes and owns from contracts it consumes, and explain why owned contracts must remain stable while changes to consumed contracts are absorbed in adapters.
Why it matters: Ownership tells the team which changes could break its neighbors and which changes an adapter should contain. - WriteFlow map in practice: Apply the contract-map format to the partner CMS interaction and describe when the map should be created and updated.
Why it matters: A current map lets a new team member see who interacts with WriteFlow, how, and under whose contract.
Key terms: external architecture, contract map, direction, request, fact, mode, owned contracts, consumed contracts, adapter, ArticleApproved
10.7 Summary
Where this is used later
- (chapter intro) (chapter 11) · The boundary between communicating hexagons.
- Bounding the availability cost (chapter 11) · The idea of synchronous calls between contexts.
Concepts explained in this chapter
- integration eventA published event contract representing an occurrence in a stable form suitable for consumers across system boundaries.
- orchestrationThe coordination of collaborators to complete an application operation without owning the underlying business rules.
- integration modeAn integration mode is a way for work or information to cross an architectural boundary, distinguished by waiting and responsibility for continuing work.
- factA statement of something that has happened, which other components may react to later.
- contract mapA diagram that shows an application’s neighboring systems and records the direction, intent, mode, and ownership of each interaction contract.
- synchronous callA synchronous call is an interaction in which the caller waits for the called system to return an answer.
- coordinatorA software component that coordinates interactions among other components or processes.
- driven actorAn external system that an application calls or otherwise causes to act during an interaction.
- driver actorAn external system or user that initiates an interaction by calling into an application.
- adapterAn adapter that connects an application to an external service through an API.
- application layerA software layer that coordinates application operations and use cases above the domain layer.
- outbox patternA pattern that stores a message in the same transaction as a business change so it can be published reliably afterward.
- system boundaryA structural separation that defines permitted responsibilities and dependencies between parts of a software system.
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.
