Architecture problems / Tight Coupling
Draft
Tier 2 problem — exemplar mapping pending.
What is tight coupling — and why does it raise coordination cost?
Tight coupling is when modules depend directly on concrete implementations instead of abstractions — or when many subsystems share mutable state through a small set of hubs.
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/coupled/moduleDocs → - 2arc hotspots
Rank modules by fan-in and downstream reach across the repo.
arc hotspots - 3arc explain
Inspect src/coupled/module — hub role, dependents, and path narrative.
arc explain src/coupled/module - 4arc watchPro
Pro: keep architecture clean after merge so this problem does not return.
arc watchDocs →
- High fan-in paired with high blast radius on the same module.
- Dependency cycles involving feature packages.
- Impact paths that cross every subsystem from one edit point.
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
Tight coupling propagates changes across teams, couples deployment schedules, and makes safe refactors depend on coordinated big-bang releases.
What it looks like in codebases
- Feature modules importing concrete database or HTTP clients from peer features.
- Shared singletons mutated across unrelated call paths.
- Mutual imports between packages that should be independent.
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
- Concrete imports where interfaces or events would decouple subsystems.
- Cycles involving the module you plan to change.
- Shared mutable modules with fan-in above team ownership boundaries.
What to do next
- Introduce interfaces or events at the highest fan-in boundary first.
- Break the smallest cycle edge before widening abstractions.
- Re-impact after each decoupling step.