Skip to content

Architecture Dependency Graph Review

Structural review — instantiates Organization–Artifact Topology Alignment

Maps the artifact's actual module-and-dependency structure — what calls, imports, or depends on what — so its coupling can be read off and matched against the teams that own the pieces.

Where Communication Pattern Review maps the people, Architecture Dependency Graph Review maps the artifact: it extracts the real graph of modules and their dependencies — imports, calls, build edges — and reads the coupling off it. Its defining move is to size not just what depends on what but the coordination load each dependency imposes: a cross-cutting edge between two independently-owned components is a standing tax on both. This is the artifact-side portrait of the mirror, the thing the domain's intended structure and the organization's communication graph both get compared against.

Example

A bank's payments platform starts throwing incidents a quarter after two teams were merged. An Architecture Dependency Graph Review builds the service graph from build files and runtime call traces, and one feature jumps out: the accounts service and the fraud service each reach into the other's internals — a two-way cycle. That cycle maps exactly onto the two just-merged teams whose code was never separated. The review labels the edge high-coupling, high-coordination-load: every non-trivial change now needs both on-call rotations awake at once. That profile — a concrete cyclic dependency with a measured coordination cost — is what tells the org a boundary has to be redrawn (or the teams re-split) rather than papered over with more process.

How it works

What distinguishes it from a generic code review is that it works from the artifact's own structure, mechanically:

  • Extract edges from real artifacts — static imports, runtime call traces, build dependencies — rather than from a diagram someone drew.
  • Compute coupling — fan-in/fan-out, cycles, cross-boundary edges, and change-coupling (files that keep changing together), which exposes logical ties the static graph misses.
  • Annotate each heavy edge with its coordination load — how many separately-owned pieces a typical change has to touch.
  • Separate essential from accidental coupling, so the review flags the coupling worth removing rather than every edge.

Tuning parameters

  • Edge source — static imports versus runtime traces versus build graph. Runtime catches real coupling that static analysis misses; static is cheaper and complete.
  • Granularity — file, module, or service level. Coarser reads cleanly; finer pinpoints the exact offending dependency.
  • Coupling metric — structural (fan-out, cycles) versus change-coupling. Change-coupling reveals hidden logical dependencies invisible in the call graph.
  • Essential-vs-accidental lens — how aggressively to flag coupling as removable. Too aggressive and you attack necessary cohesion.
  • Refresh cadence — a one-shot audit versus a graph regenerated on every build.

When it helps, and when it misleads

Its strength is making the artifact's true seams visible and putting a coordination price on each one — cycles and change-coupling that no architecture diagram admits to. It turns "the code feels tangled" into a specific edge with a specific cost.

Its failure mode is that a dependency graph shows structure, not intent: some coupling is essential to the domain, and treating every cycle as a defect leads straight to over-splitting and a fresh mess of indirection. The classic misuse is running it backwards — assembling the graph to justify a rewrite or reorganization already decided. The discipline that keeps it honest is to distinguish essential from accidental coupling explicitly, and to read the graph against the domain's intended boundaries rather than in a vacuum, so a refactor moves the artifact toward the right shape and not merely a different wrong one.[1]

How it implements the components

Architecture Dependency Graph Review fills the artifact-mapping side of the archetype — the components an analysis of the built system can produce:

  • artifact_topology_map — its primary output: the extracted graph of modules and dependencies as they actually are.
  • coupling_and_coordination_load_profile — the annotation layer that scores each dependency's strength and the coordination cost it forces on its owners.

It does not build the collective_communication_topology_map — that is Communication Pattern Review — and it does not perform the seam_congruence_assessment overlaying artifact against organization, which belongs to the Organization–Artifact Topology Overlay.

References

[1] A Design Structure Matrix (DSM) is the square dependency matrix used in engineering-design and software-modularity research to represent exactly this kind of artifact dependency graph; clustering it is the standard way to surface candidate module boundaries and cycles. Used correctly it describes the coupling that is — deciding which coupling should exist is a separate, domain-driven judgment. ↩