Overview
This section documents the internals of the ZXW Graphboard app, for contributors. It assumes you have read the User Guide and are familiar with what the app does.
What it is
Section titled “What it is”A client-side-only Next.js app — an online graph editor for ZXW calculus. Users place
vertices, connect them with edges, assign phase labels, compute the tensor the diagram
represents, and export the graph as JSON. There is no backend: persistence is localStorage
plus manual file export/import, and the compute engine runs in the browser as WebAssembly.
Tech stack
Section titled “Tech stack”| Concern | Choice |
|---|---|
| Framework | Next.js 16 (App Router, Turbopack), React 19 |
| Canvas | @xyflow/react (React Flow) v12, controlled mode |
| State | Zustand v5 + zundo for undo/redo |
| Styling | Tailwind CSS v4 (config-less, via @tailwindcss/postcss) |
| Math typesetting | KaTeX |
| Icons | lucide-react |
| IDs | nanoid |
| Tests | Vitest (jsdom env) + Testing Library; cargo test / cargo llvm-cov for the Rust workspace |
| Compute | Rust workspace root (Cargo.toml): crate crates/zxw/ compiled to WASM via wasm-pack, run in a Web Worker |
| Package manager | pnpm (workspace; the docs submodule is excluded via !doc/**) |
Repository layout
Section titled “Repository layout”src/├── app/ # Next.js App Router entry (single page → GraphEditor)├── components/graph-editor/ # All editor UI (canvas, tab bar, toolbar, nodes, edges, panels)├── store/│ ├── graph-store.ts # Single Zustand store — source of truth (tabs + zundo)│ └── selectors.ts # Pure selectors over store state├── lib/│ ├── graph/ # Pure graph logic│ │ ├── types.ts # Barrel over type/ (runtime + persisted types)│ │ ├── type/ # vertex-types.ts, edge-types.ts, editor-types.ts│ │ ├── vertex-registry.ts# VERTEX_TYPES / VERTEX_TYPE_MAP + predicates│ │ ├── edge-registry.ts # EDGE_KIND_MAP│ │ ├── operations.ts # Create/delete, click dispatch, clipboard, boundary│ │ │ # ordering, grid snapping (GRID_SIZE / snapPosition)│ │ ├── validate.ts # Pre-compute structural checks (→ validationErrors)│ │ ├── stats.ts # Pure graph statistics for the properties dialog│ │ └── edge-geometry.ts # Pure edge endpoint math (rotation-aware)│ ├── serialisation/ # Persistence boundary + export formats│ │ ├── document.ts # projectToDocument / hydrateDocument (graph ↔ view)│ │ ├── parse.ts # parseDocument / parseWorkspace / importGraphJson + migrations│ │ ├── storage.ts # localStorage save/load (tabs wrapper of v2 docs)│ │ ├── export-*.ts # one serializer per export format│ │ └── formats.ts # registry + getExportFormat│ ├── compute/ # Frontend wrapper around the Rust/WASM compute layer│ │ ├── index.ts # computeTensor() entry point + Web Worker lifecycle│ │ ├── worker.ts # the worker; lazy-loads the wasm│ │ ├── types.ts # main↔worker message protocol│ │ ├── result-types.ts # TS mirror of the Rust TensorResult│ │ ├── errors.ts # ComputeError class + error classifier│ │ └── matrix-format.ts # tensor → matrix display math│ ├── keyboard/shortcuts.ts # Display-only shortcut registry│ ├── hooks/useTrackedDraft.ts│ ├── hooks/useCompute.ts # Compute lifecycle (promise/progress/abort)│ ├── hooks/useKatexReady.ts # Re-render signal for lazy KaTeX│ ├── onboarding/intro.ts # First-run intro gate (localStorage flag)│ ├── label/renderLabel.ts # Label → HTML (KaTeX or plain text)│ ├── label/katex-loader.ts # Lazy-loads KaTeX as a separate chunk│ ├── phase/parser.ts # Phase expression parser (numeric v1)│ ├── download.ts # File System Access API + fallback│ └── filename.ts # Title → safe filename└── test-utils/factories.ts # makeVertex / makeEdge for testscrates/zxw/ # Rust compute layer (ZXW tensor evaluation)crates/cartographer/ # Git submodule — Rust research CLI (treewidth), kept for later integrationCargo.toml # Cargo workspace root (members: zxw + cartographer; default-members: zxw)doc/plans.md # Compute-backend plan & contract (status block at top)scripts/build-wasm.sh # wasm-pack driverHigh-level data flow
Section titled “High-level data flow”The editing loop and the compute loop share the same serialization boundary but are otherwise independent:
┌──────────────┐ read slices ┌─────────────────────────┐ │ Components │ ◀─────────────── │ useGraphStore (Zustand)│ │ (React Flow │ │ + zundo temporal │ │ + panels) │ ── actions ───▶ │ (single source of truth)│ └──────┬───────┘ └───────────┬─────────────┘ │ │ calls │ ▼ │ ┌──────────────────────────┐ │ onNodesChange/ │ src/lib/graph/ │ │ onEdgesChange │ operations.ts (pure) │ └──────────────────────────┤ src/lib/serialisation/ │ └───────────┬──────────────┘ project / hydrate │ ┌───────────────────────────────┴───────────────┐ ▼ ▼ ┌──────────────────────────┐ ┌──────────────────────────────┐ │ localStorage + JSON file │ │ validateGraphForCompute() │ │ (v2 GraphDocuments — N │ │ → per-vertex errors in the │ │ in a "tabs" wrapper; │ │ store's validationErrors │ │ export = active tab) │ │ computeTensor(graph) │ └──────────────────────────┘ │ → Web Worker → WASM │ │ → TensorResult + warnings │ │ (reads only doc.graph) │ └──────────────────────────────┘Key principle: components never hold graph data in local state — they read slices from the
store and dispatch actions, and all mutation logic lives in src/lib/graph/operations.ts, called
from the store, not inline in components. React Flow runs in controlled mode: nodes/edges
come from the store, and onNodesChange/onEdgesChange route back through store actions. The
compute path is separate: the toolbar takes a one-off projectToDocument(...) snapshot of the
graph slice, runs validateGraphForCompute (structural errors land per-vertex in the store’s
validationErrors and light up the offending vertices), and hands doc.graph to computeTensor —
it never touches the store (see Compute Layer).
Documentation map
Section titled “Documentation map”One owner per topic — the app repo’s docs don’t duplicate each other:
AGENTS.md(main repo root) — the operating manual: commands, layout, architecture invariants, persistence rules. The authoritative reference this section mirrors.doc/plans.md(main repo) — the compute-layer design contract; its status block at the top says which phases have landed (Phases 0–5 landed, Phase 6 not started).- This docs site (
doc/zxw-graphboard-doc/submodule) — user-facing: user guides + these dev docs. It is a git submodule excluded from the pnpm workspace (!doc/**in the mainpnpm-workspace.yaml) and has its own build. README.md(main repo) — a thin pointer doc: quickstart + links to the above.
Where to go next
Section titled “Where to go next”- State Management — the store, the tab workspace, the undo/redo policy, and the gesture controller pattern.
- Graph Model — the
graph/viewdocument split, the runtime ↔ persisted boundary, handle-id mapping. - Labels & Phases — how vertex labels render with KaTeX (including lazy-loading), how they parse as phase expressions, and how the two stay in sync.
- Compute Layer — the Rust/WASM tensor engine, the Web Worker, the result and error model.
- Contributing — setup, commands, conventions, and the gotchas to know before changing editor behaviour.