A handler can compile while depending directly on a persistence adapter, bypassing the core’s repository port. ArchUnit makes that architectural drift a test failure: it checks compiled Java classes against executable rules for dependencies, annotations, naming, and structure. section 7.1 section 7.0
Maven modules enforce visibility at the artifact level, but they cannot reject every wrong relationship once classes share an assembly classpath. ArchUnit complements those compile-time boundaries with class-level checks that run alongside unit tests in CI. section 7.0 section 7.1
Architectural rules can check that:
- Packages and classes depend only on permitted counterparts, so handlers use ports rather than concrete adapters. section 7.1
- Annotations appear in the appropriate layer, rather than on classes with incompatible responsibilities. section 7.1
- Commands, queries, and ports have the intended structural shape, and implementations follow naming conventions. section 7.0
- Rules remain portable through externalized YAML properties and can be adopted using a freeze mechanism. section 7.0
Guarding an adapter swap
Replace a JPA facade with an adapter built against the core’s repository port, keeping domain-to-JPA mapping inside the adapter. Then check that no core class gained an infrastructure import. An Elasticsearch adapter can implement the same port without changing the handler, domain entity, or ports. section 2.4.5
Figure 7.1 ArchUnit tests surround the production architecture as a test-time verification layer. They act as executable documentation of the intended boundaries and help prevent architectural erosion.
The diagram places ArchUnit tests around the production architecture as a test-time boundary check. section 7.0
