liveBook · Manning

Chapter 6: The running hexagon: From pieces to system

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

The introduction explains why WriteFlow’s independently built hexagonal components need runtime assembly to become a working application.

After this chapter you will be able to

What it builds on

Section by section

Introduction

The introduction explains why WriteFlow’s independently built hexagonal components need runtime assembly to become a working application.

Key terms: ports, adapters, command bus, Architecture Kernel, @Transactional, Dependency Injection, handlers, assembly layer, transaction boundaries, use case

6.1 Code organization: Modules that enforce boundaries

The section shows how WriteFlow uses separate build modules and dependency declarations to make hexagonal boundaries enforceable while keeping the application core independent of adapters and runtime assembly.

Key terms: Maven modules, POM, build-time enforcement, dependency, domain, input-ports, output-ports, application, shared kernel, DTOs

6.2 Assembly time: Wiring the hexagon

This section explains why compile-time module boundaries are not enough and how WriteFlow’s assembly module connects implementations to their dependencies at runtime.

Key terms: module structure, compile-time boundaries, ArticleRepository, persistence adapter, assembly, assembly module, DI framework, Spring Boot, assembly POM, classpath

6.2.1 The bootstrap

This section shows how WriteFlow’s Spring Boot entry point starts the application while keeping the runtime framework outside the application core.

Key terms: Spring Boot, spring-boot-assembly, com.writeflow, application core

6.2.2 Discovering hexagonal stereotypes

The ApplicationAssembler makes hexagonal stereotypes discoverable to Spring while keeping dependency declarations and framework configuration out of the application core.

Key terms: ApplicationAssembler, @ApplicationService, @Adapter, @DomainService, component scanning, constructor, ArticleRepository, JpaArticleRepository, runtime resolution, application core

6.2.3 Wiring the command and query buses

This section explains how Spring assembles command and query buses and how a registry routes messages to handlers without coupling adapters to those handlers.

Key terms: SpringCommandBus, SpringQueryBus, bean registration, bus assembler, stereotype scanning, Registry, ApplicationContext, CommandHandler, QueryHandler, generic type arguments

6.2.4 Manual bean registration for external infrastructure

This section explains when external infrastructure needs explicit bean registration in the assembly module and how adapters receive those dependencies without exposing their configuration to the application core.

Key terms: discoverable, DI container, @Bean, assembly module, RestClient, AuthorExternalAPIAdapter, assembly, application core, ApplicationAssembler, CommandQueryBusAssembler

6.3 Transactionality: Boundaries the framework resolves

This section explains why Spring needs a bridge to recognize the Architecture Kernel’s transaction annotation and interpret failures returned as Either values.

Key terms: @Transactional, Architecture Kernel, Spring Boot starter library, Either, left side, Spring’s default transaction rules, bridge

6.3.1 The technology-agnostic annotation

This subsection explains how the Architecture Kernel’s @Transactional annotation lets handlers declare transactional needs without specifying the infrastructure that fulfills them.

Key terms: Architecture Kernel, @Transactional, transactional boundary, readOnly

6.3.2 The Either problem: No exception, no rollback?

This section explains why Spring’s exception-based transaction handling misses failures returned as Either values, and how the transactional starter restores rollback behavior without putting infrastructure logic in the core.

Key terms: transaction interceptor, RuntimeException, Either.left, transactional starter, custom transaction interceptor, rollback rule, rollback-only, Aspect-Oriented Programming (AOP), proxies, @Transactional

6.3.3 The bridge: Three components

This section explains how a Spring starter bridges Either-based use-case failures to transaction rollback while retaining ordinary exception-based rollback.

Key terms: Either.Left, rollback rules, rollbackOnly, rollback by value, expected use-case failures, unexpected RuntimeException, exception-based rollback, diagnostic information, transactional-either-spring-boot, starter

6.3.4 Where transaction boundaries live

This section places the transaction boundary around the whole use case at the handler and explains why handlers should use the Architecture Kernel’s annotation rather than Spring’s.

Key terms: handler, @ApplicationService, unit of work, transaction boundary, atomicity, Spring's @Transactional, Architecture Kernel's annotation, application core, testability

6.3.5 Readonly and CQS

This section shows how read-only transactions enforce command–query separation and how a transaction makes a state-changing use case an atomic unit of work.

Key terms: readOnly, @Transactional, Command Query Separation (CQS), QueryHandler, CommandHandler, atomic units of work, PublishArticleHandler, aggregate, ArticlePublished, transactional boundary

6.4 Domain events: The full lifecycle

This section connects domain event publication to its assembled adapter and identifies the transaction boundary as the factor that determines listener timing.

Key terms: domainEventPublisher, ApplicationEventPublisher, in-process event bus, transaction boundary

6.4.1 The adapter

This subsection explains how a Spring adapter delivers domain events in-process without changing the handler that publishes them through an output port.

Key terms: DomainEventPublisherOutputPort, output port, adapter, Spring's event infrastructure, in-process delivery

6.4.2 When listeners execute: The transactional question

This section explains how domain-event listeners enter the application and how listener timing affects rollback, then identifies the process boundary of domain events.

Key terms: event listener, input adapter, driving adapter, bus, synchronous listener, @TransactionalEventListener, after-commit listener, transaction, rollback, domain event

6.5 Integration events: When domain events are not enough

This section distinguishes in-process domain events from the need to communicate publication consequences to consumers outside the application.

Key terms: domain events, integration events, ArticlePublished, ApplicationEventPublisher

6.5.1 Domain events vs. integration events

Distinguishes internal domain events from published integration events by their consumers, data contracts, and delivery needs.

Key terms: domain event, integration event, published contract, bounded context, domain-event reaction, after commit, in-process reaction, durable publication mechanism, asynchronous delivery

6.5.2 From domain event to integration event

This section traces how WriteFlow turns a domain event into an externally delivered integration event and explains why that event must be a minimal, stable contract.

Key terms: domain event, listener, input adapter, use case, integration event, outbox, shared contract, external consumers, bounded context, articleId

6.5.3 The outbox pattern: A brief introduction

This section explains how a transactional outbox keeps business changes and pending integration events consistent, then delivers those events reliably despite possible duplicates.

Key terms: dual-write problem, message broker, outbox pattern, outbox table, poller, change-data-capture (CDC), at-least-once delivery, idempotency, eventId

6.6 Summary

Where this is used later

Concepts explained in this chapter

← Chapter 5: Crossing the boundaries: Adapters, repositories, and the mapping problem Chapter 7: Enforcing the architecture as executable specification →

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.