diagrams-fable-tauri/docs/plan/plan.md

Pipeline Network Diagram Editor — Implementation Plan

Desktop diagram editor for pipeline networks (water, gas, heat, power) built with Tauri 2 + React 18 + TypeScript + Vite + JointJS core (@joint/core, MPL-2.0).

Library selection (done via web research)

JointJS core was selected over React Flow, AntV X6, GoJS because it is the only open-source option with all hard requirements built in:

• SVG-markup-defined nodes with port groups and validateConnection / validateMagnet hooks → relation-based connection rules (water/gas/power…).
• manhattan / orthogonal / rightAngle routers → edges follow rectangular grid.
• jumpover connector → arcs at line intersections, toggleable per configuration.
• Rich link styling: source/target markers (arrows, circles, diamonds), dash patterns.
• Framework-agnostic core; React used for panels/UI around the canvas.

Rejected: GoJS (commercial license), React Flow (no built-in orthogonal routing or line jumps), AntV X6 (no jumpover arcs, weaker docs in English).

Architecture

src/                      # frontend (React + TS)
  model/                  # pure domain model — no JointJS imports, fully unit-testable
    properties.ts         # typed property system + groups
    catalog.ts            # catalogues (pipe series, materials…)
    nodeTypes.ts          # node type registry: SVG, ports, default props
    graph.ts              # document model: nodes, edges, (de)serialization
    validation.ts         # port relation compatibility rules
  editor/                 # JointJS integration
    shapes.ts             # JointJS element/link factories from node types
    paper.ts              # paper setup: grid, routing, jumpover, interactions
    edgeStyles.ts         # line styles, arrowheads/tails: arrow|circle|diamond|bar|none
    colorSchemes.ts       # port-relation color schemes (default/dark/high-contrast/mono)
  sim/
    flow.ts               # mock flow distribution solver (mass balance at junctions)
    animation.ts          # dash-offset flow animation, speed & width ∝ flow volume
  state/
    store.ts              # app state, selection, config
    history.ts            # undo/redo command stack
    clipboard.ts          # copy/paste
  ui/
    Palette.tsx           # grouped node palette, drag & drop onto canvas
    PropertyPanel.tsx     # grouped typed property editors
    Toolbar.tsx           # file ops, undo/redo, zoom, grid, simulate
    SettingsDialog.tsx    # configuration (arc-on-intersection, schemes, grid…)
    Canvas.tsx            # JointJS paper host
src-tauri/                # Rust shell, fs dialogs, save/load
tests/                    # vitest unit + component tests

Actionable items

Phase 0 — Research & scaffolding

• Web research: select diagramming library (JointJS core)
• Write implementation plan (this document)
• Init git repository, .gitignore, conventional commits
• Install Linux system deps for Tauri (webkit2gtk 4.1, librsvg, appindicator)
• Scaffold Vite + React + TS app, add @joint/core
• Add Tauri 2 shell (src-tauri), dev/build scripts
• Set up vitest + jsdom + testing-library

Phase 1 — Domain model

• Property system: string, int, float, enum, catalogueItem, catalogueItems, color, listOfValues with property groups (Presentation / Physics / General) and validation
• Catalogues: pipe diameter series, materials, media catalogues
• Port relations: water, gas, heat, power, signal + compatibility matrix
• Node type registry: SVG view, port layout per type (pump, valve, tank, source, consumer, junction/tee, heat exchanger, boiler, power supply, sensor…)
• Graph document model + JSON (de)serialization

Phase 2 — Editor canvas

• JointJS paper: rectangular grid, pan (space/drag), zoom (wheel), snap-to-grid
• Node shapes generated from SVG defs with ports
• Click node → show/highlight ports (magnets) available for linking
• Edge drawing from port to compatible port only (validateConnection by relation)
• Orthogonal (manhattan) edge routing along grid
• Config option: jumpover connector — arc on line intersections (on/off)
• Edge styles: line (solid/dashed/dotted), width, color; head & tail markers: arrow, circle, diamond, bar, none
• Port relation color schemes (≥3 schemes) applied to ports and edges

Phase 3 — Editing UX (the "missed features")

• Node dragging with grid snap
• Multi-select (shift-click + rubber-band), group move
• Delete node/edge (Del), with connected-edge cleanup
• Undo / redo (Ctrl+Z / Ctrl+Shift+Z) command stack
• Copy / paste / duplicate (Ctrl+C/V/D) with offset
• Edge vertex editing (drag to add bend points) via link tools
• Select-all (Ctrl+A), Escape clears selection
• Zoom to fit, zoom in/out buttons, reset zoom
• Keyboard nudge of selected nodes with arrow keys

Phase 4 — Panels

• Left palette: node types grouped by category, SVG thumbnails, drag onto canvas
• Palette search/filter
• Right property panel for focused node/edge: grouped, collapsible
• Editors per property type: text, int, float (with units), enum select, catalogue item picker, multi catalogue items, color picker, list-of-values editor
• Presentation group edits geometry live (x, y, angle, size; edge style)
• Physics group (length, diameter, flow rate, flow type…) stored on model
• Read-only computed properties (e.g. simulated flow) displayed

Phase 5 — Configuration & persistence

• Settings dialog: grid size, snap on/off, arc-on-intersection, router choice, color scheme, animation on/off
• Save / Load project as JSON via Tauri dialog + fs (browser fallback in dev)
• Export diagram as SVG
• New / clear document with confirm

Phase 6 — Mock calculation & animation

• Flow solver mock: sources with supply, consumers with demand, mass balance, proportional split at junctions by pipe cross-section
• Edge direction from solved flow (may oppose drawing direction)
• Animate flow: moving dashes along edges, speed ∝ flow volume, stroke width ∝ volume, direction arrows
• Simulation panel/toggle in toolbar; results written to read-only edge props

Phase 7 — Tests (vitest)

• Property system: creation, validation, groups, all 8 types
• Graph model: add/remove nodes & edges, serialization round-trip
• Connection validation: relation compatibility matrix scenarios
• Flow solver: chain, tee split, multi-source, disconnected, conservation
• History: undo/redo scenarios incl. transaction batching
• Catalogues: lookup, item resolution
• Component smoke tests: palette renders groups, property panel renders editors
• Full suite green: npm test (94 tests)

Phase 8 — Finish

• README with dev/build instructions
• cargo tauri build debug bundle succeeds (npm run tauri:build:debug)
• Check off all plan items