A system can look layered while changes still require tracing dependencies across the whole codebase. Dependency direction makes the boundary explicit: it specifies which components or layers may depend on which others. In a hexagonal design, inner modules do not reference outer modules; the assembly module sees the whole system to wire it together, not to hold business logic. section 1.2.2 section 6.1
An interface alone does not establish a useful boundary. If an interface merely mirrors its implementation and belongs to the implementing layer rather than the calling layer, the caller still depends in the wrong direction. The abstraction protects nothing. section 1.2.2
A module dependency policy can make the permitted directions precise:
- The domain may depend on the shared kernel, but not on the application, adapters, or a dependency-injection framework. section 6.1
- Application code may depend on the domain and ports, but not on adapters or a dependency-injection framework. section 6.1
- Adapters have distinct allowed dependencies and must not depend on one another. The assembly module can depend on all modules for wiring. section 6.1
Table 6.1 Module dependency rules
|
Module
|
May depend on
|
Must NOT depend on
|
|
domain
|
shared-kernel
|
application, adapters, DI framework
|
|
input-ports
|
shared-kernel
|
domain, application, adapters, DI framework
|
|
output-ports
|
shared-kernel
|
domain, application, adapters, DI framework
|
|
application
|
domain, input-ports, output-ports, shared-kernel
|
adapters, DI framework
|
|
rest-adapter
|
input-ports, shared-kernel, MVC framework
|
domain, output-ports, other adapters
|
|
persistence-adapter
|
domain, shared-kernel, Data framework
|
input-ports, output-ports, other adapters
|
|
notification-adapter
|
output-ports, shared-kernel
|
domain, input-ports, other adapters
|
|
spring-boot-assembly
|
all modules, DI framework
|
— (it is the root)
|
Use the module dependency table to check both permitted and forbidden dependencies for each boundary. section 6.1
Make a domain boundary fail at build time
Place the domain in its own Maven module and omit Spring Framework from its dependency list. A domain class cannot then import a Spring type: the compiler enforces the boundary instead of relying on convention. Split modules where the compiler can protect a real boundary; avoid splits that add ceremony without protecting one. section 6.1
Module boundaries can be complemented by executable package rules. ArchUnit checkers load allowed packages from configuration and fail the build when a class depends outside its layer’s allowlist. Freezing separates existing violations from new ones, preventing further degradation while the existing debt is addressed. section 7.3 section 7.3.1
