What Is a Dependency Graph?

How it is built

A parser reads each file's imports and requires and resolves them to the files they point at. The result is a directed graph, usually with some cycles, that records every dependency relationship in the codebase.

Nodes with many incoming edges are hubs: a lot of the codebase depends on them, so a change to a hub has a wide blast radius and deserves extra review.

What it is used for

Change impact analysis, architecture review, and planning a decomposition — a service boundary should follow clusters that already exist in the graph rather than a line drawn on a whiteboard.

Dependency graph vs dependency diagram

A dependency diagram or dependency map is usually drawn by a person: boxes for the main modules and arrows for the relationships someone remembered to add. It is useful for explaining a system, and it starts going stale the day after it is drawn.

A dependency graph is derived from the source code itself, so it can be rebuilt on every change and includes every edge, not only the ones someone thought were important. When the two disagree, the graph is describing the code you actually ship.

Package graph vs code graph

"Software dependency graph" can mean two different things. A package graph lists the third-party libraries a project installs and what they in turn install — what a lockfile records and what GitHub's dependency graph and supply-chain tools show. It answers "which open-source code do we depend on?"

A code graph works one level down: the files and modules inside your own repository and the imports between them. It answers "if I change this file, what else breaks?" Most architecture and change-impact questions need the code graph, not the package graph.

Reading a dependency graph

Dependency graph analysis looks for a handful of shapes. Fan-in (how many files import a node) marks hubs, the files where a change spreads furthest. Fan-out (how many files a node imports) marks files that break whenever anything below them changes.

Cycles — A imports B, which eventually imports A — make modules impossible to change or test in isolation. Files nothing imports, outside of real entry points, are candidates for dead code. And tightly connected clusters with few edges between them are the natural seams for splitting a system apart.

Where a static graph falls short

A graph built by reading imports sees what the code states, not everything it does at runtime. A dynamic import with a computed path, a plugin loaded by name, a dependency-injection container, or a framework that wires routes by file location can all create a real dependency with no import statement behind it.

Good tools treat framework entry points as roots and flag what they could not resolve, rather than presenting a partial graph as complete. Treat a missing edge as "not proven", not as "does not exist".

Common questions