chihlasm/resolutionflow
1
0
Fork 0
Code Issues 23 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: add network diagram draw.io-style implementation plan

Browse Source 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
chihlasm
2026-04-13 18:16:54 +00:00
parent a71f082e25
commit 760e0f77f8
1 changed files with 757 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

757
docs/superpowers/plans/2026-04-13-network-diagram-drawio-style-implementation.md Normal file
View File

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