liveBook · Manning

ArchUnit

As explained in Clean Applications with Hexagonal Architecture

ArchUnit is a Java library for expressing and testing architectural constraints in code.

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

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Outlines dependency, annotation, structural, and naming checks, plus YAML configuration and freeze-based adoption, without showing rule implementations.
Examples
Illustrates a handler depending directly on a JPA adapter, a misplaced annotation, and JPA-to-Elasticsearch adapter replacement.
What you can do after
Evaluate architectural boundaries by identifying dependency leaks and relationships that compile but violate intended rules.
How it connects
Connects hexagonal architecture and dependency inversion with Maven modules, ports, adapters, and architectural fitness functions.

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.