generated from coulomb/repo-seed
2.0 KiB
2.0 KiB
ADR: Dependency Graph Visualization Framework
Status: accepted
Context: dependency-aware scope propagation needs an interactive graph view where curators can inspect fact-to-scope paths, stale nodes, evidence bridges, same-layer normalization signals, and review recommendations. The visualization must support practical graph exploration rather than only a static diagram.
Decision: use Cytoscape.js for the interactive dependency graph visualization.
Cytoscape.js is selected because it is graph-native: it supports pan, zoom, selection, layouts, node and edge styling, filtering, and path highlighting in a way that maps directly to the dependency model. It can be embedded inside the existing FastAPI-served UI without requiring a full frontend rewrite.
Variants considered:
- React Flow: strong for polished node-card workflows and editable diagrams, but it is more flow-builder-oriented than graph-analysis-oriented. Dense dependency maps and impact-path exploration would require more custom layout discipline.
- D3: maximum visual control and excellent for bespoke animated propagation, but it carries the highest implementation and maintenance cost. It is too easy to build a compelling custom view that becomes hard to evolve.
- Mermaid: lightweight and useful for static docs or fallback exports, but not interactive enough for curator workflows that need selection, filtering, pan/zoom, and path drilldown.
Consequences:
- The first visualization implementation should expose graph data as nodes and edges that Cytoscape can consume directly.
- UI work can remain incremental: a single graph route and JSON endpoint can be added before broader review-workflow screens.
- Cytoscape styling should encode repo-scoping semantics, not generic graph decoration: node kind, edge strength, dependency type, staleness, and same-layer flags should be visible.
- Mermaid may still be useful as an export or documentation format, but it is not the primary interactive implementation.