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.

Interaction Spec: Interactive Graph Canvas & Node Inspector Flow

1. Overview & System Goal

Goal

Render an interactive 2D Directed Acyclic Graph (DAG) canvas (FE-03) at a smooth 60 FPS frame rate across desktop, mobile, and web targets. Support intuitive gesture controls (viewport pan, pinch zoom from 0.25x to 3.0x), dynamic multi-criteria node filtering (by tag, document type, status), and a slide-out inspector drawer (FE-04) displaying full YAML frontmatters, formatted Markdown bodies, and upstream/downstream traceability navigation buttons.

Primary Actors

  • User: Software developer, software architect, or QA engineer.
  • :docugraph-app Visual Canvas (FE-03 GraphCanvas): Custom Compose Multiplatform 2D graph renderer.
  • :docugraph-app Inspector Drawer (FE-04 NodeInspector): Animated slide-out detail view.
  • :docugraph-backend Service (BE-03 graph.build): Ktor service returning workspace graph adjacency matrices.
  • PostgreSQL Database: Relational store for table: nodes and table: node_edges.

3. State Transition Model

stateDiagram-v2
    [*] --> CanvasIdle: Graph Loaded via GET /api/v1/projects/{id}/graph
    CanvasIdle --> NodeSelected: Tap / Click Node on Canvas
    CanvasIdle --> GraphFiltered: Enter Search Query / Filter Criteria
    NodeSelected --> InspectorExpanded: FE-04 Drawer Slides Open (250ms cubic-bezier)
    InspectorExpanded --> NodeSelected: Tap Different Canvas Node
    InspectorExpanded --> CanvasIdle: Close Drawer / Click Background
    GraphFiltered --> CanvasIdle: Clear Search Query & Filters

State Matrix Definitions

State Name Visual Canvas UI (FE-03) Inspector Drawer UI (FE-04) Camera / Viewport State User Input Focus
CanvasIdle Full DAG graph rendered at 60 FPS; node colors reflect document type. Hidden / Collapsed offscreen. Free pan and pinch-zoom enabled. Canvas gestures active.
NodeSelected Selected node highlighted with focus ring; connected edges emphasized; others dimmed. Animating opening transition (250ms). Viewport smooth-pans to center selected node. Node focus active.
GraphFiltered Matching nodes highlighted; non-matching nodes dimmed to 10% opacity. Displays count of matching search results. Viewport auto-fits bounding box of matching nodes. Search input field active.
InspectorExpanded Canvas constrained to remaining 65% screen width. Fully expanded (35% screen width); displaying frontmatter & preview. Canvas pan/zoom constrained to left region. Inspector tabs & links active.

4. Interaction Sequence & Data Payloads

sequenceDiagram
    autonumber
    actor User
    participant Canvas as FE-03 (GraphCanvas)
    participant Inspector as FE-04 (NodeInspector)
    participant BE as BE-03 (Ktor Backend)
    participant DB as DB (nodes, node_edges)

    User->>Canvas: Select Project & Open Graph View
    Canvas->>BE: GET /api/v1/projects/{id}/graph (operationId: buildGraph)
    BE->>DB: SELECT * FROM nodes WHERE project_id = ?; SELECT * FROM node_edges ...
    DB-->>BE: Return nodes array & directed edges array
    BE-->>Canvas: 200 OK { project_id, nodes: [...], edges: [...] }
    Canvas->>Canvas: Compute Force-Directed Layout & Render Interactive 2D Canvas @ 60 FPS

    alt Viewport Gestures
        User->>Canvas: Touch Pinch / Scroll Wheel
        Canvas->>Canvas: Transform Viewport Matrix Scale (0.25x to 3.0x zoom limit)
        User->>Canvas: Drag Canvas Viewport
        Canvas->>Canvas: Translate 2D Pan Coordinates
    end

    alt Node Selection & Inspection
        User->>Canvas: Click/Tap Node "US-01"
        Canvas->>Canvas: Highlight node "US-01", emphasize connected edges, dim others
        Canvas->>Inspector: Open FE-04 Drawer for nodeId: "US-01"
        Inspector->>BE: GET /api/v1/projects/{id}/nodes/US-01
        BE-->>Inspector: 200 OK { id: "US-01", title, frontmatter_yaml, markdown_body, links }
        Inspector-->>User: Display YAML Frontmatter tab, Markdown Preview, & Link Navigation buttons
    end

    alt Dynamic Subgraph Filtering
        User->>Canvas: Type filter query "type: user_story"
        Canvas->>Canvas: Dim non-matching nodes to 10% opacity, auto-center matching subgraph
    end

Data Payloads

1. Graph Data Response Payload (GET /api/v1/projects/{id}/graph)

{
  "project_id": "prj_01H987654321",
  "node_count": 2,
  "edge_count": 1,
  "nodes": [
    {
      "id": "US-01",
      "atomic_id": "US-01",
      "title": "Authentication & Session Management",
      "document_type": "user_story",
      "status": "APPROVED",
      "relative_file_path": "docs/user_stories/US-01_login.md",
      "tags": ["auth", "security"]
    },
    {
      "id": "IX-01",
      "atomic_id": "IX-01",
      "title": "User Authentication Flow",
      "document_type": "interaction_flow",
      "status": "APPROVED",
      "relative_file_path": "docs/interaction/IX-01_login-flow.md",
      "tags": ["auth", "flow"]
    }
  ],
  "edges": [
    {
      "id": "edg_001",
      "source_node_id": "IX-01",
      "target_node_id": "US-01",
      "relationship_type": "depends_on"
    }
  ]
}

5. Error Handling Matrix

Error Condition Indicator / Status Root Cause System Response & UI Handling Recovery Action
EMPTY_GRAPH HTTP 200 (0 nodes) Project directory contains no parsed .md files with frontmatters. Canvas renders empty state artwork with text: "No atomic documentation nodes found." Click "Trigger Workspace Scan" button on FE-02.
NODE_NOT_FOUND HTTP 404 Not Found Node deleted from filesystem concurrently while selected. Toast banner: "Node no longer exists in workspace." Inspector drawer closes automatically. Canvas re-fetches updated graph data automatically.
PERFORMANCE_LOD_FALLBACK System Event (>1,000 nodes) Workspace contains over 1,000 nodes, threatening 60 FPS target. Canvas automatically activates Level-Of-Detail (LOD) mode, hiding edge text labels during pan/zoom. User applies type/tag filters to isolate smaller subgraphs.

6. Traceability Index