Graph View

The Graph View displays a Neo4j-style force-directed graph of dependencies and ownership between tasks, drafts, and milestones, as well as the knowledge network formed by Wiki pages, documents, and decisions. It is powered by the built-in dependency graph service: this service scans Markdown files under backlog/ to build a graph database, incrementally updates as files change, and requires no manual maintenance.

Entering the Graph Page

After starting the Web interface, two graph entries are provided below "Statistics" in the sidebar:

• Graph (/graph): task dependency graph, with nodes for tasks, completed tasks, drafts, and milestones.
• Knowledge Graph (/knowledge): knowledge network, with nodes for Wiki pages, documents, decisions, and tags.

You can also open the corresponding page by directly accessing /graph or /knowledge.

Node and Edge Visual Conventions

• Node shape and color: distinguished by category (task / completed / draft / milestone / Wiki / document / decision / tag); node radius reflects degree (more connections = larger node); titles are shown as caption plates that disclose progressively with zoom level.
• Theme-aware strokes: in light theme, each node type switches to a darker border of the same hue and edge colors deepen synchronously, avoiding the washed-out problem where "edges look like gaps and nodes look like outline-less dots" on light backgrounds; dark theme colors remain unchanged.
• Edge styles:
  • DependsOn (dependency): solid line.
  • ParentOf (parent-child): dashed line, arrow pointing to the parent task.
  • BelongsToMilestone (milestone membership): dotted line.
  • The knowledge graph additionally has TaggedWith (tag), SourcedFrom (source), and LinksTo (wikilink reference) edges.
• Legend: the page provides a clickable legend; clicking a node category temporarily hides it (click again to restore), making it easier to focus on specific node types. Sample lines in the legend use the same theme-aware colors as the canvas edges, so they never differ.

Interactions

A zoom control group (zoom in, zoom out, overview) is provided in the upper-right corner. The graph receives graph-updated broadcasts via WebSocket; any file change refreshes the graph in place at the current viewport without interrupting the current browsing position.

Relationship Graph in Task Details

The Dependencies area header in the task detail modal has a graph toggle button on the right. Clicking it switches the modal body to a relationship subgraph centered on the current task:

• The subgraph expands bidirectionally along dependency, parent-child, and milestone edges (with depth and node-count limits); clicking a node continues drilling into neighboring tasks.
• Each task's graph view state (zoom position, legend filtering) is remembered independently and restored when returning after drilling.
• Click the ← Back arrow in the title bar again or press Esc to return to the task detail body.

In addition, the modal shows dependency closure query results: "Waits for / Waited on by" listed by hop count, with root blockers highlighted; unresolvable or cyclic references are also labeled truthfully. If an inline dependency edit is rejected (for example because it would create a cycle), the UI rolls back the change and shows a localized reason.

High-DPI Rendering Performance

On high-pixel-density screens such as Retina / 4K, the graph canvas is now specifically optimized and redraw overhead is significantly reduced:

• Viewport culling: only nodes and edges within the current visible area are drawn; elements outside the viewport are skipped.
• Batch drawing: edges are grouped by (dash, alpha) and nodes by (style, alpha); each group is drawn in one batch, reducing draw calls.
• DPR cap: devicePixelRatio is capped at MAX_DPR=2, avoiding meaningless rendering of pixels beyond human perception on ultra-high-DPI screens.
• Text LOD: labels are displayed progressively across three zoom stages (textStage); the farther you zoom out, the more text is omitted, and at the farthest level only nodes are drawn.
• Gesture snapshot: pan/zoom operations reuse the previous frame's snapshot and only redraw after the new frame stabilizes, eliminating drag stutter.

All optimizations are pure rendering-layer changes and do not alter graph data, layout, or interaction semantics.

Graph Service and Cache

The graph service starts automatically with the Web server. During first build, /api/graph returns a building status; the graph page becomes available automatically once complete:

• Scan scope: only tasks, drafts, milestones, completed (task graph) and wiki, docs, decisions (knowledge graph) under backlog/; archive directories are not included.
• Cold-start acceleration: file-fingerprint cache validation means unchanged files are not reparsed; parser or graph-structure version upgrades automatically trigger a full rebuild.
• Hot update: any write from CLI / TUI / Web / MCP notifies the graph service to incrementally sync, with directory watching and periodic reconciliation as a fallback.
• Cache location: graph data is stored in the OS cache directory (not inside the project tree), partitioned by project path hash. Two browser sessions each hold independent databases and do not contend. The cache directory can be overridden with the environment variable BACKLOG_GRAPH_CACHE_DIR. Only lock files and fingerprint sidecars (*.kuzu.lock, *.kuzu.meta.json) are written to the cache directory; the database itself lives in the WASM in-memory filesystem—this is by design, not a deficiency. The graph can be rebuilt from Markdown at any time.
• Backend: the default backend is RyuGraph WASM (Kuzu's MIT fork built for WebAssembly, executing inside Bun's WebAssembly runtime, working out of the box on all platforms without environment variables). The native Kuzu dependency has been removed; BACKLOG_GRAPH_BACKEND=kuzu is no longer a valid value. BACKLOG_GRAPH_BACKEND=memory forces a pure-JS memory fallback mode (Cypher search is not supported). If ryu initialization fails, it automatically falls back to the memory backend without crashing. During fallback, a one-line English warning is printed in the terminal ([graph] RyuGraph (WASM) backend init failed for <path> ...), and the Web interface displays the English error message returned by the server as-is.
• Lock conflicts: only one process may hold a graph slot for a project at a time. Locks are automatically reclaimed when the holder process has exited; if the holder is still alive, the interactive terminal asks whether to take over (troubleshooting for stuck building and takeover is in Troubleshooting).

The graph is only for visualization and querying; it never writes back to Markdown files—all data still uses files under backlog/ as the single source of truth.