liveBook · Manning

Architectural rule

As explained in Clean Applications with Hexagonal Architecture

An architectural rule is a constraint that specifies an allowed or required structural property of a software system.

Architectural rules constrain relationships and properties that the compiler may allow but the intended design forbids. As ArchUnit tests, they inspect compiled classes and turn violations into build failures, making boundaries enforceable rather than dependent on code review. section 7.0 section 7.1

Use rules to check properties that module boundaries and the type system do not fully enforce:

  • Restrict which packages or classes may depend on one another. section 7.1
  • Keep annotations in their intended layers and enforce class naming or structural conventions. section 7.0
  • Guard project-specific decisions, such as allowing only the persistence adapter to call domain reconstitution methods. section 9.7.2

A dependency boundary

A publish handler can compile while accepting a persistence adapter directly, bypassing a repository interface. An ArchUnit rule can reject that relationship; Maven module boundaries alone may not catch it when both classes are available on the assembled test classpath. section 7.1

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 shows ArchUnit tests as a test-time verification layer around production architecture. section 7.0

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Checks compiled-class dependencies, annotations, naming, structural shape, and project-specific method access.
Examples
Checks handler dependencies, annotation placement, naming conventions, and calls to domain reconstitution methods.
What you can do after
Apply them via ArchUnit tests that fail the build when code violates declared boundaries.
How it connects
Connects ArchUnit checks with Maven module boundaries and hexagonal architecture layers.

Also explained in

Compare how 2 books explain architectural rule →

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.