resolutionflow/docs/superpowers/plans/2026-04-13-network-diagram-drawio-style-implementation.md

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.