Projects › BibleWeb › Cross-References › Cross-reference graph visualization
Done

Cross-reference graph visualization

Area: Cross-References Milestone: v2

Context

Problem: Cross-references between Bible verses form a rich web of connections, but traditional cross-reference lists are flat and fail to show the larger network structure. Users can't see how verses connect to each other across books and testaments.

Solution: An interactive force-directed graph that visualizes cross-reference networks. Users start with a focal verse and explore outward by clicking nodes, discovering how verses connect across the entire Bible. Built with a custom Canvas-based physics engine — no external libraries.

Not included: A static list of cross-references (that's the sidebar feature). This is the interactive graph exploration experience.

Functional

An interactive network graph where each node is a verse and each edge is a cross-reference connection. Users explore by clicking nodes to expand the network.

User flow:

  1. User navigates to /crossrefs/[book]/[chapter]/[verse] (e.g., John 3:16)
  2. The focal verse appears as a central node with connected verses radiating outward
  3. Click an unexpanded node → it expands, fetching and displaying its own cross-references
  4. Click an expanded node → selects it, showing details in the side panel
  5. Graph physics animate nodes into a balanced layout
  6. User can pan (drag) and zoom (scroll wheel) to explore

Keyboard shortcuts:

  • R — reset graph with selected node as new root
  • V — jump to the selected verse in the reader
  • Backspace — go back in the breadcrumb exploration trail

Edge cases:

  • Initial load shows up to 20 nodes from 30 server-fetched cross-refs (minVotes=3)
  • Breadcrumb trail tracks the exploration path for backtracking
  • prefers-reduced-motion: runs physics to completion in one batch instead of animating

UX & Design

Graph rendering: Pure HTML5 Canvas — no SVG, no D3, no external library.

Node colors by Bible section:

  • Torah: sand (#d4a574)
  • History: green (#86efac)
  • Wisdom: purple (#c084fc)
  • Prophets: amber (#fbbf24)
  • Gospels: sky (#7dd3fc)
  • Acts: teal (#38bdf8)
  • Paul's letters: blue
  • General letters: purple (#f472b6)
  • Revelation: red (#f87171)

Node sizes: Unexpanded = 8px, expanded = 12px.

Interaction: Pan via mouse drag, zoom via scroll wheel. Click nodes to expand/select.

Side panel: Shows selected verse reference, text preview, and action buttons.

Technical

Physics engine (crossRefPhysics.ts):

  • Force-directed layout, entirely custom
  • Node-node repulsion: inverse-square, strength 5000, capped at 50px/frame
  • Spring forces along edges: rest length 120, strength 0.005
  • Center gravity pulling toward (0,0)
  • Velocity damping: 0.85 per frame
  • Frame-rate normalization: dt / 16.67 (targeting 60fps)
  • Simulation stops when total kinetic energy < 0.5

Data:

  • DB table: cross_references — 432,949 rows, votes range -31 to 1268
  • Data source: OpenBible cross-reference dataset, imported from BibleGame source DB
  • API: GET /api/crossrefs/[bookId]/[chapter]/[verse]?minVotes=N — returns up to 30 refs
  • Cached: max-age=86400, s-maxage=604800

Tier gate: crossRefGraph (Pro+)

Components:

  • CrossRefGraph.svelte — Canvas rendering and interaction
  • crossRefPhysics.ts — physics simulation engine
  • CrossRefPanel.svelte — side panel for selected node details

Files:

  • apps/web/src/routes/(app)/crossrefs/[book]/[chapter]/[verse]/+page.svelte + +page.server.ts
  • apps/web/src/lib/components/bible/CrossRefGraph.svelte
  • apps/web/src/lib/components/bible/crossRefPhysics.ts
  • apps/web/src/lib/components/bible/CrossRefPanel.svelte
  • apps/web/src/routes/api/crossrefs/[bookId]/[chapter]/[verse]/+server.ts
  • apps/web/src/lib/server/queries/cross-refs.ts

Status

Current: DONE Milestone: v2 Priority: High — signature Pro feature and visual differentiator

History:

  • BibleGame had a similar force-directed graph with MonoGame rendering
  • Web version rebuilt from scratch with Canvas API and custom physics
  • Physics parameters tuned to match the BibleGame feel

Dependencies:

  • Requires: cross_references data (DONE), Canvas API (browser built-in)
  • Used by: vote threshold adjustment (DONE), breadcrumb navigation (NEEDS_DESIGN)
← Back to Cross-References features