architecture-diagram · v2.4.0 · 2026-09-05 · sha256 0e09c028a09c5e8d
architecture-diagram v2.4.0A
Immutable. This exact content never changes and is served at /api/v1/blob/0e09c028a09c5e8d.
---
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:
```bash
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:**
```bash
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:**
```bash
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 output only after every check passes. `--emit drawio` also delivers `diagram.drawio`; the JSON receipt's top-level `artifacts` list records the path, SHA-256, and byte count for each committed file. With `--verify-sources`, it atomically delivers `diagram.svg`, `diagram.drawio`, and `diagram.sources.json`; the SVG and draw.io output carry local `VERIFIED SRC n` badges, while the sidecar binds verified references to the delivered SVG digest. Caught write or replacement failures restore the prior bundle; process termination between replacements is outside that rollback contract.
7. **Review a draw.io companion before handoff:**
1. Open `diagram.drawio` in draw.io.
2. Confirm that a zone, node container, icon, node label, edge, and edge label select independently.
3. Move a node label and save. The output preserves authored structure and initial computed placement; it does not promise round-trip SVG bytes or manual-route preservation.
8. **Compare authored revisions when needed:**
```bash
python3 -m engine compare base.yaml head.yaml
```
`compare` emits a JSON receipt keyed only by authored node and edge ids. It reports added, removed, changed, moved, and rerouted entities with exact field paths. Its mandatory limitation is: `Authored specification only; no runtime impact, causality, risk, or merge safety is inferred.`
9. **Output** the final `.svg` and requested `.drawio` companion to the working directory or user-specified path. Mention the icon-cache prerequisite only if this was the first render for a given provider.
## Spec fields at a glance
Full schema and worked examples: `references/spec-format.md`. Summary:
```yaml
title: string
direction: LR | TB # default LR
provider: aws | azure | gcp | generic # default provider for nodes that omit it
profile: deployment-ownership # opt-in blocking deployment checks
sources:
- id: string # unique authored reference id
revision: 40-char hex # declared Git object id
path: relative POSIX path
lines: [start, end] # positive inclusive range
zones:
- id: string
label: string
parent: string | null # nesting — omit for a top-level zone
kind: generic | region | security # default generic
nodes:
- id: string # unique
label: string
sublabel: string # optional secondary line
service: string # icon cache slug — see services-aws.yaml / services-azure.yaml / services-gcp.yaml
provider: string # overrides the top-level provider for this node
zone: string | null # zone id this node belongs to
color: "#RRGGBB" # icon fill color
owner: string # required for non-external nodes under deployment-ownership
external: boolean # default false
storage: boolean # true requires a security zone under deployment-ownership
sources: [source-id] # optional declared source ids
edges:
- id: string # required and stable when using compare
from: string # node id
to: string # node id
label: string # required for security-boundary crossings under deployment-ownership
type: realtime | batch | event | control | default
sources: [source-id] # optional declared source ids
```
### Deployment ownership validation
Set `profile: deployment-ownership` only when the spec is a deployment ownership record rather than a visual-only diagram. The profile fails closed: every node must resolve to exactly one `kind: region`, every non-external node needs a non-blank `owner`, every `storage: true` node must be inside `kind: security`, and a cross-security-zone edge needs a non-blank label naming its mechanism. It never infers those facts from labels, icons, service slugs, or layout. Omit `profile` to preserve existing behavior.
## Connection type semantics
| type | color | style | use for |
|---|---|---|---|
| `realtime` | blue | solid | REST, gRPC, synchronous requests |
| `batch` | red | dashed | SFTP, file transfer, scheduled jobs |
| `event` | green | solid | pub-sub, webhooks, event-driven triggers |
| `control` | orange | solid | management plane, monitoring, config push |
| `default` | gray | solid | when semantics are unspecified or only one flow type exists |
A legend renders automatically whenever more than one connection type is used in a diagram; it's omitted entirely when every edge is `default`.
## Unsupported / partial coverage
- **Kubernetes and on-premises providers** have no dedicated icon set yet — model them with `provider: generic` (server, container, database, queue, and 31 other hand-drawn glyphs in `references/icons-generic.md`, 35 total) until a future milestone adds native K8s/on-prem icon coverage.
- **GCP and Azure icon coverage is narrower than AWS's** (297 and ~700 icons vs. 1037). `references/services-aws.yaml`, `references/services-azure.yaml`, and `references/services-gcp.yaml` each document that provider's specific gaps (e.g. GCP has no dedicated Vertex AI or Artifact Registry icon; Azure has no dedicated Pipelines/Boards/Artifacts icon) rather than silently substituting a misleading icon.
- **Interactive elements** (click-through, animation, mode toggles) are out of scope — this skill produces one static SVG. Use `static-web-artifacts-builder` for that.
- **PNG/PDF export** isn't built in. Pipe the SVG through a converter afterward if a raster format is needed: `rsvg-convert diagram.svg -o diagram.png` or `cairosvg diagram.svg -o diagram.pdf`.
## Common patterns
### AWS serverless API
```yaml
title: Serverless API — us-east-1
provider: aws
direction: LR
zones:
- id: vpc
label: VPC 10.0.0.0/16
nodes:
- id: cf
label: CloudFront
service: cloudfront
color: "#8C4FFF"
- id: apigw
label: API Gateway
service: api-gateway
zone: vpc
color: "#E7157B"
- id: fn
label: Lambda
service: lambda
zone: vpc
color: "#ED7100"
- id: ddb
label: DynamoDB
zone: vpc
service: dynamodb
color: "#C925D1"
edges:
- {from: cf, to: apigw, label: HTTPS, type: realtime}
- {from: apigw, to: fn, label: invoke, type: realtime}
- {from: fn, to: ddb, label: query, type: realtime}
```
### Azure web app (top-to-bottom)
```yaml
title: Azure Web App
provider: azure
direction: TB
nodes:
- {id: user, label: User, color: "#6B7280"}
- {id: gw, label: App Gateway, service: application-gateways, color: "#0078D4"}
- {id: app, label: App Service, service: app-services, color: "#0078D4"}
- {id: db, label: SQL Database, service: sql-database, color: "#0078D4"}
edges:
- {from: user, to: gw, label: HTTPS}
- {from: gw, to: app}
- {from: app, to: db, label: TDS}
```
### Multi-cloud pipeline
Mix providers freely — set `provider` per node instead of at the top level:
```yaml
title: Multi-Cloud Data Pipeline
direction: LR
nodes:
- {id: ingest, label: Kinesis, provider: aws, service: kinesis, color: "#8C4FFF"}
- {id: transform, label: Dataflow, provider: gcp, service: cloud-dataflow, color: "#4285F4"}
- {id: notify, label: Logic Apps, provider: azure, service: logic-apps, color: "#0078D4"}
edges:
- {from: ingest, to: transform, label: stream, type: event}
- {from: transform, to: notify, label: alert, type: event}
```
### Vendor-neutral / on-prem
Omit `service` (or set `provider: generic`) for nodes with no cloud icon — they render as a colored placeholder with the label's first letter:
```yaml
title: On-Prem 3-Tier
provider: generic
direction: LR
nodes:
- {id: lb, label: Nginx, color: "#3A3A3A"}
- {id: app, label: App Servers, color: "#3A3A3A"}
- {id: db, label: PostgreSQL, color: "#3A3A3A"}
edges:
- {from: lb, to: app}
- {from: app, to: db}
```
## Handling ambiguity
- Infer zone nesting from naming conventions (Region > VPC > Subnet, Resource Group > VNet > Subnet).
- Default to `default` connection type and no legend when the user doesn't specify flow semantics.
- Default to `LR` direction for request/data-flow diagrams, `TB` for hierarchical or layered ones.
- Use `provider: generic` and the hand-drawn icon set when no cloud provider is specified or the architecture is vendor-neutral.
- Ask for clarification only when the component list or topology is fundamentally unclear — never when a single icon is missing (fall back per Unsupported above).
## Exit codes and diagnostics
Every finding is a coded diagnostic carrying `code`, `severity`, `message`, `subject` (what it is about), `evidence` (the numbers that locate it), `supported_fixes` (spec-level moves), and sometimes `suppresses`. The exit code is the verdict:
| Exit | Meaning | Action |
|---|---|---|
| 0 | `validate` completed with no error findings, or `deliver` atomically committed a validated SVG bundle | Hand off the receipt and requested artifacts; any warnings are deliberate, explainable tradeoffs |
| 1 | A blocking finding or operational delivery failure | Apply a diagnostic's `supported_fixes`, or correct the output path or filesystem permissions |
| 2 | Usage error — missing subcommand, unreadable spec path, unknown flag or profile value | Correct the command |
`--json` prints the receipt and nothing else on stdout. It contains `input` and primary-SVG `artifact` SHA-256/byte records, `output.written`, `validation.checks_passed`/`checks_total`, quality, composition status, severity counts, and diagnostics. When `--emit drawio` is present, `artifacts` lists every committed output with its path, SHA-256, and byte count. `--quality showcase` raises `composition/*` route-geometry findings to errors; the default `standard` keeps them as warnings.
| Code | Meaning | Fix |
|---|---|---|
| `spec/*` | The spec is unanswerable: no nodes, duplicate or missing ids, unknown zone/parent/edge endpoint, zone cycle, empty zone | Each diagnostic's `supported_fixes` names the field to change |
| `icon/not-found` | The `service` slug is absent from that provider's cache, or the cache was never fetched | Use the exact slug from that provider's reference service map, or run `fetch_icons.py --provider <name>`; drop `service` to take the labeled placeholder deliberately |
| `layout/node-overlap` | Two node boxes collide | Separate the nodes across ranks, or remove the duplicate |
| `layout/zone-overlap` | Two unrelated zone boxes collide because their member nodes are interleaved | List each zone's members contiguously in `nodes`, or fix the `zone` assignments |
| `layout/label-overflow` | A `label` or `sublabel` cannot fit in its node box at the hard 6px minimum (blocking) | Shorten it, or move detail into `sublabel` |
| `editability/*` | The output contains raster, `<use>`, or an external reference | Renderer bug — a spec cannot cause this; report it |
| `usage/spec-unreadable` | The spec path does not exist or cannot be read | Pass an existing, readable YAML path |
A fetch failure (`could not fetch <provider> icons`) is a network problem, not a spec problem: rerun `fetch_icons.py` for that provider, which skips already-cached icons.
## Output
Report the SVG path, requested draw.io companion path, and any warning-severity findings left unresolved and why. Mention the icon-cache fetch cost only on the first render for a given provider.
## Reference table
| File | Contents | Read when |
|---|---|---|
| `references/spec-format.md` | Full YAML spec schema, field-by-field, with edge cases | Always, before authoring a spec |
| `references/services-aws.yaml` | AWS service name → icon slug + color, ~70 entries, documented gaps | Diagramming AWS components |
| `references/services-azure.yaml` | Azure service name → icon slug + color, ~45 entries, documented gaps | Diagramming Azure components |
| `references/services-gcp.yaml` | GCP service name → icon slug + color, ~35 entries, documented gaps | Diagramming GCP components |
| `references/icons-generic.md` | 35 hand-drawn generic icons (server, database, queue, user, …) for non-cloud diagrams | `provider: generic`, or any node with no cloud equivalent |
| `references/editability.md` | Why the output never uses `<use>`/raster/outlined text, and what "editable" actually verifies | Understanding or modifying the renderer's output contract |
## Engine
| File | Purpose |
|---|---|
| `engine/__main__.py` | `python3 -m engine` entry point for validate, deliver, and compare. |
| `engine/pipeline.py` | Deterministic spec → SVG composition and render result. |
| `engine/commands.py` | Validation, delivery, comparison receipts, staging, and CLI dispatch. |
| `engine/fetch_icons.py` | Local icon-cache builder; invoke with `python3 -m engine.fetch_icons`. |
| `engine/stencil2svg.py` | AWS/GCP stencil-to-SVG converter — internal. |
| `engine/svg_inline.py` | Azure real-SVG inliner/namespacer — internal. |
| `engine/data.py` | Single resolver for bundled assets and reference data. |
## Assets
| File | Contents |
|---|---|
| `assets/example-serverless.yaml` | A complete, real spec (AWS, zones, mixed connection types) — copy as a starting point |
| `assets/example-serverless.svg` | That spec's actual rendered output, committed for reference |
| `assets/generic-icons.json` | The data `BundledGenericIconLookup` reads; `references/icons-generic.md` is this same content in agent-readable form |