EPIC0001 - Graph Showcases (Samples App)

[wendellmva]

Goal

Add 5 interactive UI showcases that make LowlandTech.Graph cognition transitions + traversal algorithms tangible.

This is mock-first (runs fully in the WASM sample app), with a clean path to a “Live” mode that reads/writes via GraphSession/UserContext when those endpoints are available.

Showcases (5)

1) Traversal Visualizer

• Choose strategy: BFS, DFS, best-first, weighted shortest-path
• Configure: start node, target (optional), max depth/steps, edge filters
• Playback controls: step, run, pause, reset
• Inspector: visited set, frontier, chosen edge, score/priority queue state

2) Transition Stepper (Cognition)

• Small rule-driven state graph (guards + actions + emitted events)
• Shows: enabled transitions at the current state, chosen transition, and the “why” (guard inputs)
• Playback controls: step, run, reset; optionally allow backtracking to prior state

3) Spec/Scenario Knowledge Graph

• Build an in-memory graph from samples/app/wwwroot/content/index.json plus scenario frontmatter
• Nodes: SPEC, US, SC, UAC, Test
• Edges: contains, validates, implements, references
• Queries/traversals:
  • Spec -> failing tests
  • Scenario -> UAC coverage
  • Shortest path Spec -> Test (explain the path)

4) UserState Graph Explorer

• Create/edit a rooted UserState graph (supports multi-parent; not a strict tree)
• Traversals:
  • ancestors/descendants
  • path-to-root
  • reachable set with constraints (depth limit, edge-type allowlist)
• Designed so storage can swap from mock (local) to live GraphSession/UserContext later

5) Vector RAG + Agent Router

• Query -> vector search over snippets/properties (mock embeddings acceptable initially)
• Show top-k matches + the graph traversal that links results back to work items/nodes
• Optional: simple router that detects “graph reasoning” queries and selects the right tool/traversal

Cross-cutting requirements

• Mock-first + “Live” toggle UI (graceful when live endpoint not configured)
• Explainability everywhere: each traversal/transition exposes rule/score/constraint inputs
• Mobile-friendly layout; keep demo datasets small and bundled

Motion + Recording (keyframes)

Design showcases to be recordable as deterministic motion graphics.

• Single source of truth: each showcase renders from a single ShowcaseState object (no hidden timers/randomness).
• Timeline model: Timeline = ordered keyframes { timeMs, state, easing }.
• Interpolation rules:
  • Numeric fields interpolate (camera x/y/zoom, opacity, pulse progress).
  • Discrete fields snap (selected node id, visited/frontier sets, captions).
• Slide host: a host page loads timeline.json and renders StateAt(t) with controls (step/back/play/pause) and query params like ?t=...&autoplay=1&fps=60 for deterministic capture.

This enables an automated “video agent” flow:

1. run a usecase against real graph/pgvector and record an execution trace
2. compile trace -> keyframed timeline (pacing + camera choreography)
3. render timeline to clips; optionally assemble in Remotion

Deliverables

• New pages under samples/app/Pages/UseCases/ (or similar) for each showcase
• Shared UI components: node/edge list, traversal stepper, inspector
• Demo datasets under samples/app/wwwroot/sample-data/
• Timeline + keyframe infrastructure under samples/app/ (state model, interpolation, slide host)

Dependencies / related

• Related to SPEC0210 - Samples App (WASM) for SPEC0200-0209 #97 (SPEC0210 samples app)
• Likely benefits from Add authentication and API integration to samples app #102 (auth + API integration) for “Live” mode

Checklist (sub-issues)

• SPEC0211 - Traversal Visualizer (page + traversal engine adapters)
• SPEC0212 - Transition Stepper (Cognition) (page + rule/guard model)
• SPEC0213 - Spec/Scenario Knowledge Graph (builder + explorer page)
• SPEC0214 - UserState Graph Explorer (page + mock storage adapter)
• SPEC0215 - Vector RAG + Agent Router (page + demo dataset)
• SPEC0216 - Showcase Infrastructure (shared graph UI components, Mock/Live toggle, demo datasets + extension docs)