liveBook · Manning

System boundary

As explained in Clean Applications with Hexagonal Architecture

A structural separation that defines permitted responsibilities and dependencies between parts of a software system.

A shortcut across a module or layer can make a release easier and the next change harder. Shared models travel too far, services reach into internals, and responsibilities become difficult to locate. A system boundary separates responsibilities and controls which dependencies are permitted, so the structure in code remains meaningful. section 1.2 section 1.2.2

In hexagonal architecture, the boundary protects the application core from frameworks, transport objects, and infrastructure. Dependency direction matters: an interface owned by the implementing layer and mirroring its sole implementation can be a fake boundary. It provides an abstraction without protecting the caller from the dependency. section 1.2.2 section 1.2.3

Assign responsibilities at the boundary deliberately:

  • The domain decides what is allowed and enforces business invariants. section 10.5
  • The application layer orchestrates use cases and decides what leaves the hexagon, including the shape of integration events. section 10.5
  • Adapters translate external formats and implement delivery mechanics. Application or domain policies set the relevant limits and semantics. section 10.5
  • Cross-cutting concerns such as transactions are expressed through core-owned, technology-agnostic abstractions; their runtime implementation belongs to adapters. section 4.4.3

A transactional handler

A publish handler uses a technology-agnostic transaction annotation, reads an article, invokes its domain operation, and saves it. Importing Spring's transactional annotation into the handler would instead make the application core depend on Spring. The handler returns Either<Error, Void>; callers needing data use a separate query rather than receiving the domain entity through the command interface. section 4.4.3

Listing 4.11 Handler with technology-agnostic transactional boundary
@ApplicationService
@RequiredArgsConstructor
@Transactional #A
final class PublishArticleHandler implements PublishArticleUseCase {
 
  private final ArticleRepository articleRepository;
 
  @Override
  public Either<Error, Void> handle(final PublishArticleCommand command) {
    return this.articleRepository.readById(command.articleId())
      .flatMap(article -> article.publish(command.authorId()))
      .flatMap(article -> this.articleRepository.save(article));
  }
 
}

The handler listing shows the transaction marker and the sequence of repository and domain operations at the use-case boundary. section 4.4.3

Data crossing a boundary needs an explicit type choice. Reusing one type across HTTP, domain, and persistence reduces mapping but increases coupling; distinct types improve isolation at the cost of more mappers. Choose the trade-off rather than letting convenience decide it. section 5.4

Enforce dependency rules in the build. Maven modules can reject imports when a dependency is absent from the POM; an assembly module can see and wire the components while the core remains unaware of the framework that assembled it. section 6.6

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Explains dependency direction and ownership, then illustrates handler-level transactions, mapping trade-offs, and compile-time enforcement.
Examples
Uses a publish handler, article data in HTTP and persistence forms, and an integration request between systems.
What you can do after
Evaluate boundary ownership, dependency direction, mapping trade-offs, and enforcement choices in a hexagonal system.
How it connects
Connects dependency inversion, hexagonal architecture, command-query separation, adapters, and domain invariants.

Also explained in

Compare how 9 books explain system boundary →

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.