rgBuilder static dashboard — engineering design (living document)

Status: Phase 8 complete (taint tab); Query Guide + HTTP serve integrated
Last updated: 2026-07-13
Owner: rgBuilder core / export pipeline

This document is the running source of truth for the WASM + WebGL dashboard replacement. Update the Implementation status section at the end of every phase PR.

Related: cli-io-sanity-qe.md, Code_structure.md, json-api.md.

Goals

Repository layout

dashboard/                      # Vite + Preact + Bootstrap 5 (bundled, offline)
  src/styles.css                # Bootstrap import + graph layout tweaks
  src/App.tsx                   # Tab shell, stat toolbar
  src/worker.ts                 # Loads WASM + graph_payload.bin
  dist/                         # Built assets (npm run build) — embedded at compile time

crates/rgbuilder-dashboard/      # Rust: export bundle on discover
  src/lib.rs                    # export_dashboard_bundle()
  src/manifest.rs               # manifest.json schema
  src/bundle.rs                 # Copy/extract static assets

crates/rgbuilder-wasm/           # WASM engine (Phase 1+)
  src/lib.rs                    # Columnar v2 header parse, future graph ops

.rgbuilder/dashboard/            # Runtime output (per repo, gitignored)
  index.html
  assets/                       # Hashed JS/CSS from Vite
  manifest.json                 # Counts, paths, phase flags
  graph_payload.bin             # Copy of graph.snapshot.bin (columnar v2)
  wasm/                         # rgbuilder_engine.wasm + JS glue

Phase map (with mandatory removal)

Phase 0 — Shell + bundle export

What it does

1. discover writes .rgbuilder/dashboard/ instead of monolithic dashboard.html.
2. UI: responsive tab bar matching legacy areas (graph, functions, CFG, slice, blast, guide).
3. Stat cards read manifest.json (no inline graph JSON).
4. Static assets bundled at compile time via include_dir from dashboard/dist/.

How to build the UI

cd dashboard && npm ci && npm run build
cargo build --release   # rgbuilder-dashboard embeds dashboard/dist

How to open after discover

rg-build discover .
# Option A — rg-build HTTP server (dashboard + POST /api/query)
rg-build serve --open
# Option B — local static server (WASM fetch; no query API)
cd .rgbuilder/dashboard && python3 -m http.server 8765
open http://localhost:8080   # or :8765 for Option B

Lookup

Phase 1 — Binary payload + WASM loader

What it does

1. graph_payload.bin — byte copy of .rgbuilder/graph.snapshot.bin (columnar v2).
2. manifest.json — payload_format: "columnar_v2", node/edge counts, digest.
3. Web worker fetches payload + instantiates WASM.
4. WASM parses columnar header (magic, version, counts) — no full graph hydrate.

Worker message protocol (v1)

Future phases add filter, blast_radius, compute_slice, etc.

Columnar v2 header (first 136 bytes)

See crates/rgbuilder-graph/src/columnar_snapshot.rs:

• [0..4] magic RBGR
• [4..8] format version 2
• [8..12] schema version
• [12..20] node count (u64 LE)
• [20..28] edge count (u64 LE)
• [28..92] digest (64-byte UTF-8, null padded)

WASM duplicates minimal parse in crates/rgbuilder-wasm/src/lib.rs (no full graph crate in WASM yet).

Lookup

manifest.json (schema v1)

{
  "schema_version": 1,
  "dashboard_version": "0.1.0",
  "phases": { "0": "complete", "1": "complete" },
  "graph": {
    "payload_path": "graph_payload.bin",
    "payload_format": "columnar_v2",
    "node_count": 798,
    "edge_count": 1506,
    "digest": "sha256:..."
  },
  "metrics": {
    "function_count": 120,
    "class_count": 45,
    "calls_count": 890,
    "avg_complexity": 2.4,
    "high_blast_radius_count": 3
  },
  "generated_at": "2026-07-03T20:00:00Z"
}

Sanity checks

Golden repo (run after every phase): /Users/sshaaf/git/java/gbuilder
Override: RGBUILDER_DASHBOARD_GOLDEN_REPO=/path/to/repo

# One-shot phase gate (build UI + WASM + both tests)
./scripts/test-dashboard-golden.sh

# Or manually:
./scripts/build-dashboard.sh
cargo build --release
cargo test --release --test dashboard_bundle --test dashboard_gbuilder -- --nocapture

# Preview gbuilder dashboard
cd /Users/sshaaf/git/java/gbuilder/.rgbuilder/dashboard && python3 -m http.server 8765

Test targets

Shared assertions: tests/dashboard_harness.rs → assert_dashboard_bundle_with_meta().

Phase 2 artifacts

UI loads ./metagraph.json in the Graph tab (Sigma.js). At ≥50k source nodes, community_only is set: function_metrics.json carries schema metadata only (no per-function rows); use the metagraph and WASM node list for hotspots. member_indices are omitted from metagraph.json at this scale to keep export fast.

Phase 3 — LOD + filters

Worker protocol (v2):

Implementation status

Update this table when a phase lands.

Removed (Phase 0)

• crates/rgbuilder-export/src/html.rs (~2700 lines)
• export_html_dashboard public API
• Monolithic .rgbuilder/dashboard.html default output

Removed (Phase 4)

• all_analyses.json writer in discover (discover --with-cfg still writes per-function storage + archive)

Not yet removed (later phases)

• Discover-time blast radius string properties on nodes (Phase 6, dashboard only)

Query Guide (Phase 9)

The Query Guide tab (GuideView.tsx, dashboard/src/guideCliWorkflows.ts) documents CLI equivalents for each dashboard view. Workflows are validated against real repos via dashboard/scripts/validate-guide-cli-gbuilder.sh. End-user walkthrough: dashboard-user-guide.md.

Large-repo CFG (archive_only)

When function count exceeds the inline JSON budget, cfg_index.json sets detail_mode: "archive_only". The CFG and Dataflow tabs show a banner and load per-function records on demand from cfg_pdg.archive.bin sidecars (record_index_path, record_data_path).

PR checklist (every phase)

• Build — new behavior documented in this file
• Remove — deleted code listed in Implementation status
• Sanity — ./scripts/test-dashboard-golden.sh passes (gbuilder + tiny fixture)
• Docs — cli-getting-started path updated if user-visible