ai-generation

What this skill does

# AI-Powered Diagram Generation

## draw.io Built-in AI Generate Tool

draw.io includes a native AI diagram generation feature accessible from the editor.

### Accessing the AI Generator

1. Open draw.io (app.diagrams.net or desktop)
2. Click **Extras > AI Diagram** or the AI icon in the toolbar
3. Enter a natural language prompt
4. Select the AI model/provider
5. Click **Generate**

### Supported AI Models

| Provider | Models | Notes |
|----------|--------|-------|
| Google Gemini | 2.0 Flash, 2.5 Pro, 2.5 Flash | Free tier available |
| Anthropic Claude | 3.7 Sonnet, 4.0 Sonnet, 4.5 Sonnet | Requires API key |
| OpenAI GPT | 4o, 4.1, 4.1-mini, 5.1 | Requires API key |

### Configuration

Configure AI in draw.io via **Extras > Configuration** (JSON editor):

```json
{
  "enableAi": true,
  "gptApiKey": "sk-...",
  "geminiApiKey": "AIza...",
  "claudeApiKey": "sk-ant-...",
  "defaultAiModel": "claude-sonnet-4-20250514"
}
```

Or set via URL parameters:
```
https://app.diagrams.net/?enableAi=1
```

### AI Actions

| Action | Description |
|--------|-------------|
| `createPublic` | Generate a new public diagram from prompt |
| `create` | Generate a new diagram (private) |
| `update` | Modify an existing diagram based on instructions |
| `assist` | Get suggestions for improving the current diagram |

### Custom LLM Backend

Point draw.io to a custom/self-hosted LLM endpoint:

```json
{
  "enableAi": true,
  "aiBaseUrl": "https://your-llm-proxy.example.com/v1",
  "aiApiKey": "your-key",
  "aiModel": "your-model-name"
}
```

The endpoint must be compatible with the OpenAI Chat Completions API format.

---

## AI Diagram Generation Best Practices

### Use Simplified mxGraphModel Format

When generating diagrams via LLM, always use the simplified format without the `mxfile` wrapper. This reduces complexity and error rates:

```xml
<!-- CORRECT: Simplified format for AI generation -->
<mxGraphModel>
  <root>
    <mxCell id="0"/>
    <mxCell id="1" parent="0"/>
    <!-- diagram content -->
  </root>
</mxGraphModel>
```

```xml
<!-- AVOID: Full mxfile wrapper adds unnecessary complexity -->
<mxfile host="..." modified="..." agent="..." version="..." type="...">
  <diagram id="..." name="...">
    <mxGraphModel dx="..." dy="..." grid="..." ...>
      <root>
        <!-- diagram content -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>
```

### Always Include Structural Cells

Every generated diagram must start with the two mandatory structural cells:

```xml
<mxCell id="0"/>                <!-- Root cell -->
<mxCell id="1" parent="0"/>     <!-- Default layer -->
```

Omitting these causes the diagram to fail to load.

### Use Uncompressed XML

Always output uncompressed, human-readable XML. Never generate the base64-compressed format that draw.io uses internally for storage. draw.io imports uncompressed XML without issue.

### Reference Valid Style Properties

Only use documented style property names. Common mistakes:

| Wrong | Correct |
|-------|---------|
| `fill` | `fillColor` |
| `stroke` | `strokeColor` |
| `color` | `fontColor` |
| `border` | `strokeWidth` |
| `background` | `fillColor` |
| `bold` | `fontStyle=1` |
| `italic` | `fontStyle=2` |
| `font-size` | `fontSize` |
| `text-align` | `align` |
| `border-radius` | `rounded=1;arcSize=N;` |

### Ensure Unique IDs

Every cell must have a unique `id`. Use descriptive IDs for clarity:

```xml
<!-- GOOD: Descriptive IDs -->
<mxCell id="api-gateway" value="API Gateway" .../>
<mxCell id="auth-service" value="Auth Service" .../>
<mxCell id="edge-gw-to-auth" edge="1" source="api-gateway" target="auth-service" .../>

<!-- ACCEPTABLE: Sequential IDs -->
<mxCell id="2" value="API Gateway" .../>
<mxCell id="3" value="Auth Service" .../>
<mxCell id="e1" edge="1" source="2" target="3" .../>

<!-- BAD: Duplicate IDs -->
<mxCell id="node" value="API Gateway" .../>
<mxCell id="node" value="Auth Service" .../>  <!-- DUPLICATE -->
```

### Match Perimeter to Shape

When using non-rectangular shapes, set the matching perimeter:

| Shape | Required Perimeter |
|-------|-------------------|
| `shape=ellipse` | `perimeter=ellipsePerimeter` |
| `shape=rhombus` | `perimeter=rhombusPerimeter` |
| `shape=hexagon` | `perimeter=hexagonPerimeter2` |
| `shape=triangle` | `perimeter=trianglePerimeter` |
| `shape=parallelogram` | `perimeter=parallelogramPerimeter` |
| `shape=trapezoid` | `perimeter=trapezoidPerimeter` |
| `shape=step` | `perimeter=stepPerimeter` |

Mismatched perimeters cause connection points to appear in wrong positions.

---

## Prompt Engineering for Diagram Generation

### Effective Prompt Structure

A good diagram generation prompt includes:

1. **Diagram type**: Explicitly state what kind of diagram
2. **Entities/components**: List the key elements
3. **Relationships**: Describe how elements connect
4. **Style preferences**: Colors, themes, layout direction
5. **Detail level**: High-level overview vs. detailed implementation

### Example Prompts

#### System Architecture
```
Create a cloud architecture diagram showing:
- A React frontend hosted on CloudFront/S3
- API Gateway routing to Lambda functions
- Lambda connects to DynamoDB and S3
- SQS queue between Lambda and a worker Lambda
- All inside a VPC with public and private subnets
- Use AWS icon shapes
- Blue color scheme, orthogonal edge routing
```

#### Sequence Diagram
```
Create a UML sequence diagram for OAuth 2.0 authorization code flow:
- Participants: User, Client App, Auth Server, Resource Server
- Steps: authorization request, user login, auth code, token exchange, API call
- Show the redirect steps clearly
- Use dashed lines for responses
- Include activation boxes on Auth Server
```

#### Flowchart
```
Create a flowchart for a CI/CD pipeline:
- Start with code push
- Run linting and unit tests in parallel
- If tests pass, build Docker image
- Push to container registry
- Deploy to staging
- Run integration tests
- If pass, require manual approval
- Deploy to production
- End
- Use green for success paths, red for failure paths
- Horizontal swimlanes: Dev, CI, Staging, Production
```

#### ER Diagram
```
Create an ER diagram with Crow's foot notation for an e-commerce database:
- Tables: users, products, orders, order_items, categories, reviews
- Show primary keys, foreign keys, and key columns
- Users have many orders (1:N)
- Orders have many order_items (1:N)
- Products have many order_items (M:N through order_items)
- Products belong to categories (N:1)
- Users write reviews on products (M:N through reviews)
- Use table-style entity boxes with column lists
```

### Prompt Anti-Patterns

| Avoid | Why | Better |
|-------|-----|--------|
| "Make a diagram" | Too vague, no type specified | "Create a UML sequence diagram for..." |
| "Show everything" | Too broad, overwhelms the diagram | "Show the top-level components and their connections" |
| "Make it look nice" | Subjective, no actionable direction | "Use blue fill (#dae8fc), rounded corners, orthogonal edges" |
| "Add all the details" | Overloads the diagram | "Include service names, protocols, and port numbers" |
| Describing in paragraphs | Hard to extract structure | Use bullet points for entities and relationships |

---

## LLM-Generated Diagram Validation

### Validation Checklist

After generating a diagram, verify all of the following:

```
[ ] 1. Structural cells: id="0" (root) and id="1" (default layer) exist
[ ] 2. All IDs are unique across the entire document
[ ] 3. Every vertex has vertex="1" and mxGeometry with width/height
[ ] 4. Every edge has edge="1" and mxGeometry with relative="1"
[ ] 5. Edge source/target IDs reference existing vertex cells
[ ] 6. Parent references point to existing cells
[ ] 7. Style properties use exact camelCase names (fillColor not fill-color)
[ ] 8. Perimeter type matches shape type
[ ] 9. HTML labels have proper XML escaping (&lt; &gt; &amp;)
[ ] 10. Shapes don't overlap (distinct x, y positions)
[ ] 11. Shapes have reasonable dimens