Overview

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

This chapter explains how the outer ring of a hexagonal architecture is built so the application core can actually interact with the outside world without losing its independence. Input adapters sit on the left and translate external requests such as HTTP calls, messages, or CLI input into commands and queries for the bus, then translate results back into protocol-specific responses. Output adapters sit on the right and implement the core’s ports, turning application intent into infrastructure calls such as persistence, notifications, or external API requests while keeping framework details out of the hexagon.

For WriteFlow, the chapter shows how a REST controller can map the application’s sealed error hierarchy to stable HTTP problem responses, how adapters should remain translators rather than contain business logic, and why output ports should be designed as role interfaces rather than header interfaces. It also emphasizes that output adapters should communicate through lightweight DTOs instead of domain entities, preserving the domain model’s purity and avoiding accidental coupling to serialization formats, transport protocols, or third-party libraries.

Repositories receive special treatment because they are output ports that are allowed to cross the boundary with domain entities: they persist and reconstitute aggregates, so they must work with the real domain model. The chapter then develops repository design with read-side and write-side methods, shows how to wrap frameworks like Spring Data behind domain-owned ports, and introduces a spectrum of mapping strategies, from no mapping to one-way mapping, two-way mapping, and a full bridge. The central lesson is that mapping is a cost worth paying to keep changes local, with the two-way approach as a practical default and the full bridge as the strongest option for long-lived or public systems.

This chapter completes the outside ring of the hexagon. Input adapters translate external requests into commands and queries, output adapters implement the ports required by the core, and explicit mapping keeps each boundary separate.
This chapter completes the outside ring of the hexagon. Input adapters translate external requests into commands and queries, output adapters implement the ports required by the core, and explicit mapping keeps each boundary separate.
Two input adapters, one use case. The REST controller and the message consumer both call the same command bus. The handler behind the bus is identical regardless of which adapter triggered it.
Two input adapters, one use case. The REST controller and the message consumer both call the same command bus. The handler behind the bus is identical regardless of which adapter triggered it.
Error hierarchy to HTTP status code mapping. Each sealed subtype maps to a specific status code. The compiler enforces completeness—no subtype can be silently ignored.
Error hierarchy to HTTP status code mapping. Each sealed subtype maps to a specific status code. The compiler enforces completeness—no subtype can be silently ignored.
The header interface on the left is shaped by the email implementation. The role interface on the right is shaped by what the application core needs, keeping the port technology-agnostic.
The header interface on the left is shaped by the email implementation. The role interface on the right is shaped by what the application core needs, keeping the port technology-agnostic.
Spring Data reinterpretation. The domain-owned ArticleRepository at the top (annotated with the Shared Kernel's @Repository) defines the contract. The adapter in the middle implements that port and delegates to Spring Data at the bottom (annotated with Spring's @Repository). Two different annotations with the same name, two different layers, two different purposes.
Spring Data reinterpretation. The domain-owned ArticleRepository at the top (annotated with the Shared Kernel's @Repository) defines the contract. The adapter in the middle implements that port and delegates to Spring Data at the bottom (annotated with Spring's @Repository). Two different annotations with the same name, two different layers, two different purposes.
The Full Bridge for a publication-readiness query. The request enters as raw HTTP input, becomes an application query, resolves to a validated domain identifier, loads the Article aggregate because the answer depends on domain rules, maps the domain result to a DTO, and finally maps that DTO to an HTTP response. No type crosses more than one boundary.
The Full Bridge for a publication-readiness query. The request enters as raw HTTP input, becomes an application query, resolves to a validated domain identifier, loads the Article aggregate because the answer depends on domain rules, maps the domain result to a DTO, and finally maps that DTO to an HTTP response. No type crosses more than one boundary.

Summary

  • Input adapters are translators that receive external stimuli—HTTP requests, messages, scheduled triggers—and convert them into commands or queries the bus understands. They map the Error hierarchy to protocol-specific responses using exhaustive switch on sealed types. Framework annotations belong here, not in the core.
  • Output adapters implement port interfaces defined by the core, using whatever technology is appropriate. They translate between the port's domain-language DTOs and the infrastructure's native format. The core never sees the adapter—only the port.
  • Role interfaces vs header interfaces determine whether your ports protect the core or leak the infrastructure. A role interface is shaped by what the consumer needs. A header interface mirrors the implementation. Always design ports from the inside out.
  • DTOs are the currency of output port boundaries—lightweight, immutable records that carry exactly the data the port needs. Domain entities never cross output port boundaries directly. The one exception is repositories.
  • Repositories are special output ports that work directly with domain entities. Their purpose—persisting and reconstituting domain state—requires the domain model to cross the boundary. The repository interface lives in the core, annotated with the Shared Kernel's @Repository. The implementation lives in the adapter layer, annotated with @Adapter.
  • Repository interfaces separate read-side from write-side through naming conventions: save and delete for writes, read for loading domain entities into command handlers, and find for returning DTOs to query handlers. Granularity beyond this—slicing into multiple interfaces—is a team decision, not an architectural one.
  • Spring Data belongs inside the adapter, never on domain-owned ports. The SpringArticleRepository extends ListCrudRepository operating on a persistence entity, hidden behind the JpaArticleRepository adapter that the core depends on.
  • Two @Repository annotations with the same name, two different layers, two different purposes.
  • In WriteFlow, these boundaries complete the outside ring of the hexagon: REST controllers drive article use cases, repository adapters persist and reload articles, notification adapters deliver publication-related messages, and mappers keep each external representation separate from the domain model.
  • The mapping problem arises at every boundary crossing. Four strategies exist along the convenience-isolation spectrum: no mapping (anti-pattern), one-way (API decoupled), two-way (API and persistence decoupled), and the Full Bridge (complete isolation at every boundary). Two-way is the pragmatic default. The Full Bridge is the right choice for public APIs, large teams, and long-lived systems. The only incorrect choice is no mapping at all.

FAQ

What is the role of an input adapter in hexagonal architecture?An input adapter sits outside the hexagon and receives external requests such as HTTP calls, messages, CLI input, or scheduled triggers. Its job is to translate that request into a command or query the bus understands, send it through the bus, and translate the result back into the protocol used by the caller.
What should an input adapter not do?An input adapter should not contain business logic. It should not decide whether an article can be published, inspect database state, or coordinate multiple use cases. Those responsibilities belong to the handlers and the application core.
Why are input adapters considered replaceable?Input adapters are replaceable because the bus makes the delivery mechanism irrelevant to the core. The same use case can be exposed through REST, messaging, or CLI without changing handlers, commands, queries, or the domain model.
How does the chapter map application errors to HTTP responses?The chapter uses a sealed Error hierarchy and an exhaustive switch to map each error subtype to a specific HTTP status code. For example, validation errors map to 400 Bad Request, missing resources to 404 Not Found, and conflicts to 409 Conflict.
Why is exhaustive switching on sealed errors useful?It gives compile-time safety. When a new error subtype is added, the compiler forces every switch expression that handles the hierarchy to be updated, preventing forgotten mappings and runtime surprises.
What is the difference between a role interface and a header interface?A header interface is shaped by the implementation and mirrors its public API. A role interface is shaped by the consumer’s needs and expresses exactly what the application core requires from an external collaborator, no more and no less.
Why are repositories treated differently from other output ports?Repositories are privileged output ports because they must work directly with domain entities. Their purpose is to persist and reconstitute domain state, so the domain entity is allowed to cross the boundary through the repository port.
How should repository interfaces be designed for read and write operations?The chapter recommends splitting repository contracts by consumer need. Write-side methods like save and delete accept domain entities and return Either<Error, Void>, while read-side methods may return either domain entities for mutation workflows or DTOs for query workflows.
Why should Spring Data not be exposed directly from the domain port?Extending Spring Data interfaces directly in the domain port turns the port into a header interface in disguise. It leaks framework methods, couples the core to persistence annotations, and dissolves the hexagon boundary. Spring Data should stay hidden inside the adapter layer.
What mapping strategy does the chapter recommend for most applications?The chapter presents four strategies and treats two-way mapping as the pragmatic default for most applications. It keeps the domain pure and persistence independent while avoiding the extra overhead of separate request and response types. For public or long-lived APIs, the Full Bridge is recommended instead.

pro $24.99 per month

  • access to all Manning books, MEAPs, liveVideos, liveProjects, and audiobooks!
  • choose one free eBook per month to keep
  • exclusive 50% discount on all purchases
  • renews monthly, pause or cancel renewal anytime

lite $19.99 per month

  • access to all Manning books, including MEAPs!

team

5, 10 or 20 seats+ for your team - learn more


Close
choose your plan

team

monthly
annual
$49.99
$499.99
only $41.67 per month
  • five seats for your team
  • access to all Manning books, MEAPs, liveVideos, liveProjects, and audiobooks!
  • choose another free product every time you renew
  • choose twelve free products per year
  • exclusive 50% discount on all purchases
  • renews monthly, pause or cancel renewal anytime
  • renews annually, pause or cancel renewal anytime
  • Clean Applications with Hexagonal Architecture Clean Applications with Hexagonal Architecture ebook for free
Close
choose your plan

team

monthly
annual
$49.99
$499.99
only $41.67 per month
  • five seats for your team
  • access to all Manning books, MEAPs, liveVideos, liveProjects, and audiobooks!
  • choose another free product every time you renew
  • choose twelve free products per year
  • exclusive 50% discount on all purchases
  • renews monthly, pause or cancel renewal anytime
  • renews annually, pause or cancel renewal anytime
  • Clean Applications with Hexagonal Architecture Clean Applications with Hexagonal Architecture ebook for free