Skip to content

feat(v1.0): interactive knowledge graph viewer with force-directed layout #118

@Pratiyush

Description

@Pratiyush

Why

The current `/wiki-graph` (v0.2) outputs a static `graph.json` + basic `graph.html`. It works but:

  • No zoom/pan/search
  • No clustering by project or entity type
  • No node sizing by connection count (hub detection)
  • No edge labels showing relationship type
  • No dark mode support
  • Can't click a node to navigate to the page
  • Doesn't show on the main site (separate standalone file)

Karpathy's spec says: "Obsidian's graph view is the best way to see the shape of your wiki — what's connected to what, which pages are hubs, which are orphans." We should match that quality.

What

1. Upgrade `graph.html` to a full interactive viewer

  • Force-directed layout (d3-force or sigma.js via CDN — no bundler needed)
  • Zoom + pan with mouse/trackpad
  • Node sizing proportional to inbound link count (hubs are big, orphans are tiny)
  • Node coloring by type: sources (blue), entities (purple), concepts (green), syntheses (orange)
  • Edge labels on hover showing the relationship text from `## Connections`
  • Click to navigate — clicking a node opens the wiki page in a new tab
  • Search overlay — type to highlight matching nodes (same as Obsidian's graph search)
  • Cluster toggle — group nodes by project or by type
  • Orphan highlighting — nodes with zero inbound links glow red

2. Embed in the main site

  • New nav link: "Graph" → `site/graph.html`
  • Or: embed as a widget on the home page (smaller, non-interactive preview that links to the full graph)

3. Dark mode

  • Graph background + labels + edges must flip with the page theme toggle
  • Use CSS vars from the existing `--bg` / `--text` / `--accent` palette

4. Stats overlay

  • Total nodes / edges / clusters
  • Average connections per page
  • Top 5 hubs (most connected)
  • Orphan count

Acceptance criteria

  • `site/graph.html` renders an interactive force-directed graph
  • Nodes are clickable → navigate to the page
  • Search highlights matching nodes
  • Dark mode matches the rest of the site
  • Stats overlay shows hub/orphan counts
  • Works offline (CDN-loaded JS with local fallback)
  • No new Python deps (graph data is still built by `llmwiki graph`)
  • Performance: renders 500+ nodes smoothly (WebGL preferred for large graphs)

Non-goals

  • 3D graph (2D force-directed is enough for v1.0)
  • Real-time editing of connections in the viewer
  • Embedding inside Obsidian (users who want that use Obsidian's native graph)

Related

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions