# 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
- [x] Install Qt 6 (base, svg), ninja; verify cmake configure
- [x] Project scaffold: CMakeLists (app + tests), .gitignore, README
- [x] This plan committed under docs/plan

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

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

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

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

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

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

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

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

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

### 11. Delivery
- [x] All tests green in CI-able script (`ctest`)
- [x] README with build/run instructions and screenshots
- [x] Conventional atomic commits per module