Skip to content

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.

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.

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/**)
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 tests
crates/zxw/ # Rust compute layer (ZXW tensor evaluation)
crates/cartographer/ # Git submodule — Rust research CLI (treewidth), kept for later integration
Cargo.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 driver

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).

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 main pnpm-workspace.yaml) and has its own build.
  • README.md (main repo) — a thin pointer doc: quickstart + links to the above.
  • State Management — the store, the tab workspace, the undo/redo policy, and the gesture controller pattern.
  • Graph Model — the graph/view document 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.