Chapter 6: The running hexagon: From pieces to system
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
- The runtime assembly gap. Explain why independently testable hexagonal components do not yet make a running application: runtime connections must supply implementations for ports, route commands to handlers, and honor the transaction annotation.
- Build Enforced Module Boundaries. Explain how separate modules turn architectural dependency rules into build failures, and describe when a boundary merits its own module.
- Application Core Dependency Shape. Describe the four application-core submodules, what belongs in each, and which dependencies their arrangement allows.
- Adapter Specific Dependencies. Distinguish the dependencies and boundary roles of WriteFlow's REST, persistence, and notification adapters.
- Assembly Module Independence Test. Explain the assembly module's limited role and describe the compile test for an infrastructure-independent core.
- Compile-Time and Runtime Boundaries. Explain why module boundaries do not, by themselves, connect a handler to the adapter it needs at runtime.
- Assembly Module and Spring Boot. Describe how WriteFlow confines Spring Boot to the assembly module while using it to resolve interfaces to implementations and inject dependencies.
- Bootstrap scanning and isolation. Explain where the Spring Boot entry point lives, what package tree it scans, and why keeping Spring Boot in the assembly module matters to the application core.
- Architectural stereotype discovery. Explain why Spring does not discover the Architecture Kernel’s stereotypes by default and how the ApplicationAssembler makes annotated classes available as beans.
- Explicit dependencies and runtime resolution. Distinguish a handler’s explicit constructor dependency from Spring’s runtime choice and injection of an implementation.
- Explicit bus bean registration. Explain why the command and query buses need explicit bean registration even though Spring discovers handlers and adapters through stereotype scanning.
- Registry-based handler routing. Trace how the registry connects a command or query to its handler, and explain why an adapter can use the bus without knowing a concrete handler.
- Explicit infrastructure bean registration. Distinguish classes the DI container can discover from external infrastructure that usually needs explicit registration, and explain why the assembly module is the place for that registration.
- Adapter infrastructure dependency boundary. Trace how an externally configured client reaches an adapter without making the adapter responsible for building it or exposing it to the application core.
- Either failure transaction gap. Distinguish an exception from a returned Either failure in transaction control flow, and explain why Spring’s default transaction rules need a bridge to interpret the left side.
- Technology-agnostic transaction declaration. Explain that a handler uses the Architecture Kernel’s @Transactional to request atomic execution without specifying how the transaction is implemented, and that readOnly = true declares an intent not to modify state.
- Either and transaction mismatch. Explain why Spring’s standard transaction interceptor would commit when a handler returns a failed Either instead of throwing an exception.
- Rollback without exceptions. Describe how the Architecture Kernel’s transactional starter can roll back a transaction for an Either-returning handler.
- Rollback by Either value. Trace how the transaction interceptor handles a handler that returns Either.Left and explain when it marks the transaction for rollback.
- Handler Transaction Boundary. Explain why the handler is the unit of work and why its transaction must cover the entire use case rather than individual repository operations.
- Read-only transaction enforcement. Explain how query and command handlers use @Transactional differently, and how a read-only transaction enforces CQS when a query attempts a write.
- Domain event delivery at assembly. Explain how the domain event publisher port is implemented and what determines when its listeners execute.
- Domain Event Publisher Adapter. Explain how an adapter implements the DomainEventPublisherOutputPort by delegating event delivery to Spring, while the handler continues to pass aggregate events to the port unchanged.
- Event listeners as input adapters. Explain how an event listener responds to a domain event by invoking a use case through the bus rather than calling output ports directly.
- Listener timing and rollback. Distinguish synchronous listeners from after-commit listeners by when they run and whether their failure can roll back the primary operation. Explain the choice using WriteFlow’s publication and notification example.
- Domain and integration event boundaries. Explain why an ArticlePublished domain event can reach listeners in the same application but cannot reach a separate service, and why that creates a need for integration events.
- Event audiences and contracts. Distinguish a domain event, which expresses a domain decision for consumers inside the application, from an integration event, which is a stable, versionable contract for external consumers. Describe why their data differs.
- Event delivery trade-offs. Explain why an in-process domain-event reaction is not durable by itself, even if deferred until after commit, and why cross-boundary publication needs a durable mechanism.
- Domain-to-integration event flow. Trace how publishing an article leads from a domain event through a listener and use case to an integration event for external consumers.
- Minimal external event contract. Explain why an integration event is a stable, intentional shared contract rather than a copy of an internal domain event, using WriteFlow's published-article example.
- Transactional outbox and relay. Trace how the outbox stores an integration event with the business change and how a separate process forwards it.
- At-least-once consumer idempotency. Explain why outbox consumers must handle duplicate deliveries and how the eventId supports that.
What it builds on
- The command bus (chapter 4) · Commands reach handlers through the command bus.
- Repositories: A privileged kind of output port (chapter 5) · Handlers depend on repository ports implemented by adapters.
- The Application handler (chapter 4) · Handlers orchestrate use cases.
- The secret sauce: Dependency inversion (chapter 1) · Assumes the importance of dependencies pointing toward the core.
- Input adapters: Driving the hexagon (chapter 5) · Assumes the role of an input adapter.
- Output adapters: Serving the hexagon (chapter 5) · Assumes the role of an output adapter.
- From use case interface to handler implementation (chapter 4) · Introduces handlers implementing use cases.
- What an output adapter is (and is not) (chapter 5) · Introduces adapters at the application boundary.
Section by section
Introduction
The introduction explains why WriteFlow’s independently built hexagonal components need runtime assembly to become a working application.
- The runtime assembly gap: Explain why independently testable hexagonal components do not yet make a running application: runtime connections must supply implementations for ports, route commands to handlers, and honor the transaction annotation.
Why it matters: It explains why building clean components is not the same as having an application that runs. - Assembly layer responsibilities: Describe the division of responsibility stated here: dependency injection assembles components, while handlers define use-case transaction boundaries and the assembly layer supplies the infrastructure that enforces them.
Why it matters: It keeps framework wiring separate from the application’s use-case decisions. - Iterative use case assembly: Describe how assembly usually proceeds in a real project, and distinguish that approach from the book’s teaching sequence.
Why it matters: It prevents the book’s teaching order from being mistaken for a required migration strategy.
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.
- Build Enforced Module Boundaries: Explain how separate modules turn architectural dependency rules into build failures, and describe when a boundary merits its own module.
Why it matters: A dependency rule enforced by the build is harder to accidentally break than a package convention. - Application Core Dependency Shape: Describe the four application-core submodules, what belongs in each, and which dependencies their arrangement allows.
Why it matters: These dependencies let handlers use the core's contracts without making the core depend on an adapter. - Adapter Specific Dependencies: Distinguish the dependencies and boundary roles of WriteFlow's REST, persistence, and notification adapters.
Why it matters: Narrow adapter dependencies keep each external concern from reaching unrelated parts of the core. - Assembly Module Independence Test: Explain the assembly module's limited role and describe the compile test for an infrastructure-independent core.
Why it matters: A replaceable assembly module demonstrates that domain and use cases do not rely on the delivery mechanism or infrastructure.
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.
- Compile-Time and Runtime Boundaries: Explain why module boundaries do not, by themselves, connect a handler to the adapter it needs at runtime.
Why it matters: Keeping dependency rules and runtime wiring distinct explains why a well-structured application still needs assembly. - Assembly Module and Spring Boot: Describe how WriteFlow confines Spring Boot to the assembly module while using it to resolve interfaces to implementations and inject dependencies.
Why it matters: Centralizing wiring lets the application run without making its other modules depend on how Spring Boot assembles them.
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.
- Bootstrap scanning and isolation: Explain where the Spring Boot entry point lives, what package tree it scans, and why keeping Spring Boot in the assembly module matters to the application core.
Why it matters: The application can use Spring Boot to start without making its core depend on Spring Boot.
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.
- Architectural stereotype discovery: Explain why Spring does not discover the Architecture Kernel’s stereotypes by default and how the ApplicationAssembler makes annotated classes available as beans.
Why it matters: This configuration lets architectural roles also serve as markers for runtime assembly. - Explicit dependencies and runtime resolution: Distinguish a handler’s explicit constructor dependency from Spring’s runtime choice and injection of an implementation.
Why it matters: Automatic wiring can coexist with visible dependencies and a framework-independent core. - Assembly configuration boundary: Explain why @ComponentScan belongs in the assembly module and what remains if Spring is replaced by manual dependency injection.
Why it matters: Keeping scanning in assembly prevents a framework choice from becoming a core dependency.
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.
- Explicit bus bean registration: Explain why the command and query buses need explicit bean registration even though Spring discovers handlers and adapters through stereotype scanning.
Why it matters: It explains why discovering the handlers is not enough to make the buses available at runtime. - Registry-based handler routing: Trace how the registry connects a command or query to its handler, and explain why an adapter can use the bus without knowing a concrete handler.
Why it matters: It shows how messages reach the right handler while adapters remain independent of handler implementations.
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.
- Explicit infrastructure bean registration: Distinguish classes the DI container can discover from external infrastructure that usually needs explicit registration, and explain why the assembly module is the place for that registration.
Why it matters: It helps you decide which dependencies scanning can supply and which the assembly must configure. - Adapter infrastructure dependency boundary: Trace how an externally configured client reaches an adapter without making the adapter responsible for building it or exposing it to the application core.
Why it matters: It keeps external-client setup out of both adapter behavior and the application core. - Focused assembly configuration: Explain why assembly configuration is split into small classes by concern, using the section's examples.
Why it matters: Focused configuration makes assembly wiring easier to locate and change safely.
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.
- Kernel transaction annotation recognition: Explain how a handler can use the Architecture Kernel’s @Transactional annotation rather than importing Spring’s annotation: a Spring Boot starter teaches Spring’s transaction infrastructure to recognize it.
Why it matters: It connects the handler’s framework-independent annotation to transaction handling at runtime. - Either failure transaction gap: Distinguish an exception from a returned Either failure in transaction control flow, and explain why Spring’s default transaction rules need a bridge to interpret the left side.
Why it matters: An explicitly returned failure does not signal a transaction failure to Spring in the same way an exception does.
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.
- Technology-agnostic transaction declaration: Explain that a handler uses the Architecture Kernel’s @Transactional to request atomic execution without specifying how the transaction is implemented, and that readOnly = true declares an intent not to modify state.
Why it matters: Handlers can state their transaction needs without depending on a particular framework’s annotation.
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.
- Either and transaction mismatch: Explain why Spring’s standard transaction interceptor would commit when a handler returns a failed Either instead of throwing an exception.
Why it matters: A failure value needs explicit transaction handling or it can leave a failed operation committed. - Rollback without exceptions: Describe how the Architecture Kernel’s transactional starter can roll back a transaction for an Either-returning handler.
Why it matters: This preserves rollback behavior while letting handlers report failures as values. - AOP at the assembly boundary: Explain how the starter intercepts handlers without changing them and why that infrastructure behavior belongs outside the core.
Why it matters: The transaction behavior can be added around handlers without making the core depend on that infrastructure.
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.
- Rollback by Either value: Trace how the transaction interceptor handles a handler that returns Either.Left and explain when it marks the transaction for rollback.
Why it matters: It lets an explicit failure value determine whether a transaction commits or rolls back. - Exception rollback remains intact: Distinguish expected failures returned as error values from unexpected RuntimeExceptions, including what to preserve if an exception is translated into an error value.
Why it matters: Explicit error results need not hide unexpected failures or make them harder to diagnose. - Starter-provided transaction bridge: Describe how a project obtains the transaction bridge rather than implementing it itself.
Why it matters: A project can use the bridge without rebuilding its infrastructure for each application.
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.
- Handler Transaction Boundary: Explain why the handler is the unit of work and why its transaction must cover the entire use case rather than individual repository operations.
Why it matters: A transaction around only one repository call cannot make the entire use case atomic. - Framework Independent Transaction Annotation: Explain why a handler should use the Architecture Kernel’s transaction annotation instead of Spring’s @Transactional.
Why it matters: Keeping Spring’s annotation off handlers lets the application core remain framework-independent and easier to unit-test.
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.
- Read-only transaction enforcement: Explain how query and command handlers use @Transactional differently, and how a read-only transaction enforces CQS when a query attempts a write.
Why it matters: The transaction setting makes the query-versus-command distinction enforceable at runtime, not just in handler types. - Atomic state-changing use cases: Trace the work a publishing handler performs within one transaction and describe what happens to the article state on success or failure.
Why it matters: The transaction keeps the publishing use case's state change together as one 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.
- Domain event delivery at assembly: Explain how the domain event publisher port is implemented and what determines when its listeners execute.
Why it matters: It separates the handler's act of publishing from the assembled delivery mechanism and 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.
- Domain Event Publisher Adapter: Explain how an adapter implements the DomainEventPublisherOutputPort by delegating event delivery to Spring, while the handler continues to pass aggregate events to the port unchanged.
Why it matters: It keeps the handler's event-publishing intent separate from the framework that delivers the events.
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.
- Event listeners as input adapters: Explain how an event listener responds to a domain event by invoking a use case through the bus rather than calling output ports directly.
Why it matters: This keeps event-triggered work on the same application entry path as other use cases. - Listener timing and rollback: Distinguish synchronous listeners from after-commit listeners by when they run and whether their failure can roll back the primary operation. Explain the choice using WriteFlow’s publication and notification example.
Why it matters: Listener timing decides whether a failed secondary effect can undo a successful primary operation. - Domain event process boundary: State where domain events are delivered and why they are insufficient when a side effect must reach another bounded context or external system.
Why it matters: This identifies when local domain-event delivery is not enough for a required side effect.
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.
- Domain and integration event boundaries: Explain why an ArticlePublished domain event can reach listeners in the same application but cannot reach a separate service, and why that creates a need for integration events.
Why it matters: It helps you recognize when an in-application event is insufficient for a consumer 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.
- Event audiences and contracts: Distinguish a domain event, which expresses a domain decision for consumers inside the application, from an integration event, which is a stable, versionable contract for external consumers. Describe why their data differs.
Why it matters: The intended consumers determine what an event can safely expose. - Event delivery trade-offs: Explain why an in-process domain-event reaction is not durable by itself, even if deferred until after commit, and why cross-boundary publication needs a durable mechanism.
Why it matters: A reaction that runs after commit can still be lost, so it is not sufficient on its own for reliable external communication.
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.
- Domain-to-integration event flow: Trace how publishing an article leads from a domain event through a listener and use case to an integration event for external consumers.
Why it matters: It separates an internal business occurrence from the event delivered to other systems. - Minimal external event contract: Explain why an integration event is a stable, intentional shared contract rather than a copy of an internal domain event, using WriteFlow's published-article example.
Why it matters: Other systems can rely on the published contract without becoming coupled to WriteFlow's internal model.
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.
- Direct publication dual-write risk: Explain why sending an integration event directly to a message broker from a handler can leave the system inconsistent.
Why it matters: This is the failure the outbox is designed to prevent. - Transactional outbox and relay: Trace how the outbox stores an integration event with the business change and how a separate process forwards it.
Why it matters: The event remains available for delivery without risking a committed business change that has no pending message. - At-least-once consumer idempotency: Explain why outbox consumers must handle duplicate deliveries and how the eventId supports that.
Why it matters: Durable delivery does not prevent duplicate messages from affecting an external consumer.
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
- Assembly: The composition root (chapter 9) · The complete WriteFlow implementation brings its components together at the composition root.
- Dependency rules: Who may import whom (chapter 7) · Provides the module-level dependency rules that the architecture tests will examine more closely.
- (chapter intro) (chapter 7) · Maven modules used to enforce dependency boundaries
- Adapters: Wiring the core to the outside world (chapter 9) · WriteFlow implements adapters at these boundaries.
- Why tests, not just modules (chapter 7) · Uses the module boundaries established to enforce dependencies.
- (chapter intro) (chapter 9) · Earlier assembly work introduced wiring the hexagon.
- Wiring beans by stereotype, not by name (chapter 9) · WriteFlow’s composition root wires beans by stereotype.
- The bootstrap class (chapter 9) · The complete WriteFlow implementation supplies its bootstrap class.
Concepts explained in this chapter
- integration eventA published event contract representing an occurrence in a stable form suitable for consumers across system boundaries.
- moduleA module is a cohesive software unit whose implementation and dependencies are organized behind a defined boundary.
- outbox patternA pattern that stores a message in the same transaction as a business change so it can be published reliably afterward.
- transaction boundaryA transaction boundary defines the scope within which a set of operations participates in one atomic transaction.
- assembly moduleAn assembly module wires application components and adapters into a runnable application.
- persistence adapterAn adapter that implements persistence contracts and translates between domain objects and storage technology.
- Transactional annotationSpring's @Transactional annotation declares transactional behavior for a class or method.
- dependency directionA constraint specifying which software components or layers are permitted to depend on one another.
- event handlerA component that reacts to a published event by invoking additional behavior.
- dependency injectionDependency injection is a design technique in which an object's dependencies are supplied by external configuration or infrastructure.
- component scanningA Spring mechanism that scans specified packages for eligible classes and registers them as application-context beans.
- application serviceA service that coordinates an application use case and its domain operations without containing infrastructure concerns.
- command and query busAn application component that accepts commands through a uniform interface and dispatches them to corresponding handlers.
- domain eventAn immutable representation of a significant occurrence expressed in the language of the business domain.
- dual-write problemThe dual-write problem is the consistency failure that occurs when one operation must atomically update a database and publish a message through separate systems.
- architecture kernelThe Architecture Kernel is a book-specific framework-independent component that provides technology-agnostic annotations for expressing architectural intent.
- handlerA handler is an application component that processes a request and coordinates the interactions needed to fulfill it.
- application coreThe central part of an application containing its domain and application logic while remaining independent of external technologies.
- adapterAn adapter that connects an application to an external service through an API.
- domain serviceA domain service is a stateless domain-layer component that encapsulates business logic not naturally belonging to a single entity.
- handler registryA mapping from operation types or other keys to the handlers responsible for processing them.
- driving adapterA primary adapter translates an external trigger into a call to an application input port.
- outbound portAn application-facing boundary that declares a service the application requires from an external system.
- query busA query bus dispatches query requests to their corresponding handlers through a single entry point.
- system boundaryA structural separation that defines permitted responsibilities and dependencies between parts of a software system.
- command handlerA command handler processes a command representing an application state change.
- command-query separationA software design principle that separates operations that change state from operations that return information without changing state.
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.
