Draw.io Diagram Forge

Generate draw.io editable diagrams using AI-powered orchestrated workflow.

When to Use

• General diagram requests - "Create a diagram", "Draw me a chart", etc.
• Creating architecture diagrams (Azure, AWS, on-premises)
• Converting flowcharts, system diagrams from text descriptions
• Transforming existing images/screenshots into editable draw.io format
• Generating swimlane diagrams, sequence diagrams from Excel/Markdown

Prerequisites

Install extension: Draw.io Integration

Quick Start

Basic Usage

Create a login flow diagram

Generate an Azure architecture diagram with Hub-Spoke topology

Convert this Excel file to a flowchart

With Input Files

From inputs/requirements.md, create a system architecture diagram

Recreate this image (inputs/architecture.png) as an editable draw.io file

Output Formats

Output directory: outputs/

Workflow Overview

USER INPUT
    │
    ▼
┌─────────────────────────────────────────────────┐
│           FLOW ORCHESTRATOR                      │
│  ┌─────────────────────────────────────────┐    │
│  │ Internal Modules:                        │    │
│  │ • Analysis (input classification)        │    │
│  │ • Review (quality scoring)               │    │
│  │ • State (context management)             │    │
│  │ • Timeout (watchdog)                     │    │
│  └─────────────────────────────────────────┘    │
└─────────────────────────────────────────────────┘
    │
    ├──► MANIFEST GATEWAY (create manifest)
    │
    └──► SVG FORGE (generate diagram + validation)
    │
    ▼
COMPLETED (.drawio file)

Quality Gates

Iteration Limits

Advanced: Agent Delegation

For complex diagrams, explicitly invoke the orchestrator:

@flow-orchestrator Create a detailed microservices architecture from inputs/requirements.md

This triggers the full manifest → review → generation → review cycle.

Cloud Icon Usage

When generating cloud architecture diagrams, follow this icon selection logic:

Step 1: Detect Cloud Provider

Scan input for provider-specific keywords:

Step 2: Search for Matching Icon

For each cloud service mentioned:

1. Search the appropriate icon library for a matching icon
2. If found: Use the provider-specific format (see below)
3. If not found: Use a generic shape with the service name as label

Step 3: Apply Provider-Specific Format

Step 4: Fallback for Unknown Services

If no matching icon exists:

<!-- Generic rectangle with service name -->
<mxCell value="Custom Service" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" />

⚠️ Critical: Azure Format

<!-- ❌ WRONG - Will show blue square in VS Code -->
<mxCell style="shape=mxgraph.azure.front_door;..." />

<!-- ✅ CORRECT - Works everywhere -->
<mxCell style="aspect=fixed;image=img/lib/azure2/networking/Front_Doors.svg;..." />

Refer to [cloud-icons.md](references/cloud-icons.md) for detailed SVG paths and style examples.

Resources

References

Scripts

Cloud Icons (Azure/AWS)

To enable cloud icons in generated diagrams:

1. Open generated .drawio file in VS Code
2. Click "+ More Shapes" (bottom-left)
3. Enable: ✅ Azure, ✅ AWS
4. Click Apply

Troubleshooting

Technical Details

How It Works

AI generates XML/SVG text that renders as editable diagrams:

Natural Language  →  XML/mxGraphModel  →  Rendered Diagram
     ↑                    ↑                      ↑
  Human input        AI generates          SVG rendering

mxCell Completeness Rule

Required mxCells >= 2 + nodes + edges

• mxCell id="0" (root)
• mxCell id="1" (default parent)
• One mxCell per node (vertex="1")
• One mxCell per edge (edge="1")