ilya/diagrams-opus-electron
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
diagrams-opus-electron/docs/plan/README.md
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

6.0 KiB
Raw Blame History

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.