drawio

# Draw.io Architecture Diagrams

Generate Azure architecture diagrams in `.drawio` format using the
simonkurtz-MSFT Draw.io MCP server. The server ships the full Azure icon set
(see [`assets/azure-public-service-icons/`](../../../assets/drawio-libraries/azure-icons)),
fuzzy shape search, batch operations, group/layer/page management, and
transactional mode for efficient multi-step workflows.

The MCP server's own `src/instructions.md` is the authoritative tool reference;
it is auto-sent to the client at startup. This skill captures project-specific
conventions that complement (not duplicate) it.

> **Naming note**: "drawio" can refer to (a) this skill, (b) the MCP server slug
> `simonkurtz-MSFT/drawio-mcp-server`, or (c) the `mcp_drawio_*` tool family. In
> agent-facing references, disambiguate explicitly — say "the `drawio` skill" or
> "the drawio MCP server", not bare `drawio`.

## Prerequisites

- **MCP server**: `simonkurtz-MSFT/drawio-mcp-server` (Deno, stdio) configured in `.vscode/mcp.json`
- **Deno runtime**: installed via devcontainer feature
- **VS Code extension** (optional): `hediet.vscode-drawio` for in-editor preview

## MCP Workflow Summary

The MCP server's startup `src/instructions.md` is the authoritative tool reference. The
table below lists the most-used tools and the repo-specific batch sequence. Reusable call
patterns: [`references/azure-patterns.md`](references/azure-patterns.md).

| Tool                         | Purpose                                                              |
| ---------------------------- | -------------------------------------------------------------------- |
| `search-shapes`              | Fuzzy-search the Azure icon library; resolves names to shapes        |
| `create-groups`              | Create container cells (VNets, subnets, resource groups, envs)       |
| `add-cells`                  | Add vertices + edges in a single batch (use `shape_name`, `temp_id`) |
| `add-cells-to-group`         | Assign children to group containers                                  |
| `edit-cells` / `edit-edges`  | Update cell or edge properties post-creation                         |
| `validate-group-containment` | Detect children that exceed group bounds                             |
| `finish-diagram`             | Resolve transactional placeholders + emit final compressed XML       |
| `export-diagram`             | Non-transactional export with `compress: true`                       |

Standard sequence: `search-shapes` → `create-groups` → `add-cells` → `add-cells-to-group`
→ (optional `edit-*`) → `validate-group-containment` → `finish-diagram` /
`export-diagram` (`compress: true`).

> **`import-diagram` input contract (CRITICAL — Phase D3 of nordic-foods
> lessons plan)**: when calling `import-diagram` (or any tool whose schema
> declares an `xml` parameter), the field **MUST be XML content as a
> string** — never a file path. Passing a bare `path/to/file.drawio`
> string produces `INVALID_XML` from the server and burns an MCP round
> trip. If you have a path on disk:
>
> ```text
> WRONG: import-diagram(xml="agent-output/foo/03-des-diagram.drawio")
> RIGHT: read_file("agent-output/foo/03-des-diagram.drawio") → import-diagram(xml=<content>)
> ```
>
> Mirror this warning in `04-design.agent.md` next to every
> `import-diagram` reference. The two locations must stay in sync.

## CLI Fallback

**There is no programmatic CLI fallback for diagram authoring.** The Draw.io desktop app
is the only manual alternative; if the MCP server is unavailable, stop and surface the
failure rather than hand-rolling XML. The `tools/scripts/save-drawio.py` and
`cleanup-drawio.py` helpers are post-processing utilities for MCP output, not authoring
fallbacks.

## Icon Handling

Icons are resolved automatically by the MCP server from its built-in library
(the full Azure icon set bundled with the server).

- `shape_name` in `add-cells` specifies an Azure icon (e.g., `"Front Doors"`).
  **Do NOT** pass `width`, `height`, or `style` alongside it — the server applies them.
- `search-shapes` with a `queries` array finds icon names by fuzzy match.
- Azure icons use official service names, often plural (`"Key Vaults"`, `"Container Apps"`).
- Every shaped vertex MUST have a `text` label or omit `text` entirely — never pass `""`.
- Output format is embedded base64 SVG in the style attribute.

## Diagram Creation Workflows

Two modes — **non-transactional** (small diagrams, full XML each call) and
**transactional** (recommended for multi-step; lightweight placeholders during
the loop, real SVGs resolved by `finish-diagram` at the end). Full call chains,
the `save-drawio.py` save procedure, and the post-save cleanup script live in
[`references/creation-workflows.md`](references/creation-workflows.md).

> **Critical**: transactional mode MUST end with `finish-diagram(compress: true)`
> or the saved diagram keeps placeholder cells instead of real Azure icons.

## Rules

- **Batch-only workflow** — every tool that accepts an array MUST be called exactly ONCE with all items; never call a tool repeatedly for individual items (see [Batch-Only Workflow (CRITICAL)](#batch-only-workflow-critical) below)
- **Use `shape_name` for Azure icons** — do NOT pass `width`, `height`, or `style` alongside it; the server applies them
- **Every shaped vertex MUST have a `text` label or omit `text` entirely** — never pass `""`
- **Vertices first in `add-cells`** — edges must be ordered after the vertices they reference
- **Transactional mode for multi-step diagrams** — use placeholders + `finish-diagram` at the end (~2KB intermediate vs ~200KB)
- **Use `compress: true`** on `export-diagram` / `finish-diagram` to keep `.drawio` files small
- **Do NOT pipe large MCP JSON back through the LLM** — use `python3 tools/scripts/save-drawio.py` to extract via terminal
- **Out of scope**: WAF / cost charts (use `python-diagrams`), inline Mermaid (use `mermaid`)

## Steps

**Every tool that accepts an array MUST be