Architecture diff

What it shows

A normal diff answers which lines changed. An architecture diff answers which parts of the system are different now, by drawing the components and the relationships between them twice: once as they were at the base commit, once as they are at the head.

The unit is the component, not the file. A component is a cluster of files that belong together — an authentication domain, a billing module, a request pipeline — so a change touching forty files might move two boxes and one arrow.

Three states carry the meaning, and they are the same three a line diff uses:

• New — a component that did not exist at the base.
• Modified — a component that existed and whose files or relationships changed.
• Removed — a component that no longer exists at the head.

An arrow between two boxes means a real dependency: an import, a call, a route handler, a database access. New arrows are usually more significant than new boxes. A new component nobody depends on is inert; a new edge from Checkout into Authentication is a coupling decision.

How it is computed

Two commits are parsed independently — imports, exports, function calls, route declarations, database access — and each side is grouped into components. The two graphs are then compared.

Nothing about that step should involve a language model. The edges are facts a parser extracts exactly, and a model asked to produce them will produce plausible ones instead, which is the subject of why LLM-drawn architecture diagrams are wrong.

What a model is good for here is naming. "These eleven files form a cluster" is computed; calling that cluster Authentication domain is a judgement, and it is the one part of the drawing worth generating.

Why only part of the system is drawn

A complete architecture diagram of a real repository is unreadable — a force-directed hairball with sixty nodes, which is a picture of having a codebase rather than a picture of a change.

So an architecture diff draws only the affected neighbourhood: the components that changed, plus the ones directly connected to them. Everything else is omitted, and a diff worth trusting says how many it omitted rather than quietly cropping.

The rule of thumb is roughly nine nodes. Past that, the reader is doing graph traversal instead of understanding a change.

What it does not tell you

An architecture diff shows structure, so it is blind to everything that is not structural. It will not tell you whether a function is correct, whether a test covers it, or whether a change is a good idea. Two commits with identical structure and opposite behaviour produce the same drawing.

It is also blind to dynamic dispatch — reflection, dependency-injection containers, duck typing — because static analysis is. Edges that only exist at runtime do not appear, and a tool that claimed otherwise would be guessing.

Related

• Change impact analysis — what the changed parts reach.
• Architecture drift — what many of these diffs add up to.
• An architecture diff on a real pull request.