# Pipeline Network Diagram Editor — Implementation Plan

An Electron desktop application for drawing and analyzing **pipeline / network
diagrams** (water lines, power lines, gas, etc.). Nodes are SVG symbols with
typed connection ports; edges are routed orthogonally along a grid and can
carry an animated mock flow.

## Tech stack (decided after research)

| Concern            | Choice                        | Why |
|--------------------|-------------------------------|-----|
| Shell              | **Electron**                  | Required by task |
| Diagram engine     | **JointJS core (`@joint/core`, MPL-2.0)** | Only free engine with custom SVG nodes **+** built-in ports **+** manhattan router **+** `jumpover` connector (arc-on-intersection). |
| UI panels / shell  | **React 18 + TypeScript**     | Ergonomic typed property panel & stencil. |
| Build              | **electron-vite (Vite 6)**    | Fast HMR, TS, main/preload/renderer split. |
| Tests              | **Vitest + jsdom**            | Headless testing of graph model, validation, flow, properties. |

Research sources:
- https://www.jointjs.com/blog/javascript-diagramming-libraries
- https://reactflow.dev/
- https://portalzine.de/visualize-this-open-source-diagram-tools-to-replace-gojs/

---

## Milestones & actionable checklist

### M0 — Project scaffold
- [x] Initialize `package.json`, TypeScript, electron-vite config
- [x] Electron main process + secure preload bridge (contextIsolation)
- [x] React renderer boots inside Electron with 3-pane layout (stencil | canvas | properties)
- [x] `npm run dev` launches, `npm run build` produces bundles
- [x] Vitest configured, suite green (52 tests)

### M1 — Diagram canvas (JointJS host)
- [x] `DiagramController` wraps a JointJS `Graph` + `Paper` (+ headless mode)
- [x] Rectangular background grid, configurable size
- [x] Pan (blank drag) + zoom (wheel/buttons) + fit-to-content
- [x] Selection model (click, shift/ctrl multi-select, select-all)
- [ ] Marquee (rubber-band) selection — *deferred*

### M2 — Node system (SVG symbols + ports)
- [x] Symbol registry: each symbol = SVG icon + port layout + default props
- [x] Seed symbol library grouped by domain (16 symbols across 5 categories)
- [x] Custom JointJS element renders symbol SVG + ports
- [x] Ports carry a **relation/medium** (water, power, gas, signal…) with color scheme
- [x] Focused/hovered node reveals its ports as connectable magnets

### M3 — Node panel (stencil)
- [x] Left panel lists symbols grouped by category, collapsible
- [x] Search/filter symbols
- [x] Drag symbol → drop onto canvas creates node at grid-snapped position
- [x] Live SVG preview thumbnails

### M4 — Edges / connectors
- [x] Draw edge by dragging from a port; snap to a compatible target port
- [x] **Connection validation** by port relation (compatible media only)
- [x] Orthogonal (manhattan) routing along the grid
- [x] Config toggle: **arc (jumpover) on line intersections** vs plain crossing
- [x] Edge style presets: line style (solid/dashed/dotted), width, color
- [x] Head/tail markers: none, arrow, open arrow, circle, diamond, bar
- [x] Vertices editable (link tools); re-route on node move

### M5 — Property panel (typed, grouped)
- [x] Reflects focused node **or** edge
- [x] Property groups (Identity / Presentation / Physics)
- [x] Editors for types: `string`, `int`, `float`, `enum`, `color`,
      `catalogueItem`, `catalogueItems`, `listOfValues`
- [x] Two-way binding: edit → model → canvas re-render
- [x] Validation (min/max, required, units)

### M6 — Catalogue system
- [x] Catalogue store (pipe materials, pump models, valve types) with typed fields
- [x] `catalogueItem` picker (single) and `catalogueItems` (multi)
- [x] Selecting a catalogue item seeds physics defaults (roughness, flow…)

### M7 — Mock calculation & flow animation
- [x] Flow solver mock: mass-conserving distribution from sources to sinks
- [x] Animate flow direction along edges (marching ants)
- [x] Animation speed & dash density encode flow **volume**
- [x] Color edges by flow magnitude (legend + residual readout)
- [x] Run / stop controls in toolbar

### M8 — Editing UX & configuration
- [x] Move/drag nodes with grid snapping
- [x] Delete (nodes + incident edges), copy/paste, duplicate
- [x] Undo / redo (snapshot history)
- [x] Keyboard shortcuts (Del, Ctrl+Z/Y, Ctrl+C/V, Ctrl+D, Ctrl+A)
- [x] Save / load diagram to JSON; New; export SVG
- [x] Settings dialog: grid size, snapping, jumpover, color scheme, theme
- [ ] Context menu on node/edge/canvas — *deferred*
- [ ] Alignment/distribution helpers, z-order — *deferred*
- [ ] PNG export, minimap — *deferred*

### M9 — Tests (typical scenarios)
- [x] Symbol registry & port relation resolution
- [x] Connection validation (compatible vs incompatible media)
- [x] Property model get/set, type coercion & validation
- [x] Catalogue pick seeds defaults
- [x] Add node / connect / delete lifecycle on the graph model
- [x] Serialization round-trip (save → load)
- [x] Flow solver conservation & direction
- [x] Router/jumpover configuration switch

### M10 — Polish & docs
- [x] README with screenshots / run instructions
- [x] Sample diagram auto-seeded on launch
- [x] Final plan checkmarks updated
- [x] End-to-end smoke verified in real Electron (see screenshots below)

---

## Features added beyond the original brief
- Undo/redo command history, copy/paste/duplicate, keyboard shortcuts
- Canvas panning, wheel zoom, fit-to-content
- Save/load (JSON) + export (SVG)
- Settings dialog (grid, snapping, jumpover, color scheme, light/dark theme)
- Catalogue-driven physics defaults
- Flow legend with live mass-balance residual, run/stop controls
- Symbol search in the stencil
- Headless controller mode (enables tests + potential server-side use)

## Verified screenshots
- `app-screenshot.png` — editor with the seeded network
- `app-flow.png` — a node selected (grouped properties) with flow animation running

## Deferred (nice-to-have, not implemented)
Marquee selection, right-click context menu, alignment/distribution & z-order
helpers, PNG export, minimap, and a flow "step" control.