diagrams-fable-qt/docs/plan/plan.md

Pipeline Network Diagram Editor — Implementation Plan

A Qt 6 desktop editor for drawing pipeline networks (water, power, gas, …) with grid-aligned routing, typed ports, grouped editable properties, styleable edges, and a mock flow-calculation with animated flow.

Tool selection (research summary)

Candidates evaluated (web research, July 2026):

Option	Verdict
QtNodes / paceholder nodeeditor	Mature model-view node editor, but built for dataflow graphs: connections are cubic curves only (no orthogonal/Manhattan routing), port placement limited to horizontal/vertical in/out layouts, no per-side port docking, no intersection decorations. Its node/port model would fight the pipeline-schematic requirements.
QuickQanava (QML)	Per-side port docks, but QML-centric; heavier stack, weaker fit for the widget-based property panel and offscreen unit testing.
yFiles	Real orthogonal routing, but commercial.
Custom editor on QGraphicsView (Qt Widgets)	Full control over orthogonal grid routing, arc jump-overs, SVG nodes with arbitrary port configs, relation-based connection rules. QGraphicsScene is battle-tested for exactly this (Elastic Nodes / Diagram Scene examples), integrates with QUndoStack, and tests run headless via the offscreen platform.

Decision: custom QGraphicsView-based editor, C++20, Qt 6 Widgets + Qt SVG, CMake + Ninja, Qt Test.

Sources:

• https://github.com/paceholder/nodeeditor
• https://qtnodes.readthedocs.io/en/master/overview.html
• https://qtnodes.readthedocs.io/en/stable/features.html
• http://cneben.github.io/QuickQanava/nodes.html
• https://doc.qt.io/qt-6/qtwidgets-graphicsview-elasticnodes-example.html
• http://docs.yworks.com/yfiles/doc/developers-guide/orthogonal_edge_router.html

Architecture

src/
  core/        # Qt-Core-only, headless-testable
    NodeType, PortSpec, Relation     # node/port/relation definitions
    Node, Edge, NetworkModel         # document model, connection rules
    Property, PropertySpec, Catalogue# typed grouped properties
    EdgeStyle                        # line style + end decorations
    Router                           # orthogonal routing + intersection arcs
    FlowSolver                       # mock flow distribution
    JsonIo                           # save/load
  scene/       # QGraphicsScene layer
    DiagramScene, NodeItem, PortItem, EdgeItem, GridView (bg grid, zoom/pan)
    FlowAnimator                     # animated flow overlay
    Commands                         # QUndoCommand set
  app/         # widgets
    MainWindow, NodePalette, PropertyPanel, SettingsDialog
resources/     # SVG node set, node-type & catalogue JSON
tests/         # Qt Test suites

Model layer is pure Qt Core (no scene), so connection rules, routing, solver and serialization are unit-testable offscreen. Scene items observe the model; edits go through QUndoCommands.

Checklist

1. Foundation

• Install Qt 6 (base, svg), ninja; verify cmake configure
• Project scaffold: CMakeLists (app + tests), .gitignore, README
• This plan committed under docs/plan

2. Core model

• Relations (water, gas, power, control, …) with per-scheme colors
• PortSpec: id, relation, direction (in/out/bidirectional), relative position on node
• NodeType: id, group, label, SVG path, port list, default size, property specs
• Node/Edge/NetworkModel: add/remove/move, connect with validation (relation match, direction, no self-port duplicates, occupancy)
• Signals for model→view sync

3. Property system

• Property types: String, Int, Float, Enum, CatalogueItem, CatalogueItems, Color, ValueList
• PropertySpec with group ("General", "Presentation", "Physics"), unit, limits, read-only flag
• Catalogue store (e.g. pipe series DN/material) loaded from JSON
• Default specs: node (title, color, rotation…), edge (title, length, diameter, flow rate, flow type, style props)

4. Routing

• Orthogonal (Manhattan) routing snapped to grid, port-direction-aware first segment
• Config: grid step, arcOnIntersection — arc jump-over where an edge crosses another
• Intersection computation between routed polylines
• Painter-path builder producing arcs over crossings

5. Scene / items

• Grid background + snap-to-grid
• NodeItem: shared QSvgRenderer per type, selection highlight, drag with snapping
• PortItem: visible on node focus/hover, colored by relation, click-drag to start edge
• Interactive edge creation with live preview, drop on compatible port only (highlight legal targets)
• EdgeItem: styles — line (solid/dash/dot, width, color), head/tail decorations (none, arrow, circle, diamond, bar), title label
• Color schemes: light / dark / high-contrast; per-relation edge & port colors

6. Application UI

• Node palette: grouped tree with SVG icons, drag & drop onto canvas (mime-encoded type id)
• Property panel: grouped editors per selected node/edge — line edit, spin boxes, combo (enum), catalogue pickers (single/multi), color button, string-list editor
• Settings dialog: grid size, snap, intersection arcs, color scheme
• Toolbar/menus, status bar with cursor position & zoom

7. Editing UX (added features beyond the brief)

• Node dragging (multi-selection), rubber-band selection
• Zoom with Ctrl+wheel (cursor-anchored), fit-to-view, pan with middle mouse
• Undo/redo for all edits (add, delete, move, connect, property change)
• Copy/paste/duplicate with offset; Delete removes nodes + attached edges
• Context menus on canvas/node/edge
• Save/load document as JSON; window state persistence
• Keyboard shortcuts (standard set)

8. Flow simulation mock

• FlowSolver: sources/sinks from node types, conservation-based distribution splitting flow by pipe conductance (diameter-driven), per-edge signed flow rate
• Animation: moving dashes along edge path; direction = flow sign, speed & density ∝ volume
• Run/stop simulation from toolbar; solver results shown in edge properties

9. Assets

• SVG set: source, tank, pump, valve, consumer, junction, generator, transformer, switch
• Node-type JSON with port configs; sample catalogues (pipe series, materials)
• Sample document for demo

10. Tests (Qt Test, offscreen)

• Model: create/connect validation matrix, port occupancy, delete cascades
• Properties: set/get, type safety, serialization round-trip
• Router: orthogonality, grid alignment, intersection arcs on/off
• Solver: conservation at junctions, distribution by diameter
• Undo/redo scenarios
• GUI: drop node from palette, drag node snapping, interactive connect, edge selection → property panel

11. Delivery

• All tests green in CI-able script (ctest)
• README with build/run instructions and screenshots
• Conventional atomic commits per module