liveBook · Manning

Dependency direction

As explained in Clean Applications with Hexagonal Architecture

A constraint specifying which software components or layers are permitted to depend on one another.

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

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Specifies layer allowlists and shows how to enforce and freeze rules, with a shared-kernel checker as the detailed example.
Examples
Uses Maven module rules, a framework-free domain, and an ArchUnit shared-kernel checker to illustrate dependency boundaries.
What you can do after
Apply dependency rules via Maven modules and ArchUnit allowlists, including freezing existing violations while blocking new ones.
How it connects
Connects hexagonal architecture, domain models, ports, adapters, and dependency-injection boundaries.

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.