generated from coulomb/repo-seed
41 lines
2.0 KiB
Markdown
41 lines
2.0 KiB
Markdown
# 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.
|