# 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
- [x] Web research: select diagramming library (JointJS core)
- [x] 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