chapter seven

7 Enforcing the architecture as executable specification

 

This chapter covers

  • Translating module dependency rules into executable ArchUnit tests
  • Enforcing annotation placement across hexagonal layers
  • Writing custom conditions for structural shape validation
  • Naming convention enforcement through predicates
  • Configuring rules through externalized YAML properties
  • Adopting architectural rules with the freeze mechanism

We assembled WriteFlow into a running system. Maven modules enforce dependency direction at compile time—if the domain POM does not declare Spring Framework, no class inside it can import a Spring type. But Maven modules operate at the artifact level. They prevent wrong imports. They cannot prevent wrong relationships within the classpath that the compiler considers legal. A handler's constructor can accept an adapter as a parameter—Maven will not complain, because the assembly module puts both on the classpath at test time. A command class can carry a @RestController annotation; the compiler sees a valid annotation on a valid class. A use case implementation can be named FooService instead of following the handler naming convention—nothing in the type system rejects it.

These are not compiler errors. They are architectural violations—invisible until someone reads the code and notices the drift. By then, the drift has usually spread.

7.1 Why tests, not just modules

7.1.1 Where the tests live

7.2 The configuration foundation

7.2.1 Externalized properties

7.2.2 WriteFlow's rule configuration

7.3 Dependency rules: Who may import whom

7.3.1 The shared kernel boundary

7.3.2 The domain boundary

7.3.3 The handler's wider scope

7.3.4 The adapter inversion: No reaching into core

7.4 Annotation rules: The right stereotype in the right place

7.4.1 Forbidden annotations

7.4.2 Required annotations

7.4.3 The domain's allowlist

7.5 Structural rules: Shape enforcement

7.5.1 Ports must be interfaces

7.5.2 Commands and queries must implement their marker

7.5.3 The validateThenCreate contract

7.5.4 No public default constructor

7.5.5 Generic type validation on use cases

7.6 Naming conventions: Making intent visible

7.7 Executing the rules: The test suite

7.7.1 The test class pattern

7.7.2 WriteFlow's complete test inventory

7.8 Living with violations: The freeze mechanism

7.9 Summary