Saltar a contenido

Estado de fase (MASTER-00): POST_MVP — documento de catálogo de producto sujeto a validación; no es alcance aprobado de Gate 0 / PoC / MVP. Gobernanza: MASTER-00.

User Story: Interactive Dependency Graph Visualization

User Story Statement

As a software developer, architect, or engineering manager,
I want an interactive visual graph canvas displaying all atomic documentation nodes and directed edges with real-time filtering, search, zoom/pan, and node detail inspection,
So that I can intuitively comprehend system architecture dependencies, navigate documentation visually, and identify structural relationships across the project.

Business Rationale & User Impact

The interactive dependency graph is the signature visual feature of DocuGraph. Traditional documentation systems present specifications as flat lists of files, obscuring parent-child relationships and making dependency analysis tedious. As defined in VISION-00, transforming static Markdown headers into an interactive DAG canvas enables software architects to instantly evaluate system complexity and identify architectural bottlenecks.

User Flow & Interaction Overview

  1. User selects an indexed project (US-02) from the Project Dashboard (FE-02).
  2. Client sends request to backend endpoint operationId: buildGraph to retrieve project node and edge lists.
  3. Graph Engine parses node frontmatters (:docugraph-core) and constructs DAG adjacency matrices.
  4. Compose Graph Canvas (FE-03) renders visual nodes (color-coded by type: user_story, root_doc, backend_spec, frontend_spec, database_schema) and directed edges (depends_on).
  5. User navigates canvas via pinch-to-zoom, pan, or click-and-drag node positioning.
  6. User applies dynamic tag/type filters or enters text search queries to highlight relevant subgraphs.
  7. Clicking any node slides open the Node Inspector drawer (FE-04), displaying YAML metadata, rendered Markdown content, and direct navigation links to dependent files.

Acceptance Criteria (Gherkin Format)

Scenario 1: DAG Canvas Rendering

Given an indexed documentation project with valid atomic nodes and explicit dependency links
When the user opens the Graph View screen
Then the client dispatches a request to build the dependency graph (operationId: buildGraph)
And upon receiving node records (table: nodes) and edge records (table: node_edges)
Then the GraphCanvas component (FE-03) visually renders all atomic nodes with color coding matching their document type
And directed arrows connect parent nodes to child nodes strictly adhering to "depends_on" metadata

Scenario 2: Interactive Canvas Navigation (Pan & Zoom)

Given a rendered dependency graph canvas containing 50+ documentation nodes
When the user performs touch pinch-to-zoom or mouse scroll wheel zooming
Then the canvas smoothly scales node dimensions and font sizes between 0.25x and 3.0x magnification
And when the user performs click-and-drag panning
Then the canvas viewport shifts seamlessly across the 2D coordinate space at 60 FPS

Given a displayed graph canvas with diverse document types and tags
When the user selects filter criteria "type: user_story" and "tag: auth"
Then non-matching nodes are instantly hidden with smooth fade animations
And non-relevant directed edges are hidden
And the canvas dynamically auto-centers on the active matching subgraph

Scenario 4: Node Inspector Slide-out Panel Inspection

Given a displayed node representing "US-01" on the graph canvas
When the user clicks or taps on the node
Then the selected node receives a visual highlight focus border
And the Node Inspector drawer (FE-04) slides out from the right margin
And displays the full YAML frontmatter, rendered Markdown body text, upstream dependencies, and downstream linkage buttons

Functional Requirements & Constraints

  1. Rendering Performance: The Compose Graph Canvas (FE-03) must render up to 1,000 nodes and 2,500 edges at a minimum of 60 frames per second on desktop and tablet devices.
  2. Layout Engine: Nodes must be positioned using a force-directed layout algorithm with hierarchical fallback for structured DAG layers.
  3. Multiplatform Parity: Gesture interactions (pinch-to-zoom on touchscreens, trackpad pan gestures, mouse wheel drag) must feel native across Android, iOS, and Desktop (JVM) targets.

Downstream Atomic Mapping

This User Story serves as the direct upstream source of truth for the following downstream specifications:

  • Interaction Specification: IX-03_graph-inspection-flow.md (IX-03) — Graph canvas gesture interactions, node selection logic, and drawer animations.
  • Backend Specification: BE-03_graph-build.md (BE-03) — Ktor route handler for GET /api/v1/projects/{id}/graph.
  • API Contract: openapi.yaml — Single source of truth for REST endpoint with operationId: buildGraph.
  • Frontend Specifications:
  • FE-03_graph-canvas.md (FE-03) — Interactive Compose Graph Canvas component.
  • FE-04_node-inspector.md (FE-04) — Slide-out Node Inspector panel component.
  • Database Schema: 01_DATABASE_SCHEMA.md (table: nodes, table: node_edges) — Relational nodes and edge graph storage.

Traceability Index

  • Upstream Dependencies:
  • docs/00_BUSINESS_VISION.md (VISION-00) — Core Visual Product Intent.
  • US-02_create_project.md (US-02) — Indexed Project Workspace requirement.
  • Downstream Direct Linkages (Planned M2/M3):
  • IX-03_graph-inspection-flow.md (IX-03)
  • BE-03_graph-build.md (BE-03)
  • FE-03_graph-canvas.md (FE-03)
  • FE-04_node-inspector.md (FE-04)
  • Related Stories:
  • US-04_get_task_context.md (US-04) — Node selection powering MCP context bundle extraction.
  • US-05_validate_traceability.md (US-05) — Visual rendering of graph validation errors.