liveBook · Manning

Composition root

As explained in Clean Applications with Hexagonal Architecture

A composition root is the application’s designated location for constructing components and wiring their dependencies.

Ports, adapters, and handlers can be complete yet leave an application unable to run: adapters are unbound, buses have no handlers, and infrastructure dependencies are missing. The composition root is the designated assembly module that connects these pieces and starts the application. section 9.5.5 section 9.6

In a hexagonal architecture, inner layers must not know their outer-layer collaborators. The root is allowed to depend on the domain, ports, handlers, and adapters so it can bind implementations without putting that knowledge in the core. Swapping an adapter is then an assembly decision rather than a core-code change. section 9.6 section 9.5.5

The assembly connects the application by role:

  • Bind adapters to ports and supply infrastructure such as the datasource, event publisher, and object mapper. section 9.5.5
  • Register handlers with command and query buses and connect listeners to events. section 9.5.5
  • Keep datasource, transaction-manager, and profile configuration out of inner layers; split a large root by concern. section 9.6.5
Listing 9.34 ApplicationAssembler: Stereotype-filtered component scan
@Configuration
@EnableTransactionManagement #A
@ComponentScan(basePackages = "com.manning.writeflow",
  includeFilters = @ComponentScan.Filter(
    type = FilterType.ANNOTATION,
    classes = {ApplicationService.class, Adapter.class,
               DomainService.class})) #B
class ApplicationAssembler {
}

This Spring configuration adds architectural stereotypes to component scanning, so the root discovers components by role rather than naming each implementation. section 9.6.2

Role-based scanning does not enforce the architecture by itself. ArchUnit rules check that domain and application classes avoid framework dependencies and that stereotypes appear in the right places. Package-private adapters also discourage direct references outside their module. section 9.6.2

Assembling WriteFlow

The Spring Boot assembly discovers handlers and adapters by stereotype; command and query buses derive routing tables from handler generic types. Adding a use case needs no edit to the root. An end-to-end create–publish–get lifecycle checks behavior separately from the architectural rules. section 9.8 section 9.6.5

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Explains port binding, role-based component scanning, handler registration, configuration placement, and architectural checks.
Examples
Uses a Spring Boot assembly with stereotype-filtered scanning, a package-private JPA adapter, and a create–publish–get lifecycle.
What it assumes
Assumes familiarity with the existing domain, ports, handlers, and adapters rather than rebuilding them from scratch.
What you can do after
Apply it via Spring component scanning to assemble components by architectural role while keeping framework dependencies out of inner layers.
How it connects
Connects hexagonal architecture, dependency injection, ports and adapters, command and query buses, and architecture tests.

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.