Architecture problems / Architectural Drift
Draft
Tier 2 problem — exemplar mapping pending.
What is architectural drift — and how does it compound silently?
Architectural drift is gradual divergence between intended module boundaries and the actual dependency graph — layers that leak, duplicates that compete, or utilities that absorb domain logic.
How ArcSight detects this
Many visitors land here from search — not the homepage. Run this workflow locally on your repo.
- 1arc impact
Run on the file you plan to change. Surfaces blast radius and break paths.
arc impact src/indexDocs → - 2arc hotspots
Rank modules by fan-in and downstream reach across the repo.
arc hotspots - 3arc explain
Inspect src/index — hub role, dependents, and path narrative.
arc explain src/index - 4arc watchPro
Pro: keep architecture clean after merge so this problem does not return.
arc watchDocs →
- Layer violation reports in arc scan output.
- Rising fan-in on utility folders as features shortcut local boundaries.
- Duplicate authority counts on repository proofs.
Found the issue?
Use arc impact before you change code — structured blast radius and break paths before merge. Use arc watch (Pro) to stop the problem from returning after you fix it.
Why it matters
Drift compounds until refactors are expensive or cycles block progress. Drift plus high fan-in is a common path to production incidents after “small” merges.
What it looks like in codebases
- Domain types importing utilities that import server-only code.
- Duplicate authorities for the same concept in parallel folders.
- Layer violations flagged in structural scans.
Real repository evidence
No indexed exemplar yet. See Next.js repository proof for the current flagship analysis while this problem page is in draft.
What to inspect first
- Documented layer violations involving your change surface.
- Modules that gained fan-in without an explicit design review.
- Parallel type definitions with overlapping names or shapes.
What to do next
- Fix the smallest layer violation that closes a refactor path.
- Consolidate duplicate authorities before adding features on drifted paths.
- Re-scan after boundary fixes; drift repair is incremental.