From 760e0f77f80c3c67c7f102d57e96af56a2dc6d6d Mon Sep 17 00:00:00 2001 From: chihlasm Date: Mon, 13 Apr 2026 18:16:54 +0000 Subject: [PATCH] docs: add network diagram draw.io-style implementation plan Co-Authored-By: Claude Sonnet 4.6 --- ...ork-diagram-drawio-style-implementation.md | 757 ++++++++++++++++++ 1 file changed, 757 insertions(+) create mode 100644 docs/superpowers/plans/2026-04-13-network-diagram-drawio-style-implementation.md diff --git a/docs/superpowers/plans/2026-04-13-network-diagram-drawio-style-implementation.md b/docs/superpowers/plans/2026-04-13-network-diagram-drawio-style-implementation.md new file mode 100644 index 00000000..9dd2f9a2 --- /dev/null +++ b/docs/superpowers/plans/2026-04-13-network-diagram-drawio-style-implementation.md @@ -0,0 +1,757 @@ +# Network Diagram Editor — Draw.io-Style Implementation Document + +> **Date:** 2026-04-13 +> **Status:** Proposed +> **Audience:** Product, frontend, backend, and agentic workers +> **Goal:** Build a production-grade network diagram editor inside ResolutionFlow that feels close to draw.io while staying MSP- and topology-focused. + +--- + +## Executive Summary + +ResolutionFlow should implement network diagrams as a first-class editor surface, not as a lightweight canvas utility. The right target is not "clone draw.io exactly," but "deliver draw.io-grade editing quality for MSP network topology work." + +The recommended path is: + +1. **Use the existing network-diagram branch architecture as the foundation** +2. **Ship the already-proven CRUD/editor shell as Phase 1** +3. **Invest the next phases in interaction quality, editor commands, and interoperability** +4. **Keep a ResolutionFlow-native JSON schema as the source of truth** +5. **Add draw.io compatibility at import/export boundaries, not at the storage layer** + +This preserves delivery speed while giving the product room to grow into a robust diagramming tool. + +--- + +## Product Goal + +Build a network diagram creation tool that: + +- Feels familiar to users who already know draw.io +- Supports MSP workflows better than a generic diagramming app +- Makes manual editing fast and safe +- Supports AI-assisted generation and clean-up without depending on AI for correctness +- Fits ResolutionFlow's existing frontend/backend architecture cleanly + +Success is not measured by raw feature count alone. Success means a user can open the editor and confidently: + +- Create a clean network map from scratch +- Drag devices from a stencil palette onto a canvas +- Connect, label, group, align, copy, duplicate, and organize elements quickly +- Save and revisit diagrams safely +- Export the result for documentation and client communication + +--- + +## Existing Repo Context + +ResolutionFlow already has strong signals for this direction: + +- The main architecture is React 19 + Vite + TypeScript on the frontend, FastAPI + PostgreSQL on the backend. +- There are existing design and plan docs for network diagrams: + - `docs/superpowers/specs/2026-04-04-react-flow-ui-network-diagrams-design.md` + - `docs/superpowers/specs/2026-04-04-network-diagram-ux-improvements-design.md` + - `docs/superpowers/plans/2026-04-04-react-flow-ui-network-diagrams.md` + - `docs/superpowers/plans/2026-04-04-network-diagram-ux-improvements.md` +- Git history shows a substantial prior implementation on `feat/network-map-builder-prod`. + +That branch already included: + +- Backend model, schema, migration, API routes, and AI generation service +- Frontend list page and editor page +- React Flow-based canvas +- Device registry and custom node types +- Context menu, copy/paste/duplicate shortcuts, and drag/drop improvements +- Inspector/properties panel +- Import/export JSON + +This is important: **the best implementation path is to revive and harden that architecture, not to invent a parallel one.** + +--- + +## Non-Goals + +The first implementation should not try to become a full whiteboard platform. + +Out of scope for the initial milestone: + +- Real-time multiplayer collaboration +- Comments/presence/cursors +- Arbitrary slide decks or presentation features +- BPMN/UML/general enterprise diagram libraries +- Full draw.io parity on day one +- Replacing ResolutionFlow's tree editor architecture + +The editor should stay focused on network topology and MSP documentation use cases. + +--- + +## User Experience Target + +The editor should feel close to draw.io in the following ways: + +- Fast drag/drop from a left stencil panel +- Predictable selection behavior +- Context menus and keyboard shortcuts +- Snap-to-grid and alignment affordances +- Resizable groups and containers +- Good edge routing options +- Easy text and label editing +- Familiar import/export workflows + +The editor should exceed draw.io in MSP-specific workflows: + +- Device types that reflect real client environments +- AI-generated starting diagrams from text descriptions +- Client and asset metadata +- Future hooks into PSA, assets, tickets, and documentation + +--- + +## Recommended Architecture + +### Frontend + +Use a dedicated feature area: + +- `frontend/src/pages/NetworkDiagrams/` +- `frontend/src/components/network/` +- `frontend/src/api/networkDiagrams.ts` +- `frontend/src/types/network-diagram.ts` + +Use React Flow as the canvas/rendering engine. + +Why React Flow: + +- Already used conceptually in the codebase +- Strong node/edge rendering model +- Good selection/dragging/viewport primitives +- Enough flexibility for custom nodes, groups, and edge styles +- Faster path to production than building custom canvas behavior from scratch + +### Backend + +Use a document-style data model stored in PostgreSQL JSONB: + +- `network_diagrams` table +- JSONB `nodes` +- JSONB `edges` +- Metadata columns for account scoping, names, timestamps, archive state + +Why document storage: + +- Flexible schema evolution +- Fast implementation +- Simple import/export +- Easy autosave +- Works well with editor-state persistence + +### Source of Truth + +Use a ResolutionFlow-native schema as the system of record. + +Do not store draw.io XML as the primary database format. + +Instead: + +- Store native JSON internally +- Import from draw.io into native JSON +- Export native JSON to draw.io-compatible XML when needed + +This keeps the application decoupled from an external vendor format. + +--- + +## Recommended File Layout + +### Frontend + +- `frontend/src/pages/NetworkDiagrams/index.tsx` + - Diagram list page + +- `frontend/src/pages/NetworkDiagrams/DiagramEditor.tsx` + - Editor orchestration layer + +- `frontend/src/components/network/NetworkCanvas.tsx` + - React Flow wrapper and viewport surface + +- `frontend/src/components/network/DiagramHeader.tsx` + - Save state, title, metadata actions, export/import controls + +- `frontend/src/components/network/ContextMenu.tsx` + - Node/canvas context menus + +- `frontend/src/components/network/CanvasEmptyPrompt.tsx` + - Empty-state guidance + +- `frontend/src/components/network/panels/DeviceToolbar.tsx` + - Stencil palette and searchable device library + +- `frontend/src/components/network/panels/PropertiesPanel.tsx` + - Inspector for node/edge editing + +- `frontend/src/components/network/panels/AIAssistPanel.tsx` + - AI generate/merge UX + +- `frontend/src/components/network/hooks/useCanvasShortcuts.ts` + - Keyboard shortcuts and clipboard behavior + +- `frontend/src/components/network/hooks/useDiagramCommands.ts` + - Shared command layer for actions invoked by keyboard, menus, and toolbar + +- `frontend/src/components/network/nodes/*` + - Node components, registry, types, and render configuration + +- `frontend/src/components/network/edges/*` + - Edge components and routing styles + +- `frontend/src/api/networkDiagrams.ts` + - CRUD, import/export, AI generation, duplication + +- `frontend/src/types/network-diagram.ts` + - Shared client-side typing + +### Backend + +- `backend/app/models/network_diagram.py` + - SQLAlchemy model + +- `backend/app/schemas/network_diagram.py` + - Pydantic request/response models + +- `backend/app/api/endpoints/network_diagrams.py` + - CRUD + import/export + AI routes + +- `backend/app/services/network_diagram_ai_service.py` + - AI generation and later AI clean-up/layout assistance + +- `backend/alembic/versions/074_add_network_diagrams_table.py` + - Initial schema migration + +- `backend/app/models/network_diagram_version.py` + - Later addition for version history + +- `backend/app/api/endpoints/network_diagram_versions.py` + - Later addition for restore/history flows + +--- + +## Data Model + +### V1 Database Model + +The existing JSONB storage pattern is good for a first release: + +- `id` +- `account_id` +- `name` +- `client_name` +- `asset_name` +- `description` +- `nodes` JSONB +- `edges` JSONB +- `thumbnail_url` +- `is_archived` +- `created_by` +- `created_at` +- `updated_at` + +### Recommended Node Schema + +Use a richer internal node shape than a minimal device-only object. The schema should be resilient enough to support future features without painful migration. + +Recommended fields: + +- `id` +- `kind` + - `device | group | text | shape | image` +- `type` + - device slug or shape subtype +- `label` +- `position` +- `size` +- `rotation` +- `zIndex` +- `parentId` +- `ports` +- `style` +- `data` + +Examples: + +- `kind=device`, `type=router` +- `kind=group`, `type=subnet` +- `kind=text`, `type=label` + +### Recommended Edge Schema + +- `id` +- `source` +- `target` +- `sourcePort` +- `targetPort` +- `label` +- `routing` + - `straight | step | orthogonal | curved` +- `waypoints` +- `style` +- `data` + +### Why This Matters + +The prior branch stored a solid but fairly lean `DiagramNode`/`DiagramEdge`. That is enough to start, but draw.io-like editing will need more than just `position`, `label`, and `connectionType`. + +If we adopt the richer shape early, we reduce future rework in: + +- manual bend-point support +- z-ordering +- groups/containers +- text/shape nodes +- port-specific connections + +--- + +## Editor State Model + +The editor should be built around four distinct layers of state: + +### 1. Persisted Diagram State + +What is saved to the backend: + +- nodes +- edges +- metadata + +### 2. Editor UI State + +What lives only in the browser while editing: + +- selected node IDs +- selected edge IDs +- open context menu +- active tool +- inspector visibility +- drag-over state +- clipboard reference + +### 3. Derived View State + +- filtered palette items +- current selection bounds +- whether paste is available +- whether align/distribute commands are valid + +### 4. History State + +- undo stack +- redo stack +- last autosave timestamp + +The editor page should orchestrate these, but command logic should not be scattered across component trees. + +--- + +## Command System + +To make the tool feel like draw.io, add a shared command layer. + +Recommended hook: + +- `frontend/src/components/network/hooks/useDiagramCommands.ts` + +This hook should expose commands like: + +- `copySelection` +- `pasteSelection` +- `duplicateSelection` +- `deleteSelection` +- `selectAll` +- `fitView` +- `bringToFront` +- `sendToBack` +- `alignLeft` +- `alignCenter` +- `alignRight` +- `alignTop` +- `alignMiddle` +- `alignBottom` +- `distributeHorizontally` +- `distributeVertically` +- `groupSelection` +- `ungroupSelection` +- `lockSelection` +- `unlockSelection` + +All of the following should call the same command functions: + +- keyboard shortcuts +- toolbar buttons +- context menu items +- future command palette entries + +This avoids duplicate logic and keeps behavior consistent. + +--- + +## Phase-by-Phase Delivery Plan + +## Phase 1 — Foundation MVP + +### Objective + +Ship a usable network diagram editor quickly using the existing branch shape. + +### Scope + +- Diagram list page +- Create/edit/archive/duplicate +- React Flow canvas +- Searchable device palette +- Device and group nodes +- Edge creation +- Properties panel +- Save + autosave +- Import/export ResolutionFlow JSON +- Basic AI generation from natural language +- Context menu +- Keyboard shortcuts: + - copy + - paste + - duplicate + - select all + - fit view + - delete + +### Frontend Work + +- Restore `NetworkDiagrams` page routes and navigation +- Restore `DiagramEditor` +- Restore `NetworkCanvas` +- Restore node/edge registries +- Restore clipboard + context menu behavior +- Add command-layer extraction if time allows + +### Backend Work + +- Restore migration, model, schemas, endpoints +- Validate account scoping and tenant isolation +- Restore import/export endpoint +- Restore AI generate endpoint + +### Acceptance Criteria + +- User can create and save a network map +- User can reopen it later +- User can drag devices from palette onto canvas +- User can connect nodes and label links +- User can copy/paste/duplicate/delete +- User can import/export JSON +- User can generate a starter diagram from text + +--- + +## Phase 2 — Draw.io-Grade Editing Quality + +### Objective + +Close the biggest UX gap between a basic node editor and a real diagramming tool. + +### Scope + +- Snap-to-guides in addition to snap-to-grid +- Alignment commands +- Distribution commands +- Multi-select improvements +- Better z-order handling +- Inline text editing +- Better group/container behavior +- Rich edge routing choices +- Manual bend points +- Port-aware connection handling +- Keyboard nudging and modifier behavior + +### New/Expanded Files + +- `hooks/useDiagramCommands.ts` +- `hooks/useSelectionBounds.ts` +- `components/network/guides/*` +- `components/network/edges/*` + +### Acceptance Criteria + +- Multi-select editing feels reliable +- Align/distribute work predictably +- User can produce a polished topology without fighting the canvas +- Connectors can be shaped intentionally rather than only auto-routed + +--- + +## Phase 3 — Interoperability and Export + +### Objective + +Let the editor fit real customer and internal documentation workflows. + +### Scope + +- SVG export +- PNG export +- PDF export +- Thumbnail generation +- Draw.io XML import +- Draw.io XML export + +### Implementation Notes + +Do not try to mirror every draw.io primitive internally. + +Instead: + +- Build a compatible subset for network maps +- Translate supported draw.io elements into native nodes/edges/groups/text +- Emit supported native diagrams back into draw.io XML +- Warn on unsupported constructs during import + +### Acceptance Criteria + +- A diagram can be exported for customer-facing documentation +- A supported draw.io network map can be imported into ResolutionFlow +- Users can move work between tools without losing essential topology content + +--- + +## Phase 4 — ResolutionFlow-Native Differentiation + +### Objective + +Make this better than a generic diagram editor for MSP use cases. + +### Scope + +- AI merge into existing topology +- AI tidy-up / auto-layout refinement +- Asset-aware device metadata +- Client templates +- Common MSP topology starter kits +- Diagram-to-ticket or diagram-to-flow linking +- Version history and restore + +### Acceptance Criteria + +- AI helps users start faster and clean up faster +- Diagrams connect to the rest of the ResolutionFlow product +- Version history reduces fear of experimentation + +--- + +## Draw.io Parity Matrix + +| Capability | Priority | Notes | +|-----------|----------|-------| +| Drag/drop stencil palette | P0 | Must feel immediate and stable | +| Node resize/move/select | P0 | Core editor behavior | +| Edge creation and labeling | P0 | Core topology use case | +| Copy/paste/duplicate/delete | P0 | Expected baseline | +| Context menu + keyboard shortcuts | P0 | Must be fast and familiar | +| Snap-to-grid | P0 | Already supported directionally | +| Align/distribute | P1 | Big usability leap | +| Grouping/containers | P1 | Important for subnets, rooms, racks | +| Edge routing modes | P1 | Necessary for professional-looking diagrams | +| Inline text editing | P1 | Draw.io expectation | +| Layers/lock/hide | P2 | Useful once diagrams get large | +| Draw.io import/export | P2 | Important for migration and adoption | +| Realtime collaboration | P3 | Valuable, but not early priority | + +--- + +## Risks and Mitigations + +### Risk: Editor complexity balloons too quickly + +**Mitigation** + +- Keep the MVP narrow +- Use phased delivery +- Center everything around the command layer + +### Risk: React Flow abstraction limits parity + +**Mitigation** + +- Validate manual bend points, grouping, and selection ergonomics early +- If a specific advanced behavior is awkward, implement it in a focused extension layer instead of abandoning React Flow entirely + +### Risk: Import/export compatibility becomes a trap + +**Mitigation** + +- Support a documented subset of draw.io semantics +- Keep native JSON as the canonical internal model +- Warn clearly on unsupported import constructs + +### Risk: AI-generated diagrams feel impressive but unreliable + +**Mitigation** + +- Treat AI output as a starting point only +- Keep editing UX first-class +- Make merge mode explicit and safe + +### Risk: Users lose work through autosave/history gaps + +**Mitigation** + +- Add diagram versioning soon after MVP +- Preserve a local dirty-state guard +- Add explicit "saved at" feedback + +--- + +## Versioning Recommendation + +Version history should be planned early, even if shipped after the MVP. + +Recommended table: + +- `network_diagram_versions` + - `id` + - `diagram_id` + - `account_id` + - `snapshot` JSONB + - `created_by` + - `label` + - `created_at` + +Recommended triggers for version creation: + +- explicit "Save Version" +- before destructive import-replace +- before AI replace mode +- optionally every N minutes when dirty changes are substantial + +This is one of the highest-leverage additions for user trust. + +--- + +## Testing Strategy + +### Frontend + +- Unit-test command logic +- Unit-test serialization/deserialization +- Component-test context menu and shortcut behavior +- E2E test core editor flows: + - create diagram + - drag node + - connect nodes + - save and reload + - copy/paste + - import/export + +### Backend + +- API tests for CRUD +- API tests for tenant isolation +- API tests for import/export validation +- API tests for duplicate/archive +- AI endpoint tests with mocked provider output + +### Manual QA + +Required flows: + +- New blank diagram +- Existing diagram edit +- Large diagram performance +- Multi-select behavior +- Keyboard shortcut guard behavior while inputs are focused +- Import malformed JSON +- AI merge into populated canvas + +--- + +## Suggested Delivery Order + +### Slice 1 + +- Restore backend migration/model/schema/router +- Restore types and API client +- Restore list page + +### Slice 2 + +- Restore editor shell and canvas +- Restore nodes, edges, palette, save/load + +### Slice 3 + +- Restore context menu, clipboard, shortcuts, inspector +- Validate dirty-state and autosave behavior + +### Slice 4 + +- Restore AI generation and merge mode +- Tighten import/export UX + +### Slice 5 + +- Implement command layer +- Add align/distribute/z-order polish + +### Slice 6 + +- Add version history +- Add export polish and thumbnails + +### Slice 7 + +- Add draw.io XML import/export subset + +--- + +## Recommended Immediate Next Step + +The best immediate implementation move is: + +1. **Rebase or selectively port `feat/network-map-builder-prod` into the current codebase** +2. **Use that as the Phase 1 foundation** +3. **Do not start by rewriting the editor architecture** + +That approach is faster, lower risk, and already aligned with the repo's documented direction. + +--- + +## Worker Notes + +If agentic workers implement this plan, they should: + +- Reuse the existing network-diagram branch structure where possible +- Avoid introducing a second diagram architecture +- Keep native JSON as the canonical schema +- Treat command centralization as a priority, not an afterthought +- Ship MVP behavior first, then polish toward draw.io parity in focused slices + +--- + +## Summary + +ResolutionFlow can support a draw.io-like network diagram editor without fighting its current stack. The prior network-diagram branch already proves the right foundation: + +- React Flow canvas +- FastAPI CRUD +- JSONB persistence +- device registry +- AI assist +- context menus +- keyboard shortcuts +- import/export + +The real work now is not deciding whether to build it. The real work is: + +- restoring that foundation cleanly, +- formalizing the internal schema, +- adding a reusable command system, +- and iterating on the editor interactions until the experience feels professional. + +That path gives ResolutionFlow a practical, high-value network topology tool quickly, while preserving a credible route to near-draw.io quality over the next phases.