diagrams-opus-qt/docs/plan/README.md

Pipeline Network Diagram Editor — Implementation Plan

A desktop diagram editor for drawing pipeline networks (water lines, power lines, gas, etc.), built with PyQt6 on the QGraphicsView / QGraphicsScene framework.

Tool selection (research outcome)

Candidate	Verdict
QGraphicsView framework (chosen)	Maximum control over custom SVG nodes, typed ports, orthogonal grid routing, arc crossings, flow animation. Mature, high item-count performance.
QtNodes (paceholder/nodeeditor)	Dataflow-centric, fixed node visuals, v3 breaking API — poor fit for grid-routed pipeline networks.
QuickQanava (QML)	Modern but connection routing in QML is the hard part; less control over orthogonal/arc routing.

Bindings: PyQt6 6.10 (apt, works with Python 3.14). Tests: pytest + pytest-qt, headless via QT_QPA_PLATFORM=offscreen.

Sources:

• https://github.com/paceholder/nodeeditor
• https://github.com/cneben/QuickQanava
• https://doc.qt.io/qt-6/qtwidgets-graphicsview-elasticnodes-example.html
• https://www.qt.io/blog/2017/01/19/should-you-be-using-qgraphicsview

---

Phase 0 — Project scaffolding

• Repo layout, requirements.txt, README.md, .gitignore
• pipeline_editor package skeleton + __main__ entry point
• pytest config + headless conftest (QApplication fixture)

Phase 1 — Domain model (no UI)

• PropertyType enum: string, int, float, bool, enum, color, catalogue_item, catalogue_items, value_list
• Property + PropertyGroup (grouped, editable/readonly, validation)
• Catalogue / CatalogueItem registry
• PortRelation registry (water/power/gas...) with color schemes + compatibility rules
• Port (id, name, relation, side/offset, direction)
• NodeModel, EdgeModel (ids, geometry, style, property groups)
• DiagramDocument — holds nodes/edges, emits change signals
• JSON serialization / deserialization (round-trip)

Phase 2 — Node library (feature #1)

• Bundled SVG node graphics (pump, tank, valve, junction, source, sink, transformer…)
• NodeTemplate = SVG + port configuration, organized into groups
• Left dock NodePanel: grouped tree with vector previews
• Drag-and-drop node template → canvas creates a node

Phase 3 — Canvas, scene & nodes

• CanvasView: zoom (wheel), pan, fit-to-view, rubber-band select
• Grid background (dots/lines), configurable size, snap-to-grid
• NodeItem: renders SVG, movable, selectable, edges follow on move
• Multi-select move, delete

Phase 4 — Ports & edges (features #2, #3, #5)

• Focused node reveals PortItem handles
• Port relation coloring + connection-compatibility feedback
• Drag from port → other node's port (or self) creates an edge
• Orthogonal routing along rectangular grid
• Config option: draw arc at line intersections/crossings
• EdgeItem styles: line style, head/tail decorations (arrow, circle, diamond, none)

Phase 5 — Property panel (feature #4)

• Right dock PropertyPanel: grouped property editors
• Editor widgets per type (string/int/float/bool/enum/color/catalogue/list)
• Two-way binding: edit → model → view refresh
• Geometry/title (presentation) group + physics group (length, diameter, flow rate, flow type)

Phase 6 — Mock calculation & flow animation

• FlowSolver: mock flow distribution across edges (conservation-ish heuristic)
• Per-edge flow value + direction
• FlowAnimator: animate direction (marching dashes) and volume (speed/width)
• Play/pause/stop controls

Phase 7 — Editing UX & configuration (added features)

• Undo/redo via QUndoStack (add/move/delete/connect/edit)
• Copy / paste / duplicate / delete
• Save / Open / New document (JSON)
• Export canvas to PNG / SVG
• Config dialog: grid size, snap, arc-on-crossing, color scheme, animation speed
• Multiple color schemes (light/dark + relation palettes)
• Toolbar + menus + status bar + keyboard shortcuts

Phase 8 — Tests (typical scenarios)

• Model: properties, catalogue, relations, serialization round-trip
• Routing: orthogonal path + arc-crossing generation
• Flow solver: conservation & direction on a small network
• Scene: create node via drop, connect ports, move node moves edge, delete cascades
• Property panel: edit propagates to model
• Undo/redo of add/move/connect/delete

Phase 9 — Polish

• README with run/test instructions and screenshots
• Final pass: lint, docstrings, sample document