liveBook · Manning

Hexagonal architecture

As explained in Clean Applications with Hexagonal Architecture

An application design pattern that isolates the application core behind ports and connects external technologies through adapters.

When controllers contain business rules and services depend directly on database APIs, a small infrastructure change can ripple through the application. Hexagonal architecture, also called Ports and Adapters, contains that coupling by protecting a framework-free application core behind explicit boundaries. section 1.0 section 1.1

The hexagon represents an inside and an outside, not a requirement for six ports. The core owns domain entities, value objects, use cases, and the interfaces through which it interacts with external systems. Transport, persistence, frameworks, and external services remain outside. section 1.1.1

Each component has a boundary responsibility:

  • Input ports declare what the application can do. Driving adapters, such as REST controllers or message consumers, translate external requests and invoke those ports. section 1.1.1 section 2.3
  • Handlers implement input ports and orchestrate use cases. Domain entities and value objects enforce business rules without framework or persistence annotations. section 1.3 section 1.1.1
  • Output ports declare what the core needs. Driven adapters implement those contracts for databases, external APIs, or message brokers. section 1.1.1

Dependency inversion makes the boundary work: the handler depends on a core-owned repository interface, while a JPA adapter implements it. At runtime, a request can flow outward through an output port; source-code dependencies still point inward. Interfaces alone are not enough if their models expose REST shapes or persistence assumptions. section 1.1.2 section 1.2.4

Creating an article

A REST controller maps JSON to a CreateArticleCommand and calls CreateArticleUseCase. CreateArticleHandler looks up the author through an output port, validates and creates the Article, then saves it through ArticleRepository. An adapter handles the actual persistence; the handler can instead receive a mock for an isolated test. section 1.3 section 1.1.2

Listing 1.3 Orchestration to implement the use case
@Override
public Either<Error, Void> handle(final CreateArticleCommand command) {
  return this.authorOutputPort
➥.lookupAuthor(command.authorId()) // #A
    .flatMap(author -> 
➥ Article.validateThenCreate( // #B
      command.id(), command.title(), command.content(), author).toEither())
    .flatMap(this.articleRepository::save); // #C
}

The handler listing shows author lookup, validated domain creation, and repository saving in one flow. section 1.3

To introduce the pattern incrementally, choose one bounded context, identify its business rules and infrastructure leaks, define ports around current behavior, and refactor orchestration into handlers. Wrap existing controllers and repositories as adapters, then replace them gradually while preserving working paths and regression tests. section 1.2.6 section 2.5

Guard boundaries with architectural tests and verify behavior with unit tests: a build should fail for a dependency violation as well as a broken business rule. Keep business logic out of adapters and design ports around domain needs, not infrastructure methods. section 9.7.4 section 2.5

The extra interfaces, adapters, and indirection have a cost. For prototypes, simple CRUD applications, or stable systems that favor framework conventions, a layered design may be more practical. section 1.2.6

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Traces request flow through core-owned ports and adapters, then details incremental migration, boundary testing, and trade-offs.
Examples
Uses an article-creation handler, REST and Kafka adapters, repository implementations, and a layered-to-hexagonal migration.
What it assumes
Teaches Spring Boot, functional programming, and domain-driven design practically while building the application.
What you can do after
Build a framework-free core, connect adapters, and enforce its boundaries with architectural tests.
How it connects
Connects dependency inversion, domain modeling, functional error handling, CQRS, and architectural testing.

Also explained in

Compare how 11 books explain hexagonal architecture →

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.