Glossary

Architecture drift is the gap between the diagram and the deploy.

Nobody decides to let the diagram go stale. It goes stale because nothing in the process notices.

Download for macOS
v0.1.33 · .dmg · Apple Silicon & Intel
Signed & notarized by Apple · opens without a Gatekeeper warning
sha256 698955a0187bc039f4c74f5d05a9f10fbb27376a45788a0a241d1326b73873c7
Download for Windows instead
$curl -fsSL https://lucidtrain.com/install.sh | sh

Architecture drift is the growing divergence between the architecture a team believes it has and the one actually running. It is not caused by carelessness: every change is individually reasonable, and the diagram is a separate artefact that nothing forces anyone to update. The related term erosion usually describes the same divergence viewed as decay of the original structure. Drift is prevented either by generating the diagram from the code, so it cannot disagree, or by an automated check that fails when reality and intent diverge.

The mechanism is structural, not cultural

A diagram in a wiki has no relationship to a pull request. Nothing fails, nothing is flagged and no reviewer is prompted, so the update depends entirely on somebody choosing to do unrewarded work at the moment they are trying to ship something else. Every incentive points away from it. Exhorting the team to keep diagrams current is asking people to compensate for a missing mechanism.

How you notice, and why it is always late

Drift is usually discovered by an incident nobody could explain from the documented design, or by an onboarding engineer whose questions do not match anything on the diagram, or during a migration when the plan turns out to be based on a topology that no longer exists. All three are expensive discoveries, and all three happen long after the divergence began.

Two things that actually work

Generate the picture from the source of truth, so there is no second artefact to fall behind. Or keep a hand-drawn intended architecture and add an automated check that fails when the real dependency graph violates it, which is the approach behind fitness functions and tools like ArchUnit. The first prevents documentation drift; the second prevents design drift. They solve different halves.

The trade the generated approach makes

A generated diagram shows what is, not what was intended, which means it cannot tell you the current structure is wrong. You lose the ability to express intent and gain the guarantee of accuracy. That is why the two approaches coexist: teams that care about both keep a small intended-architecture diagram and generate the detailed views.

FAQ

Questions

Is drift the same as architecture erosion?

They describe the same divergence from different angles. Erosion frames it as decay of the original structure; drift frames it as the gap between belief and reality. In practice the terms are used interchangeably.

Does generating diagrams solve drift completely?

It solves documentation drift, because the picture is derived rather than maintained. It does not solve design drift, since a generated diagram accurately shows a structure that may itself have gone wrong.

How often should a diagram be regenerated?

If regenerating is cheap, on demand is enough and a scheduled job is fine. The question only matters when regeneration is expensive, which is the problem worth removing first.

Related

Last updated