liveBook · Manning

Chapter 7: Enforcing the architecture as executable specification

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

The introduction explains why Maven module boundaries need ArchUnit tests to catch class-level architectural violations and keep WriteFlow’s intended architecture visible and enforceable.

After this chapter you will be able to

What it builds on

Section by section

Introduction

The introduction explains why Maven module boundaries need ArchUnit tests to catch class-level architectural violations and keep WriteFlow’s intended architecture visible and enforceable.

Key terms: Maven modules, dependency direction, architectural violations, ArchUnit, compiled bytecode, executable tests, living documentation

7.1 Why tests, not just modules

This section explains why compile-time module boundaries need structural tests to catch architectural violations that remain legal Java.

Key terms: Maven modules, ArchUnit, architectural fitness functions, handler, adapter, ArticleRepository, @ApplicationService, naming conventions

7.1.1 Where the tests live

This section explains why ArchUnit tests run in the assembly module and how they complement Maven module boundaries without affecting production runtime.

Key terms: spring-boot-assembly module, full classpath, Spring's application context, configuration properties, Maven modules, ArchUnit rules, two layers of defense, test-time dependency, production classpath, .class files

7.2 The configuration foundation

This section explains how externalized configuration makes architecture rules reusable across projects and how configuration connects a use case’s ports, handler, and adapters without making business decisions.

Key terms: ArchUnit rules, externalized configuration, YAML, configuration properties record, property binding, input port, application service, handler, output ports, infrastructure adapters

7.2.1 Externalized properties

This section defines the configuration properties for architecture rules and explains how checkers receive them through Spring Boot property binding.

Key terms: HexagonalArchitectureProperties, FQDNs, allowedLibraries, @Configuration, property binding, ArchUnit library, test classpath, auto-configuration

7.2.2 WriteFlow's rule configuration

WriteFlow records its architectural boundaries in test-only YAML so dependency rules can use a reviewable configuration that changes with the code.

Key terms: YAML, package structure, dependency allowances, dependency graph, architectural contract, adapters.fqdns, architectural drift, assembly module, src/test/resources, constructor injection

7.3 Dependency rules: Who may import whom

This section turns layer dependency rules into executable checks that catch forbidden imports while allowing existing violations to be frozen.

Key terms: domain, shared kernel, handlers, adapters, dependency rules, checker class, configuration properties, ArchUnit rules, allowlist, freezing

7.3.1 The shared kernel boundary

This subsection defines the shared kernel’s dependency boundary and shows how a configured ArchUnit rule enforces it.

Key terms: shared kernel, JDK, utility libraries, YAML, allowed libraries, classes().that().resideInAnyPackage(...).should().onlyDepend, HexagonalArchitectureProperties, constructor injection, static @ArchTest, instance-based test methods

7.3.2 The domain boundary

Defines the domain checker’s permitted dependencies and the imports it rejects.

Key terms: domain checker, allowedPackages, shared kernel, domain boundary

7.3.3 The handler's wider scope

This section defines which dependencies handlers may have and how the architecture rule targets handler classes without also scanning commands and queries.

Key terms: handler, @UseCase-annotated interface, handler dependency rule, onlyDependOnClassesThat, domain, input ports, output ports, commands and queries, handler package pattern, com.writeflow.application

7.3.4 The adapter inversion: No reaching into core

This section explains why adapter dependency checks use a denylist, what core dependencies they reject, and the persistence exception the rule must allow.

Key terms: allowlist, denylist, domain, handlers, ports, command bus, DTOs, persistence adapter, repository interfaces, protected set

7.4 Annotation rules: The right stereotype in the right place

This section explains why stereotype annotations must match a class’s architectural role and package, even when a misplaced annotation compiles.

Key terms: annotation rules, stereotype annotations, @ApplicationService, Architecture Kernel, component scan, ArchUnit

7.4.1 Forbidden annotations

This subsection explains how architecture checkers use annotation denylists to keep layer stereotypes in their proper places, and why the shared kernel and adapters are exceptions.

Key terms: denylist, CommandChecker, QueryChecker, HandlerChecker, InputPortChecker, OutputPortChecker, shared kernel, adapters, dependency direction

7.4.2 Required annotations

This section specifies required annotations for ports and handlers and explains why adapters do not have a blanket annotation rule.

Key terms: required rules, @UseCase, @OutputPort, @ApplicationService, @Adapter, ApplicationAssembler, AdapterChecker, @RestController, @MessageListener

7.4.3 The domain's allowlist

Defines the domain layer’s annotation allowlist and explains why enforcing it requires a custom ArchUnit condition.

Key terms: domain layer, allowlist, @Repository, @DomainService, @ValueObject, @Identity, custom ArchCondition, ArchCondition<JavaClass>, check(), fluent DSL

7.5 Structural rules: Shape enforcement

This section defines what structural architecture rules check and distinguishes simple shape checks from checks that require custom conditions.

Key terms: structural rules, ports, marker interfaces, validateThenCreate, public default constructor, CommandHandler, Domain Specific Language (DSL), should().beInterfaces(), ArchCondition

7.5.1 Ports must be interfaces

This subsection explains why ports must be interfaces and how a structural rule enforces that requirement.

Key terms: input ports, output ports, interfaces, InputPortChecker, OutputPortChecker

7.5.2 Commands and queries must implement their marker

This section explains why commands and queries must implement their marker interfaces to be dispatched by their respective buses.

Key terms: Command marker interface, Query marker interface, command bus, query bus, dispatch

7.5.3 The validateThenCreate contract

This section explains why commands and queries need a validateThenCreate factory and how an architecture rule checks its method signature.

Key terms: self-validating commands, validateThenCreate, Either<Error, T>, ArchCondition, Either, CommandChecker, QueryChecker

7.5.4 No public default constructor

This subsection explains why commands and queries must not have public default constructors and how an ArchUnit rule protects their validated construction contract.

Key terms: validateThenCreate, public default constructor, command, query, ArchUnit

7.5.5 Generic type validation on use cases

This section explains why use case interfaces need generic-type checks and how those checks complete their structural validation.

Key terms: input ports, CommandHandler<E, C>, QueryHandler<E, R, Q>, Command, Query, InputPortChecker, custom condition, generic signature, beAssignableTo, @UseCase

7.6 Naming conventions: Making intent visible

This section explains how a handler naming rule makes use case implementations easy to find and how the rule is checked.

Key terms: HandlerChecker, @UseCase, Handler, DescribedPredicate, ArchCondition, @ApplicationService

7.7 Executing the rules: The test suite

The section explains that architecture checkers need test classes to execute their rules.

Key terms: checkers, test class, Spring context, configuration properties, ArchUnit, rule evaluation

7.7.1 The test class pattern

This section shows the shared wiring pattern for architectural test classes and how their scan scope and checker vary.

Key terms: @AnalyzeClasses, TestConfig, checker, ArchUnit, SharedKernelArchitectureTest

7.7.2 WriteFlow's complete test inventory

This section shows how WriteFlow wires eight architectural test classes to checkers and runs them individually or as a suite.

Key terms: architectural test classes, checker, package scope, pure wiring, mvn test, spring-boot-assembly module, CI

7.8 Living with violations: The freeze mechanism

Explains how ArchUnit’s freeze mechanism lets a team enforce architectural rules against new violations while gradually eliminating existing ones.

Key terms: freeze mechanism, FreezingArchRule.freeze(), known violations, archunit_store/, archunit.properties, allowStoreCreation, allowStoreUpdate, freeze store, strict enforcement

7.9 Summary

Where this is used later

Concepts explained in this chapter

← Chapter 6: The running hexagon: From pieces to system Chapter 8: Testing the hexagon with behavioral verification →

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.