29ec717b47
Document features, stack and layout; mark completed milestones and list deferred nice-to-haves; include verified Electron screenshots. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
129 lines
6.0 KiB
Markdown
129 lines
6.0 KiB
Markdown
# 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.
|