Acyclic and stable abstractions

ADP: Acyclic Dependencies Principle

The Acyclic Dependencies Principle is simple to state: there must be no cycles in the component dependency graph. A cycle means a set of components where each eventually depends on the others — directly or transitively. The opening story is a classic example: billing → shared-utils → order → billing.

Cycles are destructive for three reasons:

They turn independent components into one release unit. If A depends on B depends on C depends on A, you cannot build or deploy any of them without the others. They must be released as a group even though they were designed as separate components. This is the “morning after” problem: a change in any component in the cycle can break the others, so the team cannot integrate incrementally.

They make it impossible to reason about change impact. In an acyclic graph, you can follow dependency arrows to identify exactly which components a change can affect — the set is finite and directed. In a cycle, a change in any node affects every other node in the cycle. The blast radius is the entire cycle.

They force higher coupling metrics. Every component in the cycle effectively has a source-code dependency on every other component’s internals. The afferent/efferent coupling metrics become meaningless because no component can be separated from the others to be analyzed independently.

Breaking cycles: two strategies

When you detect a cycle, you have two structural tools:

1. Apply DIP to invert one of the dependency arrows. If A → B → C → A is the cycle, introduce an interface in A that C implements. The arrow C → A becomes C → IA (where IA lives in A’s package), and A imports only IA. The cycle is broken: A → B → C → IA, with C implementing IA. No node depends on A as a concrete module.

2. Extract a new component that both sides can depend on. If A and C depend on each other because they share something (the OrderStatus enum, in the opening story), extract that shared thing into a new component D that has no dependencies. Then A → D, C → D. Both A and C depend on D; neither depends on the other. The cycle disappears because D is a leaf node.

In the opening story, the fix was option 2: extract the OrderStatus enum from shared-utils into a new order-domain-types component with no dependencies. Billing imports order-domain-types directly. Order imports order-domain-types. Shared-utils no longer imports order. The cycle is gone.

SDP: Stable Dependencies Principle

The Stable Dependencies Principle extends the dependency rule from the previous lessons to the component level: depend only in the direction of stability. A component should only depend on components that are at least as stable as itself.

Stability at the component level is measured by the instability metric from unit 01:

I = Ce / (Ca + Ce)

where Ce is the count of outgoing dependencies (efferent) and Ca is the count of incoming dependencies (afferent). I = 0 is maximally stable (nothing it depends on can force it to change; many things depend on it). I = 1 is maximally unstable (it depends on many things, and nothing depends on it).

SDP says: if component A has instability I_A and depends on component B with instability I_B, then I_A ≥ I_B must hold. The arrow should point from higher instability to lower instability — from more volatile toward more stable.

The failure mode of violating SDP: a volatile component is depended on by a stable component. The stable component was designed to be hard to change. But now it has a dependency on something volatile. The volatile component changes, and it forces the stable component to change — even though the stable component has high afferent coupling and breaking it is expensive. This is exactly how a well-designed core domain module becomes fragile: someone adds a dependency from it to a utility that is changed frequently.

In the B2B platform, the billing engine (Ca = 12, I ≈ 0.08 — very stable) should depend only on components with similarly low instability: the IOrderPort interface (I = 0 — pure abstraction, nothing depends on it from the other direction), the money utility (I = 0.1 — stable, many dependents). It should not depend on the reporting utilities component (I = 0.9 — almost nothing depends on it, it depends on many things, it changes weekly). If billing imports reporting utilities, a weekly reporting change now forces a billing recheck.

SAP: Stable Abstractions Principle

The Stable Abstractions Principle is the partner to SDP: a component should be as abstract as it is stable. Stability and abstractness must scale together.

This is not an aesthetic preference — it follows from the dependency rule. If a component is stable (high Ca, low I), many things depend on it. Those dependents cannot easily change it when their needs evolve. The only way the stable component can remain useful as requirements change without forcing changes in all its dependents is if it is abstract: defined as interfaces and abstract types that can be extended without modification. A stable, concrete component cannot be extended without being changed — and changing it breaks all its dependents.

The two failure zones follow directly:

Zone of Pain (stable + concrete, I ≈ 0, A ≈ 0): A component that is highly stable (many dependents, hard to change) but entirely concrete (all implementation, no interfaces). If this component must ever change, every dependent must change too. The concrete infrastructure code that every module in the platform imports but that must be updated with each framework upgrade lives here. It is painful because you cannot extend it without breaking dependents, and you cannot stop depending on it because everything already does.

Zone of Uselessness (unstable + abstract, I ≈ 1, A ≈ 1): A component that is entirely abstract (all interfaces, no implementation) but that nobody depends on. These interfaces were probably written for a future use case that never arrived. They are useless because no concrete component implements them, and no component depends on them — they contribute nothing to the running system.

The main sequence is the diagonal line between these two zones: the ideal position for a component is where its abstractness roughly equals its instability (A ≈ I). A maximally stable component (I = 0) should also be maximally abstract (A = 1) — a pure interface package. A maximally unstable component (I = 1) should be maximally concrete (A = 0) — a leaf implementation that implements interfaces and depends on nothing. Everything else should fall on or near the diagonal.

Applying the three principles together

ADP, SDP, and SAP are most powerful when applied together as a complete constraint set for the component graph:

1. Run ADP first: detect and break cycles. A cyclic graph invalidates instability metrics (Ca/Ce) because components in a cycle cannot be measured independently.

2. Compute instability metrics after ADP is clean: with an acyclic graph, measure I for each component.

3. Apply SDP: check that every dependency arrow points from higher I to lower I. Dependencies that violate this (stable depending on volatile) are the first candidates for DIP-based inversion.

4. Apply SAP: plot components on the I/A plane. Components far from the main sequence are structural debt: zone-of-pain components need interfaces extracted from them; zone-of-uselessness components need to either be implemented or deleted.

In the B2B order platform after the cycle fix, the remaining structural debt was a shared-utils component sitting in the zone of pain: I ≈ 0.05 (many things depend on it) but A = 0 (pure concrete utility functions). The fix was to extract the interfaces that callers actually needed into a small, pure-abstract platform-contracts package, and demote the concrete utilities to a component that only leaf modules depended on.