liveBook · Manning

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

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

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

What it builds on

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Key terms: convenience-isolation spectrum, two-way strategy, domain purity, persistence independence, Full Bridge, external contracts

5.5 Summary

Where this is used later

Concepts explained in this chapter

← Chapter 4: The honest hexagon: Use cases, commands, and the case against exceptions Chapter 6: The running hexagon: From pieces to 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.