Architecture practice

Spotting Architecture Drift Through Deliberate Comparison

Architecture drift is the gap between the system a team believes it has and the system its code and operations now express. Finding it takes comparison, context, and a human decision about what should change.

Most systems change in small increments. A new adapter appears, a service starts calling a second database, an old queue becomes a synchronous API, or a shared package gradually takes on responsibilities no one intended. Each change can be reasonable on its own. Over time, however, the current implementation may no longer match the architecture people use to make decisions.

That gap is architecture drift. A diagram can help expose it, but only when treated as a model with a known purpose and date, rather than as an unquestioned picture of reality.

Define the comparison before drawing

“Is our architecture up to date?” is too broad to answer. Choose a concrete comparison: Does the checkout service still own payment coordination? Which systems can write to customer data? Does this repository implement the boundaries in the current container view? A question gives the review a scope and a way to distinguish meaningful differences from implementation details.

Next, name the evidence on both sides. The intended side might be an authored diagram, a decision record, or a written boundary rule. The observed side could include source dependencies, deployment configuration, runtime traces, or team interviews. These sources answer different questions. Static code relationships can show that one module imports another; they do not prove that a runtime call occurs, that two modules deploy separately, or that the relationship is an architectural violation.

A mismatch is a question to investigate. It may reveal stale documentation, an intentional evolution that needs to be recorded, or a real design concern. The comparison alone cannot decide which.

Use snapshots to make change visible

One useful way to limit noise is to compare two known repository states rather than infer a trend from memory. The open-source tld CLI has a tld index workflow that creates repository snapshots, and tld git compare can compare Git revisions and produce a change-oriented view. This is a practical aid for asking what changed between revisions; it is not a guarantee that the indexed graph is a complete architecture model.

For example, a focused comparison between the current commit and its parent can start with:

tld git compare HEAD~1 HEAD

The comparison documentation describes a JSON impact scene by default, matching changes to authored diagrams where possible and falling back to mapped or file elements. A changed-file ledger helps connect the view back to the repository diff. Mermaid output is available when a text diagram fits the review:

tld git compare HEAD~1 HEAD --mermaid

Compare a feature branch with its base when reviewing proposed change, or compare tagged releases when looking back at a larger evolution. Keep the scope small first. The --blast-radius option can include up to two dependency hops around changes; more context may help explain an impact, but it can also make a diagram harder to read. Inspect the installed command’s help and the comparison guide for current flags.

Review drift in layers

  1. Start at the boundary level. Check whether responsibilities, external systems, and major dependencies still make sense. Avoid beginning with every class or file.
  2. Follow a specific discrepancy. If a diagram says one service owns a capability but the source suggests another path, trace the relevant symbols and deployment evidence.
  3. Check whether the model is explicit. A source map may be generated, grouped, or matched to authored diagram elements. Understand its provenance before treating an element as a deliberate architectural statement.
  4. Record the disposition. Update the model, document why the implementation intentionally differs, or create a concrete follow-up for an undesirable divergence.

Repeat the review at useful intervals

Drift reviews work best when attached to moments when architectural context is already being discussed: a major release, a change in ownership, a new integration, or a migration. They can also be part of a periodic design review, provided the review has a bounded scope. Comparing every commit without a question tends to create activity without shared understanding.

The tld index --watch workflow is documented for following repository changes locally, while revision comparison offers a way to inspect a pair of states. Such automation can reduce the cost of surfacing differences. It cannot establish whether all important code was indexed or whether the indexed edges correspond to the system’s meaningful runtime and organizational boundaries.

Turn a finding into a decision

When a comparison reveals a discrepancy, capture three things: the evidence, the intended rule or design, and the decision. For example: “The new notification worker reads customer records directly. The ownership model assigns those reads to the customer API. We will route the request through that API before rollout.” This makes the diagram useful as part of engineering work, rather than a separate documentation exercise.

For indexing prerequisites, caveats, and supported workflows, consult the tld indexing guide. The implementation and current project status are available in the open-source tld repository.