# 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.