diagrams-opus-tauri/docs/plan/README.md

Pipeline Network Diagram Editor — Implementation Plan

A desktop diagram editor for designing pipeline networks (water, power, gas …), built with Tauri v2 + React + TypeScript + Vite, using JointJS (@joint/core, MPL-2.0) as the diagramming engine.

Why JointJS

Chosen over React Flow / Rete / GoJS after research because it uniquely covers every hard requirement out of the box:

• Framework-agnostic SVG canvas with custom SVG markup for nodes → matches "nodes are defined by an SVG set with port configuration".
• First-class port model with port groups + validateConnection → relation-based connectability & color schemes.
• Built-in grid/orthogonal routers (manhattan, orthogonal) and a jumpover connector with jump: 'arc' → "lines drawn along rectangular grids" and the configurable "arc on intersection of lines".
• Rich link markup / markers → arrow / circle / diamond heads and tails.
• SVG attrs animation → animated flow direction & volume for the mock solver.

Architecture

src/
  model/      domain types: node & edge type defs, port types, relations,
              property schema, catalogues, color schemes  (pure, unit-tested)
  canvas/     JointJS shapes, paper/graph setup, routing, selection, tools
  calc/       mock flow-distribution solver + animation controller (unit-tested)
  store/      Zustand app store (selection, config, catalogues, document)
  panels/     React UI: NodePalette, PropertiesPanel, Toolbar, ConfigPanel
  io/         serialize / deserialize document, export PNG/SVG, Tauri fs bridge
  test/       vitest setup
src-tauri/    Tauri v2 Rust shell (file dialogs, fs plugin)

---

Milestones & Tasks

M0 — Project setup & tooling

• Research & select diagramming library (JointJS)
• Scaffold Tauri v2 + Vite + React + TS
• Install deps (@joint/core, zustand, vitest, testing-library, tauri plugins)
• Configure Vite (port 1420) + Vitest (jsdom, coverage)
• Write this plan
• Base app shell layout (palette | canvas | properties, top toolbar)
• CI-style scripts: test, test:run, lint, typecheck

M1 — Domain model (pure, tested)

• Port types & relation registry (which port types may connect)
• Connection validation function (canConnect(source, target, relations))
• Color schemes mapping port/relation types → colors (multiple presets)
• Property schema types: string,int,float,enum,catalogueItem,catalogueItems,color,list
• Property groups (presentation / identity / physics)
• Catalogue model (named collections of catalogue items)
• Node type definitions with SVG markup + port layout (pump, valve, tank, junction, source, sink, …)
• Edge style definitions (line styles + source/target markers)
• Default property values & validation/coercion per type

M2 — Canvas engine (JointJS)

• Paper + graph init, background grid, snap-to-grid
• Custom PipelineNode element (renders node-type SVG + ports)
• Custom PipelineLink with configurable markers & line styles
• Port rendering; show ports only when node focused/hovered
• Draw edge from a port; live validation highlight (valid/invalid)
• Grid routing (manhattan) + config toggle for jumpover arc connector
• Selection (single, multi, rubber-band) & focus highlighting
• Element tools: remove, boundary, resize; link tools: vertices, arrowheads, remove

M3 — Node palette

• Grouped, collapsible stencil of node types (vector previews)
• Search/filter
• Drag-and-drop node from palette to canvas (drop at cursor, snap)

M4 — Properties panel

• Reflects current selection (node or edge), empty state otherwise
• Grouped property editors, one per property type
• Editors: string, int, float, enum(select), color(picker), catalogueItem(select), catalogueItems(multi), list(add/remove rows)
• Two-way binding: edits write back to element & update canvas presentation
• Geometry props (position/size/rotation) & title reflected live

M5 — Editing UX (the "typical scenarios" often missed)

• Undo / redo (command stack)
• Delete, copy / cut / paste, duplicate
• Keyboard shortcuts (Del, Ctrl+Z/Y, Ctrl+C/V/X/D, Ctrl+A, Esc)
• Zoom (buttons + ctrl-wheel), pan (space/mmb drag), fit-to-content, reset
• Grid + snap toggles, background config
• Context menu on nodes/edges/canvas
• Rename via inline / properties title

M6 — Configuration

• Config panel: color scheme, arc-on-intersection, grid size/visibility, snap, router type, animation speed
• Persist config; live-apply to paper & links

M7 — Persistence & export

• Serialize document (graph + metadata + config) to JSON
• Save / Open via Tauri dialog + fs (graceful fallback to download/localStorage in browser)
• New document
• Export canvas to SVG and PNG

M8 — Mock calculation & flow animation

• Build network graph from nodes/edges (respect port direction)
• Assign supplies/demands from node physics props
• Flow-distribution solver (conservation at junctions, proportional split)
• Map per-edge flow → direction (sign) + volume (magnitude)
• Animate flow along edges (dash animation; speed ∝ volume, dir ∝ sign)
• Color/width edges by flow volume; run / stop / reset controls
• Report unbalanced nodes / disconnected components

M9 — Testing

• Unit: relation validation & color schemes
• Unit: property schema coercion/validation & catalogue resolution
• Unit: flow-distribution solver (linear, split, merge, cycle, unbalanced)
• Unit: document serialize/deserialize round-trip
• Component: palette renders groups; properties panel renders & edits
• Component: store actions (add node, connect, select, undo/redo)
• npm run test:run green; typecheck & lint clean

M10 — Polish & docs

• Seed demo network on first launch
• README with run/test instructions & feature list
• App icon / window sizing

---

Definition of done

• npm run test:run passes; npm run typecheck clean.
• npm run dev shows a working editor: drag nodes, connect ports with validation, edit grouped properties, toggle arc routing & color schemes, run the mock solver with animated flow, save/open/export.
• Conventional atomic commits throughout.