History

Ilya Ashikhmin 29ec717b47 docs: add README, screenshots and finalize plan checklist

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>

2026-07-02 23:41:19 +02:00

app-flow.png

docs: add README, screenshots and finalize plan checklist

2026-07-02 23:41:19 +02:00

app-screenshot.png

docs: add README, screenshots and finalize plan checklist

2026-07-02 23:41:19 +02:00

README.md

docs: add README, screenshots and finalize plan checklist

2026-07-02 23:41:19 +02:00

README.md

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:

Milestones & actionable checklist

M0 — Project scaffold

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

M1 — Diagram canvas (JointJS host)

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

M2 — Node system (SVG symbols + ports)

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

M3 — Node panel (stencil)

Left panel lists symbols grouped by category, collapsible
Search/filter symbols
Drag symbol → drop onto canvas creates node at grid-snapped position
Live SVG preview thumbnails

M4 — Edges / connectors

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

M5 — Property panel (typed, grouped)

Reflects focused node or edge
Property groups (Identity / Presentation / Physics)
Editors for types: string, int, float, enum, color, catalogueItem, catalogueItems, listOfValues
Two-way binding: edit → model → canvas re-render
Validation (min/max, required, units)

M6 — Catalogue system

Catalogue store (pipe materials, pump models, valve types) with typed fields
catalogueItem picker (single) and catalogueItems (multi)
Selecting a catalogue item seeds physics defaults (roughness, flow…)

M7 — Mock calculation & flow animation

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

M8 — Editing UX & configuration

Move/drag nodes with grid snapping
Delete (nodes + incident edges), copy/paste, duplicate
Undo / redo (snapshot history)
Keyboard shortcuts (Del, Ctrl+Z/Y, Ctrl+C/V, Ctrl+D, Ctrl+A)
Save / load diagram to JSON; New; export SVG
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)

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

M10 — Polish & docs

README with screenshots / run instructions
Sample diagram auto-seeded on launch
Final plan checkmarks updated
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.