Managing dependencies: direction, cycles and stability

Why direction matters

A dependency exists when one module needs another to compile, run or behave correctly. Draw it as an arrow from the module that depends to the module it depends on: Checkout to Pricing. The arrow tells you something important about change. If Pricing changes its interface or behaviour, Checkout may have to change; if Checkout changes, Pricing does not care. Changes travel against the direction of the arrows. So the direction of every dependency is a decision about who will be disturbed by whose changes.

Architects care about two kinds of direction that are easy to confuse. The flow of control is who calls whom at run time. The source-code dependency is who imports, references or compiles against whom. Usually they point the same way, but they need not. A framework calls your code without depending on it (Section 0.3 called this inversion of control), and with an interface, a high-level module can call a low-level one while the source-code dependency points the other way. That freedom to choose the direction of the source-code dependency independently of the flow of control is the most powerful tool in this section.

Between services, direction shows up as knowledge. If Orders calls Billing's API, Orders depends on Billing and must change when Billing's API changes. If Orders publishes an event that Billing consumes, the dependency is reversed: Billing depends on Orders' event contract, and Orders does not know Billing exists (Section 3.2). Choosing between a call and an event is therefore partly a choice about dependency direction.

The Acyclic Dependencies Principle

Robert C. Martin formulated three principles for dependencies between components, first in articles and papers in the mid-1990s and later in Agile Software Development: Principles, Patterns, and Practices (2002) and Clean Architecture (2017). The first, the Acyclic Dependencies Principle (ADP), says that the dependency graph between components must contain no cycles: it must be a directed acyclic graph.

A dependency cycle such as Orders depends on Notifications, Notifications depends on Customers and Customers depends on Orders turns three components into one. None can be compiled or tested without the others; a change to any can ripple round the loop back to itself; none can be released on its own; and nobody can say which to build first. Martin introduces the principle with what he calls the morning after syndrome: you go home with working code and return the next day to find it broken because someone else changed something you depend on. His cure is to split the system into separately released components, and that works only if the dependencies between them contain no cycles. Cycles also make it impossible to extract one component later as a library or service, because it drags the whole loop with it.

The Java Platform Module System enforces ADP between modules: the Java Language Specification makes it a compile-time error for a module to depend, directly or indirectly, on itself. Most other languages allow cycles between packages, so teams check for them with tools. Cycles between classes inside one small component are less harmful, and Martin Fowler, among others, tolerates them there; the principle matters most between components that different people build and release.

Breaking cycles

Every cycle can be broken, and there are two standard techniques. Both are shown in the diagram below for a cycle in which Orders calls Notifications to send a confirmation and Notifications calls back into Orders to read the order's details.

Dependency inversion. Notifications declares an interface describing exactly what it needs, say OrderLookup with one method, and Orders implements it. The arrow from Notifications to Orders now points the other way: Orders depends on Notifications (to call it and to implement its interface), and Notifications depends on nothing in Orders. This is dependency inversion, which Section 3.5 covers as the D in SOLID. The key detail is ownership: the interface belongs to the module that uses it, not to the one that implements it.

Extract a new component. Find what both sides actually need from each other, often a small shared model or contract, and move it into a new component that both depend on. Here, Orders publishes an event type defined in an order events component, and Notifications reads the order details from the event instead of calling back. The new component is depended on by both and depends on neither, so it is more stable than either: exactly what the next principle asks for.

The Stable Dependencies Principle and instability

Some components change often (user interfaces, integrations with partners, new features); others should change rarely (core domain concepts, shared contracts, money handling). The Stable Dependencies Principle (SDP) says: depend in the direction of stability. A component that is meant to be easy to change should not be depended on by a component that is hard to change, or it will become hard to change too.

Martin measures stability through dependencies, not through how often the code is edited. A component that many others depend on is stable in the sense that it is costly to change: every change risks breaking its dependents. A component that depends on many others and has no dependents is unstable: nothing stops it from changing, and its dependencies may force it to. Using afferent coupling (Ca, incoming) and efferent coupling (Ce, outgoing) from Section 3.2, instability is:

I = Ce / (Ca + Ce)

I ranges from 0 to 1. I = 0 means only incoming dependencies: maximally stable, responsible to many, depending on nothing. I = 1 means only outgoing dependencies: maximally unstable, nothing depends on it. SDP, stated as a metric, says that along every dependency arrow I should decrease: each component should depend on components with a lower I than its own. A dependency from a stable component (I = 0.1) to a volatile one (I = 0.8) is a warning sign; the usual fix is again dependency inversion, putting an interface in a stable place.

The Stable Abstractions Principle and the main sequence

Stability has a cost: a component with I near 0 is hard to change. If it is full of concrete code, the system becomes rigid. The Stable Abstractions Principle (SAP) resolves this: a component should be as abstract as it is stable. Stable components should consist mostly of interfaces and abstract types, so that their behaviour can be extended by new implementations elsewhere without changing them; unstable components can be concrete, because they are easy to change anyway. SDP and SAP together amount to the dependency inversion principle applied to whole components: dependencies point towards stability, and stability goes with abstraction.

Abstractness is measured as A = Na / Nc, where Na is the number of abstract classes and interfaces in the component and Nc the total number of classes. A = 0 means fully concrete; A = 1 means nothing but abstractions. Plotting A against I gives a square. The line from (I = 0, A = 1) to (I = 1, A = 0) is the main sequence: stable and abstract at one end, unstable and concrete at the other, with balanced mixtures between. Distance from it is:

D = |A + I - 1|

D ranges from 0 (on the line) to 1 (in a far corner). The corner near (0, 0) is the zone of pain: stable, because much depends on it, and concrete, so any change is both necessary and painful. A database schema that every module reads directly lives here. Martin notes that some components belong there harmlessly, such as a mature concrete utility library that never needs to change; the zone hurts only for components that are volatile. The corner near (1, 1) is the zone of uselessness: abstractions that nothing depends on, typically interfaces left behind after a refactoring or designed for an extension that never came.

Strict and relaxed layering

Layering is the oldest and most common dependency rule: arrange modules in layers, such as presentation, application or domain, and persistence, and allow each layer to use only layers below it. Lower layers know nothing about higher ones, so a new user interface can be added without changing the domain. Layering is an architectural style in its own right (Section 5.2); here the interest is the dependency rule it imposes.

In strict (closed) layering, each layer may use only the layer immediately below it. Each layer then hides everything beneath it, and replacing a lower layer affects only one other layer; the price is pass-through code, where the middle layer merely forwards calls it has nothing to add to. In relaxed (open) layering, a layer may use any layer below it. That removes the boilerplate but means a change to the bottom layer can affect every layer above. Many real systems mix the two, marking specific layers as open, such as a shared logging or utilities layer that everyone may use.

Classic layering has one notorious weakness: the domain layer depends on the persistence layer, so the most important business rules depend on database details. Hexagonal, onion and clean architecture (Section 5.6) apply dependency inversion to fix it: the domain owns interfaces such as OrderRepository, and the persistence code implements them, so all source-code dependencies point inwards towards the domain.

Checking dependency rules automatically

Dependency rules written only in a wiki are broken within weeks. The reliable way to keep them is to express them as executable checks that run in the build and fail it when a rule is violated. Such a check is an architectural fitness function, an idea introduced in Section 2.8 and developed in Section 11.3. Three widely used open-source tools cover the main ecosystems.

ArchUnit (Java and other JVM languages) lets you write architecture rules as ordinary unit tests: which packages may access which, layer definitions, and freedom from cycles between slices of the code base. dependency-cruiser (JavaScript and TypeScript) analyses imports and validates them against rules in a configuration file, and its starter configuration already forbids circular dependencies. import-linter (Python) checks contracts declared in a configuration file; its contract types include forbidden imports, layers, independence between sibling modules, protected modules and acyclic siblings.

@ArchTest
static final ArchRule layers = layeredArchitecture()
    .consideringAllDependencies()
    .layer("Web").definedBy("..web..")
    .layer("Domain").definedBy("..domain..")
    .layer("Persistence").definedBy("..persistence..")
    .whereLayer("Web").mayNotBeAccessedByAnyLayer()
    .whereLayer("Domain").mayOnlyBeAccessedByLayers("Web", "Persistence")
    .whereLayer("Persistence").mayNotBeAccessedByAnyLayer();

@ArchTest
static final ArchRule noCycles =
    slices().matching("com.shop.(*)..").should().beFreeOfCycles();

// .dependency-cruiser.js
module.exports = {
  forbidden: [
    { name: "no-circular", severity: "error",
      from: {}, to: { circular: true } },
    { name: "domain-not-to-db", severity: "error",
      comment: "Domain code must use repository interfaces, not the database",
      from: { path: "^src/domain" },
      to: { path: "^src/db" } },
  ],
};

# .importlinter
[importlinter]
root_package = shop

[importlinter:contract:layers]
name = Web above domain above adapters
type = layers
layers =
    shop.web
    shop.domain
    shop.adapters

[importlinter:contract:features-independent]
name = Feature packages do not import each other
type = independence
modules =
    shop.catalogue
    shop.ordering
    shop.payments

Notice that the ArchUnit rule above lets Persistence access Domain but not the other way round: the domain-centred arrangement just described, not classic layering. Rules like these are cheap to add, run in seconds, and turn an architecture diagram into something the build defends. When an existing code base already violates a rule, most tools can record the current violations as a baseline and fail only on new ones, so the rule stops things getting worse from the day it is introduced.

How professionals manage dependencies

Experienced architects keep a picture of the dependency graph between components and look at it regularly, generated from the code rather than drawn by hand. They decide which components are meant to be stable (domain concepts, shared contracts) and which volatile (user interfaces, integrations), and make the arrows point from volatile to stable. They treat new cycles as build failures, not as style issues. And they apply the same thinking across services: shared libraries and shared event schemas are the stable components of a distributed system, deserving minimal surfaces and careful versioning, while each service's internals stay free to change.

None of this needs the metrics to be computed precisely. The value is in the questions they force: which way should this arrow point, what happens to everything upstream if this changes, and is this component as abstract as the number of things that depend on it requires? Section 3.5 continues with the SOLID principles, which apply the same ideas inside components and between them.