What Is Architecture Drift?
Architecture drift is the gradual divergence between a system's intended architectural design and its actual implementation in code. It occurs when individual changes — each small and locally reasonable — accumulate into structural patterns that violate the original architectural intent. Layer boundaries get crossed, service isolations erode, and coupling increases without any single change being flagged as architecturally significant.
Why It Matters
Architecture drift is the silent accumulation of structural risk. No single PR introduces it. No single engineer causes it. It emerges from hundreds of small decisions made by different people over time, each taking a pragmatic shortcut that slightly violates the intended architecture.
The consequence of drift is that the architecture documented in wikis, architecture decision records, and onboarding materials no longer describes the actual system. New engineers learn the documented architecture and make assumptions about boundaries that no longer hold. Architects make decomposition decisions based on service isolations that have been violated. Compliance assessments reference controls that are architecturally undermined.
Drift is detectable by comparing the actual dependency graph against the intended architectural model. When cross-boundary dependencies appear that the model does not permit, drift has occurred.
How It Works
Architecture drift detection requires two inputs: the intended architecture (what the system should look like) and the actual architecture (what the code actually does).
The actual architecture is extracted from the dependency graph through standard static analysis — AST parsing, import resolution, and dependency mapping.
The intended architecture is defined through architectural zone boundaries — logical groupings of files and modules that should form independent clusters with minimal cross-boundary dependencies. These zones can be defined manually, inferred from directory structure, or detected automatically through graph clustering.
Drift is measured by counting and classifying cross-boundary dependencies — imports that cross zone boundaries that the intended architecture does not permit. Each cross-boundary dependency is a drift instance. The total count, weighted by the centrality of the involved files, produces a drift severity score.
Comparing drift scores across scans reveals whether the architecture is converging toward its intended design (drift decreasing) or diverging further (drift increasing).
How Axiom Refract Addresses This
- Axiom Refract detects architectural zones automatically through graph clustering and identifies cross-zone dependencies that indicate drift
- Scan-to-scan comparison reveals drift trends — whether architectural violations are increasing or decreasing over time
- The Untangler module specifically analyzes tight coupling and circular dependencies that are the primary mechanisms of drift