Architecture Diagram

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

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:

  bashCopy code
  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:

   bashCopy code
   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:

   bashCopy code
   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:

   bashCopy code
   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:

yamlCopy code
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

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

yamlCopy code
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)

yamlCopy code
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:

yamlCopy code
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:

yamlCopy code
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:

--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.

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

Engine

Assets