cluster-topo-viz

Render a GPU cluster topology in three layers, as a single static HTML file with embedded data. No framework, no server, no interaction — open in a browser and see it.

Workflow

1. Collect — gather raw data from the live cluster. Reach collection.md when collecting via ssh (probe script, zsh gotcha, dual-perspective iblinkinfo dedup). Skip when the user already has data files.
2. Parse — normalize raw outputs into the data contract. Reach data-contract.md for the exact JSON shape. Completion: topology.json validates — every node, switch, and GPU pair present, no raw regex leftovers.
3. Render — copy templates/topo-demo.html and assets/topo-base.css into the output directory, embed the JSON at the /*__DATA__*/ slot, adjust the three layer sections to what the data actually has. Completion: browser opens the file and renders every layer with no JS console errors; numbers in the stats bar match the data (grep-checkable, not eyeball).
4. Cross-check — spot-verify against sources: GPU pair count vs nvidia-smi topo -m matrix, switch uplink counts vs iblinkinfo line count, degraded nodes vs nodes with < 8 GPUs. Completion: every discrepancy explained or fixed.

The three layers

Always render top-down; each layer reads the one below it:

• Stats bar — cluster totals (nodes, GPUs, switches, links). One .stat card per number.
• Fabric layer — one block per IB fabric plane. Switch cards on top, host cards below, links as low-opacity bezier curves (rail structure becomes visible at ~0.2 opacity without spaghetti). Host cards show GPU slot chips (8 slots, NUMA-colored, red for failed GPUs).
• Node layer — compact grid of all GPU nodes (degraded nodes get a red border), then ONE representative node expanded: GPUs in two NUMA rows around a central NVSwitch bar. Full-mesh NVLink is drawn as GPU→NVSwitch spokes, never as n² pairwise lines — the NVSwitch IS the mesh's correct abstraction.

Visual language (tokens live in topo-base.css)