liveBook · Manning

Full bridge

As explained in Clean Applications with Hexagonal Architecture

A mapping strategy that isolates domain, persistence, and external API representations through separate request and response types.

When an API, domain model, and persistence schema share types, a change in one can spread across the application. A full bridge gives each boundary its own representation and uses explicit mappers between them. Each type has one purpose rather than serving multiple layers. section 5.4.5

A full bridge can use six kinds of type:

  • Request: external input received by an adapter. section 5.4.5
  • Command or query: input accepted by the application layer. section 5.4.5
  • Domain entity: the model used for domain behavior. section 5.4.5
  • Persistence entity: the representation stored by a repository adapter. section 5.4.5
  • DTO: a carrier for query results. section 5.4.5
  • Response: external output returned by the input adapter. section 5.4.5

Publication-readiness query

A GET endpoint receives an article identifier and creates a query. The handler validates a domain identifier, loads the article through a repository, and asks the aggregate to assess publication readiness. A mapper turns the result into a DTO; the controller turns that DTO into a response. The operation is read-only, but it needs domain behavior rather than a simple projection of stored fields. section 5.4.5

Listing 5.15 Full Bridge: Inside the query handler
@ApplicationService
@RequiredArgsConstructor
final class PublicationReadinessHandler
  implements PublicationReadinessUseCase {
 
  private final ArticleRepository articleRepository;
  private final PublicationReadinessMapper mapper; #A
 
  @Override
  public Either<Error, PublicationReadinessDTO>
    handle(final PublicationReadinessQuery query) {
 
    return ArticleId.validateThenCreate(query.articleId())
      .flatMap(this.articleRepository::readById) #B
      .map(Article::assessPublicationReadiness) #C
      .map(this.mapper::toDTO); #D
  }
}

The handler shows the repository lookup, domain assessment, and DTO mapping in sequence. section 5.4.5

The extra isolation costs types and mappers. It is useful when external contracts are public, multiple teams share a codebase, or the system must evolve for years. For most applications, two-way mapping is a pragmatic default: it separates domain and persistence types without adding separate request and response types. section 5.4.5 section 5.4.6

Table 5.2 Mapping strategies: trade-offs across five dimensions
Strategy
Types at boundary
Isolation
Mapper effort
Change propagation
When to use
No mapping
1 (domain entity everywhere)
None
None
Every change cascades everywhere
Prototypes, throwaway scripts
One-way
2 (domain + DTO)
API decoupled, persistence coupled
Low
Persistence changes force domain changes
Simple persistence, document stores
Two-way
3 (domain + persistence + DTO)
API and persistence decoupled
Medium
Changes contained per boundary
Most applications – reasonable default
Full Bridge
6 (request + command + domain + persistence + DTO + response)
Complete
High
Changes always local
Large teams, public APIs, long-lived systems

Compare isolation, mapper effort, and change propagation across the four mapping strategies. section 5.4.6

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Traces a domain-dependent query through its handler and mappings, then compares isolation and mapper effort across four strategies.
Examples
Uses a publication-readiness endpoint, query handler, repository, and mapper to demonstrate a read-only domain question.
What you can do after
Evaluate when to apply full-bridge mapping and trace a query through its representations.
How it connects
Connects mapping to hexagonal architecture, adapters, repositories, domain entities, and DTOs.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Clean Applications with Hexagonal Architecture. The section links point to the parts of the book it draws on.