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.
After this chapter you will be able to
- Two adapter boundary roles. Distinguish input adapters, which translate external requests into commands and queries for the bus, from output adapters, which implement the ports handlers depend on. Explain that data crossing either boundary must be translated between different types.
- Input adapter boundary role. Explain where an input adapter sits and how it handles an external request. Describe how WriteFlow’s REST controller creates a command or query and sends it through the bus without exposing core internals to the client.
- Input adapter translation responsibilities. Describe how an input adapter receives an external request, turns it into a command or query for the bus, and translates the result into the delivery mechanism’s response format.
- Replaceable delivery mechanisms. Explain how REST, message, or CLI adapters can expose the same use case through the bus without changing its handler, commands, or domain model, and why that helps test the core.
- Error to HTTP boundary. Explain how the REST input adapter maps the application’s Error subtypes to HTTP responses without introducing HTTP or Spring types into the core. Give the WriteFlow examples of invalid requests, missing articles, and publication conflicts.
- Compile time mapping completeness. Explain why an exhaustive switch over the sealed Error hierarchy makes the mapper respond to newly added error subtypes.
- Output ports and adapters. Explain the relationship between output ports and output adapters, using WriteFlow’s persistence or event-publishing needs as an example.
- Output port implementation and translation. Explain that an output adapter implements a core-defined output port and translates between the port’s language and infrastructure-specific operations and errors.
- Core independence from output adapters. Explain why an output adapter can be replaced without changing code inside the hexagon.
- Consumer-Shaped Output Port Contracts. Distinguish a header interface, copied from an implementation’s API, from a role interface, defined by what the application core needs. Explain why the latter protects the core from infrastructure concerns.
- Technology-Neutral Port Vocabulary. Apply the section’s vocabulary test to an output port: identify parameters tied to one delivery technology and describe the same need in application terms, leaving delivery choices to the adapter.
- Notification adapter boundary. Explain how WriteFlow’s email adapter implements NotificationOutputPort, translating notification DTOs into an email operation without exposing that implementation to the core. Describe why Slack could replace email without changing the core or handler.
- Infrastructure failure boundary. Explain how the adapter reports an infrastructure failure through the application’s Error hierarchy while retaining the original exception details for operational diagnosis.
- Output Port DTO Contract. Explain that output ports ordinarily accept and return lightweight, immutable DTOs containing only the data the port needs, rather than domain entities; repositories are the stated exception.
- Repository boundary exception. Explain why a repository port accepts domain entities rather than DTOs, and how publishing an Article depends on that exception.
- Repository Boundary Exception. Distinguish the types that cross ordinary output ports from those that cross repository ports, and describe what each adapter translates.
- Repository Dependency Direction. Explain where the repository interface and implementation belong and why passing entities does not make the repository part of the domain layer.
- Repository method conventions. Distinguish repository methods by what they return and which handlers use them: writes accept domain entities, aggregate reads return domain entities, and display-oriented reads return DTOs or projections.
- Adapter wrapped persistence repository. Describe how the domain-owned ArticleRepository, adapter, and Spring Data repository relate in WriteFlow.
- Domain and persistence separation. Explain how JpaArticleRepository delegates mapping between Article and JpaArticle to ArticlePersistenceMapper, and why keeping these types distinct protects the domain model.
- Boundary Type Trade-Off. Explain why choosing types for data crossing hexagonal boundaries involves a trade-off between convenience and isolation, using WriteFlow’s article data as an example.
- Mapping and coupling trade-off. Explain the work mapping adds and the coupling it avoids when types cross boundaries without translation. Describe how sharing one type can turn a local change into changes elsewhere in the system.
- No Mapping Strategy. Describe how the no-mapping strategy uses the domain entity directly in the controller and repository, without separate DTOs, mappers, or persistence entities.
- Boundary Coupling Costs. Explain why using Article as the API and persistence model compromises the hexagon, and distinguish that coupling from the additional collapse caused by having no application layer.
- One-way mapping boundary. Describe how one-way mapping converts the domain entity to a DTO for data leaving the hexagon while using the domain entity itself for persistence.
- Two-way mapping boundaries. Trace where two-way mapping occurs in WriteFlow: the repository adapter maps between Article and JpaArticle, while the handler maps domain data to ArticleDTO for the outbound path.
- Full Bridge type boundaries. Explain that the Full Bridge uses a distinct type for each purpose and an explicit mapper at each boundary, rather than letting one type serve multiple layers. Identify the roles of requests, commands or queries, domain entities, persistence entities, DTOs, and responses.
- Domain-dependent read query. Explain why the publication-readiness GET query loads the Article aggregate and invokes domain behaviour instead of answering from stored fields alone, while remaining read-only.
- Mapping strategy trade-offs. Justify choosing two-way mapping as a pragmatic default and the Full Bridge for a public, multi-team, or long-lived application. Explain why the section rejects no mapping at all.
What it builds on
- The command bus (chapter 4) · The bus routes commands to handlers.
- The Application handler (chapter 4) · Handlers depend on ports to carry out use cases.
- What lives inside the domain layer (chapter 3) · Introduces the domain layer and its model.
- Core concepts: Ports and adapters (chapter 1) · Adapters connect outside interactions to ports.
- The Error hierarchy (chapter 4) · The typed Error hierarchy that the adapter maps.
- Orchestration without business logic leakage (chapter 4) · Handlers orchestrate work using dependencies rather than taking on infrastructure responsibilities.
- The secret sauce: Dependency inversion (chapter 1) · Introduces dependency inversion.
- The Always-Valid Domain Model (chapter 3) · Introduces domain models whose validity must be preserved.
Section by section
Introduction
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.
- Two adapter boundary roles: Distinguish input adapters, which translate external requests into commands and queries for the bus, from output adapters, which implement the ports handlers depend on. Explain that data crossing either boundary must be translated between different types.
Why it matters: These two roles explain how the core can interact with external systems without taking on their responsibilities. - Repositories as privileged output ports: Explain why repositories are output ports that, unlike other ports described here, may work directly with domain entities: their job is to persist and reconstitute domain state.
Why it matters: The exception explains why a repository boundary can involve domain entities without ceasing to be an output port.
Key terms: input adapters, output adapters, commands and queries, bus, port interfaces, repositories, output ports, domain entities, persist and reconstitute domain state
5.1 Input adapters: Driving the hexagon
This section introduces input adapters as the outside components that turn external requests into commands or queries for the application core.
- Input adapter boundary role: Explain where an input adapter sits and how it handles an external request. Describe how WriteFlow’s REST controller creates a command or query and sends it through the bus without exposing core internals to the client.
Why it matters: This boundary lets clients make requests without depending on the application’s internal components.
Key terms: input adapter, hexagon boundary, command, query, REST controller, bus
5.1.1 What an input adapter is (and is not)
This section defines input adapters as translators at the hexagon’s boundary, explains why delivery mechanisms can change without changing the core, and shows how to choose among them.
- Input adapter translation responsibilities: Describe how an input adapter receives an external request, turns it into a command or query for the bus, and translates the result into the delivery mechanism’s response format.
Why it matters: This boundary keeps delivery details out of the use case and business decisions out of the adapter. - Replaceable delivery mechanisms: Explain how REST, message, or CLI adapters can expose the same use case through the bus without changing its handler, commands, or domain model, and why that helps test the core.
Why it matters: A new way to reach a use case need not force changes to, or infrastructure into tests of, the application core. - Delivery mechanism selection: Distinguish when HTTP, message-consumer, and CLI input adapters fit, using the section’s interaction and operational criteria.
Why it matters: Keeping mechanisms outside the core still leaves an important choice about how people and systems interact with the application.
Key terms: input adapter, command or query, bus, handler, validateThenCreate, input adapters, delivery mechanism, application core, HTTP adapter, message consumer
5.1.2 Error mapping: from Error hierarchy to HTTP responses
This section explains how a REST input adapter turns the core’s typed errors into HTTP responses while keeping HTTP concerns outside the application core.
- Error to HTTP boundary: Explain how the REST input adapter maps the application’s Error subtypes to HTTP responses without introducing HTTP or Spring types into the core. Give the WriteFlow examples of invalid requests, missing articles, and publication conflicts.
Why it matters: The API can offer predictable HTTP responses without making the core depend on HTTP. - Compile time mapping completeness: Explain why an exhaustive switch over the sealed Error hierarchy makes the mapper respond to newly added error subtypes.
Why it matters: New error categories cannot silently go without a mapping in an exhaustive switch. - Structured validation responses: Describe why a production REST adapter should turn validation errors into structured, adapter-specific details rather than relying on toString().
Why it matters: Clients can act on validation failures without depending on the core’s internal representation. - Grouped error status policy: Distinguish a group of errors with the same HTTP meaning from a mixed MultipleErrors group, and describe the adapter’s options for the latter.
Why it matters: A convenient error group should not conceal failures with different HTTP meanings.
Key terms: input adapter, Error hierarchy, ProblemDetail, RFC 9457, sealed Error hierarchy, exhaustive switch, validation errors, adapter-specific representation, code, field
5.2 Output adapters: Serving the hexagon
This section explains how infrastructure outside the hexagon implements core-owned output ports so WriteFlow handlers can use external capabilities without depending on their technologies.
- Output ports and adapters: Explain the relationship between output ports and output adapters, using WriteFlow’s persistence or event-publishing needs as an example.
Why it matters: This distinction lets you tell which contracts belong to the core and which implementations belong to infrastructure.
Key terms: output port, output adapter, handler, ArticleRepository, DomainEventPublisherOutputPort
5.2.1 What an output adapter is (and is not)
This section defines an output adapter’s responsibilities, its limits, and why the core can remain unchanged when infrastructure changes.
- Output port implementation and translation: Explain that an output adapter implements a core-defined output port and translates between the port’s language and infrastructure-specific operations and errors.
Why it matters: This keeps infrastructure details out of the port contract the core uses. - Business decisions stay outside adapters: Distinguish translation and delegation in an output adapter from decisions and validation performed elsewhere.
Why it matters: Keeping those responsibilities separate prevents infrastructure code from taking over application decisions. - Core independence from output adapters: Explain why an output adapter can be replaced without changing code inside the hexagon.
Why it matters: That dependency direction lets teams change external technology without rewriting the core.
Key terms: output adapter, output port interface, Error hierarchy, business logic, handler, command, translates and delegates, application core, port interface, hexagon
5.2.2 Role interfaces versus header interfaces
This section explains why output ports should express what the application core needs rather than mirror the technology an adapter uses.
- Consumer-Shaped Output Port Contracts: Distinguish a header interface, copied from an implementation’s API, from a role interface, defined by what the application core needs. Explain why the latter protects the core from infrastructure concerns.
Why it matters: The direction in which you design the port determines whether infrastructure choices leak into the core. - Technology-Neutral Port Vocabulary: Apply the section’s vocabulary test to an output port: identify parameters tied to one delivery technology and describe the same need in application terms, leaving delivery choices to the adapter.
Why it matters: Application vocabulary lets the delivery method change without making the core speak in email, HTTP, or database terms.
Key terms: output port, header interface, role interface, application core, adapter
5.2.3 Implementing an external service adapter
Shows how an external service adapter translates a core request into email delivery while keeping infrastructure details out of the core.
- Notification adapter boundary: Explain how WriteFlow’s email adapter implements NotificationOutputPort, translating notification DTOs into an email operation without exposing that implementation to the core. Describe why Slack could replace email without changing the core or handler.
Why it matters: This boundary lets notification technology change without changing the application’s request to send a notification. - Infrastructure failure boundary: Explain how the adapter reports an infrastructure failure through the application’s Error hierarchy while retaining the original exception details for operational diagnosis.
Why it matters: The application can keep a clean failure contract without depriving operators of information needed to diagnose incidents.
Key terms: NotificationOutputPort, NotificationTextDTO, NotificationTypeDTO, output adapter, Error hierarchy, infrastructure exception, diagnostic context
5.2.4 DTOs as the currency of the boundary
This section explains why DTOs, rather than domain entities, should carry data across output-port and adapter boundaries.
- Output Port DTO Contract: Explain that output ports ordinarily accept and return lightweight, immutable DTOs containing only the data the port needs, rather than domain entities; repositories are the stated exception.
Why it matters: A narrow data contract lets adapters do their work without becoming coupled to domain internals. - Adapter Response Firewall: Explain why an adapter such as a REST controller should return a DTO instead of a domain entity.
Why it matters: A DTO helps keep an API stable when the domain model changes.
Key terms: output port, DTO, domain entity, NotificationOutputPort, repository, REST controller, serialisation, API contract
5.3 Repositories: A privileged kind of output port
Explains why repositories, unlike other output ports, work directly with domain entities while keeping persistence translation outside the application core.
- Repository boundary exception: Explain why a repository port accepts domain entities rather than DTOs, and how publishing an Article depends on that exception.
Why it matters: It explains why repository ports have a different contract from other output ports. - Repository port and adapter roles: Describe where the repository port and its adapter live, and which side translates between domain entities and the persistence model.
Why it matters: This division lets the core request persistence without taking on persistence-model translation.
Key terms: repository, output port, domain entity, DTO, reconstitute domain state, aggregate, port interface, application core, adapter, persistence model
5.3.1 Why repositories are different: Domain entities cross the boundary
This section explains why repository ports, unlike other output ports, pass domain entities across the boundary while preserving dependency inversion.
- Repository Boundary Exception: Distinguish the types that cross ordinary output ports from those that cross repository ports, and describe what each adapter translates.
Why it matters: This distinction tells you which boundary may pass domain entities and where persistence mapping belongs. - In-Memory Collection Illusion: Explain why repositories make an exception for domain entities, using the handler’s save and read operations.
Why it matters: The collection-like contract explains why this port works with entities rather than DTOs. - Repository Dependency Direction: Explain where the repository interface and implementation belong and why passing entities does not make the repository part of the domain layer.
Why it matters: Passing domain entities through a repository does not require the core to depend on persistence technology.
Key terms: output port, repository, DTOs, domain entities, persistence-specific types, Domain-Driven Design, fully reconstituted Article entity, repository interface, adapter, dependency direction
5.3.2 Repository interface design: read-side vs write-side
This section defines repository method conventions for command and query consumers and explains when to split a repository interface.
- Repository method conventions: Distinguish repository methods by what they return and which handlers use them: writes accept domain entities, aggregate reads return domain entities, and display-oriented reads return DTOs or projections.
Why it matters: The method contract makes each repository consumer’s needs visible. - Repository interface granularity: Explain when a team might split one repository interface into focused interfaces and why doing so does not change the hexagonal structure.
Why it matters: A team can keep interfaces focused without treating every split as an architectural change.
Key terms: write-side methods, read-side methods, domain entities, DTOs, projections, command handlers, Interface Segregation Principle, focused interfaces, single adapter implementation
5.3.3 Spring Data reinterpretation: Wrapping the framework
This section explains why a domain repository should not extend Spring Data and how an adapter can wrap Spring Data without exposing it to the core.
- Spring Data boundary risk: Explain why extending a Spring Data repository interface from a domain port weakens the hexagonal boundary.
Why it matters: A repository interface can look like a port while still letting persistence concerns into the core. - Adapter wrapped persistence repository: Describe how the domain-owned ArticleRepository, adapter, and Spring Data repository relate in WriteFlow.
Why it matters: This arrangement lets the application use a domain-defined repository contract without depending on its persistence framework.
Key terms: header interface, domain port, JPA @Entity, ArticleRepository, SpringArticleRepository, adapter, Spring Data
5.3.4 Persistence mapping in practice
Shows how WriteFlow maps between domain and persistence entities to keep each suited to its own purpose.
- Domain and persistence separation: Explain how JpaArticleRepository delegates mapping between Article and JpaArticle to ArticlePersistenceMapper, and why keeping these types distinct protects the domain model.
Why it matters: The separation lets domain behaviour and persistence requirements evolve without making them the same model.
Key terms: JpaArticleRepository, ArticlePersistenceMapper, Article, JpaArticle, domain entity, persistence entity
5.4 The mapping problem: A journey toward full isolation
Introduces the mapping problem as a trade-off between reusing types across hexagonal boundaries and keeping those boundaries isolated.
- Boundary Type Trade-Off: Explain why choosing types for data crossing hexagonal boundaries involves a trade-off between convenience and isolation, using WriteFlow’s article data as an example.
Why it matters: This trade-off lets you discuss mapping choices in terms of both their work and their effect on isolation.
Key terms: boundary, mappers, coupling, isolation, DTO
5.4.1 Why mapping exists: The boundary tax
This section explains why mapping is worth its maintenance cost: it keeps changes to API, domain, and persistence representations from spreading across boundaries.
- Mapping and coupling trade-off: Explain the work mapping adds and the coupling it avoids when types cross boundaries without translation. Describe how sharing one type can turn a local change into changes elsewhere in the system.
Why it matters: This trade-off explains why removing mapper code can make later changes riskier. - Different boundary representation needs: Distinguish what persistence, domain, and API representations need, and explain why one shared type cannot serve those concerns without pressure.
Why it matters: Different needs at each boundary explain why a single convenient type can become a constraint.
Key terms: mapping, boundary tax, coupling, persistence layer, domain, API, ORM annotations
5.4.2 Strategy 1: No mapping
This section describes using one domain entity at every boundary and explains why that shortcut is an anti-pattern in hexagonal architecture.
- No Mapping Strategy: Describe how the no-mapping strategy uses the domain entity directly in the controller and repository, without separate DTOs, mappers, or persistence entities.
Why it matters: Recognizing this shortcut makes its boundary problems easier to spot. - Boundary Coupling Costs: Explain why using Article as the API and persistence model compromises the hexagon, and distinguish that coupling from the additional collapse caused by having no application layer.
Why it matters: The saved mapping code comes at the cost of the adapter independence and domain purity the architecture is meant to provide.
Key terms: no mapping, domain entity, Article aggregate, DTOs, API contract, serialisation annotations, JPA entity, application layer, Either
5.4.3 Strategy 2: One-way mapping
One-way mapping uses a DTO for data leaving the hexagon, decoupling API responses while leaving the domain entity coupled to persistence.
- One-way mapping boundary: Describe how one-way mapping converts the domain entity to a DTO for data leaving the hexagon while using the domain entity itself for persistence.
Why it matters: It distinguishes protection of the API boundary from isolation of the persistence boundary. - Persistence coupling trade-off: Explain why one-way mapping leaves persistence coupled to the domain and when that trade-off may be appropriate.
Why it matters: It helps you decide whether protecting API responses is enough for a particular application.
Key terms: one-way mapping, domain entity, DTO, JPA entity, persistence coupling, JPA annotations, domain invariants
5.4.4 Strategy 3: Two-way mapping
This section presents two-way mapping as WriteFlow’s baseline for keeping domain, persistence, and consumer-facing models separate.
- Two-way mapping boundaries: Trace where two-way mapping occurs in WriteFlow: the repository adapter maps between Article and JpaArticle, while the handler maps domain data to ArticleDTO for the outbound path.
Why it matters: Placing each mapper at its boundary keeps persistence concerns out of the domain object. - Model separation trade-off: Explain what each separate model is shaped for and the cost of maintaining the two mappers.
Why it matters: The isolation benefits come with mapping work that must be maintained as the domain evolves.
Key terms: two-way mapping, repository adapter, domain entity, persistence entity, ArticleDTO, DTO, ORM, mapper classes
5.4.5 Strategy 4: The full bridge
This section explains how the Full Bridge gives each boundary its own types and mappers, using a domain-dependent query to show when that isolation is useful and what it costs.
- Full Bridge type boundaries: Explain that the Full Bridge uses a distinct type for each purpose and an explicit mapper at each boundary, rather than letting one type serve multiple layers. Identify the roles of requests, commands or queries, domain entities, persistence entities, DTOs, and responses.
Why it matters: Separate types let each side of a boundary represent what its own audience needs. - Domain-dependent read query: Explain why the publication-readiness GET query loads the Article aggregate and invokes domain behaviour instead of answering from stored fields alone, while remaining read-only.
Why it matters: A read-only endpoint may still need the domain model when its answer depends on business rules. - Isolation and mapping cost: Describe the Full Bridge’s trade-off: changes to API, persistence, or domain types stay local to the boundaries concerned, but maintaining separate types and mappers takes work.
Why it matters: The choice is a trade-off between independent evolution and ongoing mapping work. - Mapper choice by mapping purpose: Distinguish mechanical field mapping, for which MapStruct can generate code, from domain-sensitive reconstruction, for which a manual mapper provides control.
Why it matters: Choosing the mapper to fit the conversion keeps routine work mechanical while preserving control over domain construction.
Key terms: Full Bridge, Request, Command / Query, Domain entity, Persistence entity, DTO, publication-readiness query, Article aggregate, domain behaviour, simple projection
5.4.6 Choosing a strategy: Trade-offs at a glance
This section helps readers choose a mapping strategy by weighing convenience against isolation and the longevity of external contracts.
- Mapping strategy trade-offs: Justify choosing two-way mapping as a pragmatic default and the Full Bridge for a public, multi-team, or long-lived application. Explain why the section rejects no mapping at all.
Why it matters: The right amount of mapping protects boundaries without adding more complexity than the application needs.
Key terms: convenience-isolation spectrum, two-way strategy, domain purity, persistence independence, Full Bridge, external contracts
5.5 Summary
Where this is used later
- REST controllers: The input adapter recipe (chapter 8) · Tests a REST controller in its role as an input adapter.
- Code organization: Modules that enforce boundaries (chapter 6) · Assumes the role of an input adapter.
- From shape to behavior (chapter 8) · Controllers are input adapters.
- When listeners execute: The transactional question (chapter 6) · The role of an input adapter in driving the hexagon.
- Orchestrated integration (chapter 10) · Input adapters as a way for outside actors to drive the hexagon.
- The rules that survive every mode (chapter 10) · The input adapter’s boundary role.
- Testing the bus failure path (chapter 8) · Controller tests check how the input adapter responds to a bus failure.
- The REST driving adapter (chapter 9) · The REST driving adapter applies the boundary between core results and HTTP responses.
Concepts explained in this chapter
- data transfer objectA data transfer object is a data-carrying type designed to convey structured information between software components without encapsulating domain behavior.
- full bridgeA mapping strategy that isolates domain, persistence, and external API representations through separate request and response types.
- driving adapterA primary adapter translates an external trigger into a call to an application input port.
- header interfaceAn interface shaped around the complete public method set of an implementing component rather than a specific client role.
- role interfaceAn interface whose operations express the specific capabilities required by its consumer rather than the full API of an implementation.
- mapperA mapper is a component or procedure that converts data between distinct representations.
- persistence entityAn object representing data in the form and structure required by a persistence mechanism.
- driven adapterAn adapter that implements an output port and translates application requests into interactions with an external system.
- Interface Segregation PrincipleThe Interface Segregation Principle states that clients should not be forced to depend on interface operations they do not use.
- data mappingData mapping is the transformation of data between representations used by different system components or layers.
- outbound portAn application-facing boundary that declares a service the application requires from an external system.
- adapterAn adapter that connects an application to an external service through an API.
- projectionA projection is a read-only view containing selected data from a domain model rather than the domain entity itself.
- application layerA software layer that coordinates application operations and use cases above the domain layer.
- domain modelA software representation of the concepts, relationships, and rules of a business domain.
- entityA domain object with an identity whose state and invariants are governed by domain rules.
- hexagonal architectureAn application design pattern that isolates the application core behind ports and connects external technologies through adapters.
- 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.
