/architecture-diagram

name: architecture-diagram
description: 'Generate architecture diagrams as fully editable SVG with native AWS, Azure, and GCP icons for cloud diagrams, or hand-drawn generic icons for everything else. Optionally deliver a self-contained editable draw.io mxGraph companion. Deterministic layout computes zone nesting and orthogonal routing instead of hand-placed coordinates. Triggers on: "architecture diagram", "infra diagram", "system diagram", "deployment diagram", "topology diagram", "draw architecture", "AWS diagram", "Azure diagram", "GCP diagram", "cloud infrastructure diagram", "VPC diagram", "draw my AWS setup". Use when a user wants a static architecture diagram they can still edit afterward in Figma, Illustrator, Inkscape, or draw.io. NOT for architecture reviews, use architecture-reviewer.'
metadata:
  version: 2.4.0
  category: visualization
  tags: [architecture, diagram, svg, aws, azure, gcp, cloud, icons]
  difficulty: intermediate
  phase: build

Architecture Diagram Generator

Produces standalone, fully editable `.svg` files: real inlined vector icons (AWS/Azure/GCP official architecture icons, or a hand-drawn generic set for everything else), deterministic zone-aware layout, orthogonal connection routing, and real `<text>` labels. `deliver --emit drawio` additionally produces a self-contained editable `.drawio` mxGraph companion. SVG output uses zero raster images and zero `<use>` clones; draw.io output uses independently editable cells with local vector icon data and no remote image, external URL, or provider stencil dependency.

When to use this

| Situation | Use this skill? | |---|---| | "Draw our AWS/Azure/GCP architecture" | **Yes** | | "System topology diagram for docs" | **Yes** | | "I need to edit this diagram afterward in Figma" | **Yes** — this is the differentiator vs. every raster-output alternative | | Multi-cloud or hybrid (cloud + on-prem) diagram | **Yes** — mix `provider:` per node freely | | Interactive, click-through, or animated diagram | No — use `static-web-artifacts-builder` | | Hand-drawn / whiteboard-style sketch | No — use `tldraw` | | Data chart, plot, or dashboard | No — use `chart-clarity` | | Reviewing or critiquing an existing architecture | No — use `architecture-reviewer` | | Single-frame concept illustration with no components/connections | No — use `concept-to-image` |

Prerequisites

Run the following commands from this skill directory (`skills/architecture-diagram` in a checkout).

• `python3` with `pyyaml` installed (`uv run --with pyyaml python3 -m engine ...` if not already available).
• **Cloud-provider icons need a one-time, per-machine network fetch.** Icons are never bundled in this skill; their providers publish diagram-use terms, so `architecture-diagram` records each provider's source and terms in the local cache rather than redistributing icon assets. The first time a diagram needs a given provider's icons, run:

  python3 -m engine.fetch_icons --provider aws    # ~5s, 1037 icons
  python3 -m engine.fetch_icons --provider gcp    # ~5s, 297 icons
  python3 -m engine.fetch_icons --provider azure  # ~60s, 704 icons
  # or: --provider all

This builds a local cache (default `~/.cache/armory/cloud-icons`, override with `--cache-dir` or `$XDG_CACHE_HOME`) pinned to a specific `jgraph/drawio` commit, so output is reproducible. Each rendered cloud icon is verified against its manifest SHA-256 digest; `icon/digest-mismatch` fails closed and requires the provider cache to be rebuilt with `python3 -m engine.fetch_icons --provider <provider> --force`. Subsequent renders reuse the verified cache — no network needed after the first fetch per provider. `provider: generic` needs no fetch at all; it uses the bundled hand-drawn icon set in `references/icons-generic.md`.

Workflow

1. **Parse** the user's request: components (with descriptions), containment hierarchy (zones — VPC/Region/Resource Group/Subnet), connections (with semantic types if specified), and cloud provider(s). 2. **Resolve services to icons.** For each cloud component, read `references/services-aws.yaml`, `references/services-azure.yaml`, or `references/services-gcp.yaml` (whichever matches its provider) — or `references/icons-generic.md` for non-cloud — and note the exact slug to use as that node's `service` field. If a service genuinely has no icon in that provider's set (documented per-provider in each table), either pick the closest sibling category or leave `service` unset — the renderer falls back to a labeled placeholder rather than a wrong icon. 3. **Ensure the icon cache is warm** for every provider used (see Prerequisites). Skip this for `provider: generic`. 4. **Author the spec** — a small YAML file per `references/spec-format.md`: `title`, `direction` (`LR`/`TB`), `zones` (with `parent` for nesting), `nodes` (`id`, `label`, `service`, `zone`, `color`), `edges` (`id`, `from`, `to`, `label`, `type`). 5. **Validate without writing an artifact:**

   python3 -m engine validate spec.yaml --quality showcase --json

The receipt contains exact spec and candidate-artifact SHA-256 digests, validation counts, quality profile, composition status, and coded diagnostics. `validate` never touches an output path. For declared `sources`, add `--verify-sources`; it fail-closes against local Git commits, blobs, and inclusive line ranges from the spec's checkout. It requires an `origin` remote and never copies source content or contacts a remote service. Use `--layout-json` instead of `--json` when an agent needs the exact emitted node boxes, zone membership and boxes, routed edge waypoints, and edge-label rectangles for review. It also never writes SVG output. 6. **Deliver only a clean candidate:**

   python3 -m engine deliver spec.yaml -o diagram.svg --quality showcase --emit drawio --json

`deliver` stages the exact spec and candidate SVG beside the target, then atomically replaces every requested