Dependency & Architecture Mapping
Map hidden dependencies, coupling, and architecture in legacy systems to expose risk, structure, and safe refactor boundaries.
SCENARIO
Act as a senior engineer tasked with reverse-engineering the real architecture of a legacy production system. Your job is to uncover how the system is actually wired, where the coupling lives, and which parts are safe or dangerous to change.
CORE WARNING:
Legacy architecture is rarely documented and almost never matches diagrams. Assume hidden dependencies exist and that changing the wrong file can cascade across the system.
CONTEXT:
The system is large, tightly coupled, poorly documented, and possibly evolved organically over many years.
PRIMARY OBJECTIVE:
Build an accurate mental and structural map of the system so future refactors, migrations, or feature changes do not accidentally destabilize production.
ARCHITECTURE DISCOVERY PHASE:
- Identify major layers, subsystems, and boundaries (UI, services, domain, data, infra)
- Map primary entry points, long-running jobs, background workers, and scheduled tasks
- Trace critical request and data flow paths end-to-end
DEPENDENCY ANALYSIS:
- List direct module-to-module dependencies
- Identify cross-layer violations and circular references
- Highlight shared global state, static singletons, or service locators
- Call out reflection, dynamic loading, configuration-driven wiring, or runtime injection
COUPLING & FRAGILITY ASSESSMENT:
- Identify tightly coupled clusters that cannot be changed independently
- Highlight god classes, central coordinators, or "everything depends on this" modules
- Flag cross-service, cross-repo, or cross-database dependencies that only appear at runtime
SEAM & BOUNDARY DETECTION:
- Identify natural seams where the system can be split, isolated, or extracted
- Suggest candidate module boundaries for refactoring or microservice extraction
- Highlight areas where introducing interfaces or adapters would reduce risk
UNKNOWN & DANGER ZONES:
- Identify code paths that cannot be statically analyzed
- Highlight runtime-only wiring and environment-specific behavior
- Flag modules with no clear ownership or production-only execution
WHAT NOT TO DO:
- Do NOT trust package structure or folder names to reflect real architecture
- Do NOT assume dependency graphs are complete without runtime confirmation
- Do NOT attempt major refactors before this map exists
ARCHITECTURE OUTPUT:
- A high-level architecture map (components, layers, boundaries)
- Dependency graph with high-risk coupling highlighted
- List of fragile hubs and critical shared modules
- Candidate seams for safe refactoring or migration
SAFETY RECOMMENDATIONS:
- Identify areas that require isolation before modification
- Suggest instrumentation or tracing to confirm runtime dependencies
- Recommend sequencing for future refactors based on coupling risk
FINAL CHECK:
- If this central module fails, how many systems or customers are affected?
- Which part of this system would cause the worst outage if changed incorrectly?
INPUT:
Codebase or modules: [Insert Code] Known architecture assumptions: [What people believe the structure is] System context: [Monolith, microservices, data stores, critical flows]