Cloud Architecture Diagrams (Azure / AWS / GCP)

Generate professional cloud architecture diagrams that match the house style of the official vendor reference architectures: dashed grouping zones (Power Platform / Azure / Data Source, or VPC / Subnet / Region), white rounded "cards" with a real product icon plus a bold title and a small description, directional and bidirectional arrows with labels, and optional numbered step badges.

The output is two editable files from one spec:

• \x3Cname>.excalidraw — JSON, opens at excalidraw.com (icons embedded as base64)
• \x3Cname>.drawio — mxGraph XML, opens at app.diagrams.net (icons embedded as data URIs)

Both are self-contained: the icons travel inside the file, so they render offline and survive being shared.

Why a spec + script instead of hand-placing shapes

Drawing the JSON/XML by hand is error-prone and the two formats drift apart. Instead you write ONE small spec (zones, nodes, edges) and a bundled script renders both files identically, fetches the right icons, embeds them, and routes the arrows. You spend your effort on the part that needs judgment — choosing icons and laying things out — not on file plumbing.

Icon sources (providers)

The skill knows ~3,900 icons across four providers, all bundled offline. Pick the one that matches the cloud you're drawing:

Always pin the provider in the spec ("provider": "aws", "azure", "gcp", or "microsoft"). For mixed Microsoft work (Power Platform + Azure) use "microsoft" (the default) or "providers": ["azure","microsoft"]. A single node can override with its own "provider" (e.g. an AWS diagram that also shows an Entra ID logo → that node uses microsoft).

GCP coverage is partial. The bundled Google set is a curated subset (core products + category tiles). Services not in it (e.g. Pub/Sub, Cloud Functions, Firestore, Dataflow) will fall back to labeled boxes. To get full coverage, download Google's complete official icon pack and import it with add_icon_pack.py --provider gcp (see "Refreshing or adding icon packs").

Workflow

0. Confirm which cloud (ASK if it's not obvious)

Before anything else, settle on the provider. If the user already made it clear — they said "AWS"/"Azure"/"GCP", named provider-specific services (S3, BigQuery, Power Automate…), or uploaded an image whose icons identify the cloud — just use that. If it's ambiguous, ask before building:

Which icon set should I use — Azure / Microsoft, AWS / Amazon, or GCP / Google?

Don't guess when it's unclear; the wrong icon set means redrawing the whole thing.

1. Understand the architecture

If the user described it in words: identify the logical groups (these become zones), the components in each (these become nodes), and how data flows between them (these become edges). Note any numbered sequence.

If the user uploaded an image of a diagram to recreate: read it carefully. List every grouping container, every icon/box (its title + any subtitle), the arrows (direction, any labels, any color coding), and any numbered step badges. Reproduce the structure and intent, not necessarily pixel positions. It's fine to tidy up spacing.

When the architecture is ambiguous or large, briefly confirm the component list and grouping with the user before generating — re-rendering is cheap but confirming intent first saves a wasted pass.

2. Resolve the icons (do this before writing the full spec)

Use the finder, scoped to the provider you're drawing, to pick the right icon for each component:

python scripts/find_icon.py "S3" --provider aws -n 4
python scripts/find_icon.py "BigQuery" --provider gcp -n 4
python scripts/find_icon.py "Azure AI Search" --provider azure,microsoft -n 4

It prints scored candidates with their provider and location. Pick deliberately:

• A score around 2+ or an exact name match is a confident hit.
• A score below ~0.9 means there's probably no good icon — plan to fall back to a plain labeled box (omit icon for that node), and tell the user.
• AWS abbreviations work directly: S3, EC2, VPC, IAM, SNS, SQS, ECS, EKS, RDS, ELB all resolve to the canonical service icon.
• GCP full names and short forms work: BigQuery/BQ, Compute Engine/GCE, Cloud Storage/GCS, GKE, Cloud Run, Vertex AI. Coverage is partial — if a service isn't found, fall back to a labeled box (or import the full pack).
• Microsoft renames things. If a modern name misses, try the legacy name. See the synonym list in references/spec-format.md (e.g. Azure AI Search is filed under Cognitive Search; Azure OpenAI under Open AI).
• Always pass --provider so an AWS query can't match an Azure icon (and vice versa).

If you're confident about a specific icon, pin it in the spec with "icon_url" (a msicons.com URL) to skip matching for microsoft; for bundled providers, just naming the service is reliable.

3. Write the spec

Create a JSON spec following references/spec-format.md. Set the spec "provider", then lay it out using the conventions documented there (left-to-right flow, zones as dashed containers, ~40px gaps, card size ~230×84). Keep coordinates on a rough grid so the result looks deliberate.

Start from assets/spec-example.json as a template — it's a real worked example you can adapt.

4. Generate both files

python scripts/build_diagram.py my_spec.json --out-prefix /mnt/user-data/outputs/my_diagram

This writes my_diagram.excalidraw and my_diagram.drawio, fetching and embedding every icon. It prints an icon-resolution report to stderr — read it: it tells you which query mapped to which icon and flags weak matches that fell back to a labeled box. Fix any wrong matches by editing the icon value (or pinning icon_url) and re-running.

Use --only excalidraw or --only drawio if the user wants just one.

Optional: native draw.io shapes

By default both files embed the icons as SVG (identical look, works everywhere). You can instead have the .drawio use draw.io's own built-in vector stencils — add "drawio_shapes": true to the spec (or pass --drawio-shapes):

python scripts/build_diagram.py my_spec.json --out-prefix out/dia --drawio-shapes

What this changes (drawio only — Excalidraw always stays embedded SVG):

• AWS → the official colored resourceIcon squares (mxgraph.aws4.*) with the correct category color baked in.
• GCP → self-colored mxgraph.gcp2.* stencils.
• Azure → mxgraph.azure.* (monochrome; limited set) — most Azure nodes have no native stencil and fall back to embedded SVG. microsoft (Power Platform, Dynamics 365, etc.) has no native draw.io vector stencils, so it always uses the bundled official SVGs — which are full-color and render in both formats.

Why use it: the shapes become first-class draw.io objects the user can recolor and restyle, and the file is much smaller (no base64). Why not: matching is best-effort against draw.io's version-specific stencil names, so preview the mapping first:

python scripts/find_drawio_shape.py "IAM" --provider aws -n 5

If a match is wrong, pin the exact stencil on that node with "drawio_shape": "mxgraph.aws4.identity_and_access_management_iam". Nodes without a confident native match automatically fall back to embedded SVG, so the diagram is never broken. (Note: I can't render .drawio to PNG here — the preview PNG shows the embedded-SVG version; confirm native shapes in diagrams.net.)

5. Preview and check

The inline Excalidraw tool can't show the embedded icons, so render a PNG:

python scripts/preview_png.py /mnt/user-data/outputs/my_diagram.excalidraw -o /tmp/preview.png

Open the PNG and check for: overlapping boxes, clipped arrow labels (short arrows can't hold long labels — widen the gap or shorten the label), arrows crossing through cards (add waypoints to that edge), and wrong/missing icons. Iterate on the spec until it's clean. Show the user this preview so they can see it without opening a file.

6. Deliver

Use present_files to give the user both files (and optionally the preview PNG). Tell them which opens where (excalidraw.com / app.diagrams.net) and that the icons are embedded so they can edit freely.

Refreshing or adding icon packs

The skill ships with a prebuilt index (references/icon-index.json) plus the bundled AWS and Azure SVGs, so normal use needs no network.

• Refresh the msicons.com (microsoft) set: python scripts/build_icon_index.py

• Add or update a bundled pack from a folder of SVGs you downloaded (e.g. a newer AWS Architecture Icons release, or an Azure icon pack):

  python scripts/add_icon_pack.py --source /path/to/unzipped/pack --provider aws
  

  It auto-detects AWS-style and Azure-style filenames, copies the chosen SVGs into assets/icons/\x3Cprovider>/, and merges them into the index (replacing any prior entries for that provider). To add a brand-new cloud (e.g. GCP), unzip its SVGs and import them under a new provider id.

What this skill does NOT do

• It won't invent icons that don't exist. Some logos simply aren't in any pack (msicons has no standalone SharePoint/Teams logo, for instance). When there's no good match, the node becomes a clean labeled box — say so.
• It draws from official vendor icon sets: AWS, Microsoft/Azure, and a curated Google Cloud set out of the box. GCP coverage is partial — import the full Google pack (or any other cloud) with add_icon_pack.py when needed.
• Don't mix providers blindly: pass --provider / set the spec provider so an AWS query can't pull an Azure or GCP icon.

Files in this skill

• scripts/find_icon.py — search/fetch icons by service name (--provider aware)
• scripts/build_diagram.py — spec → .excalidraw + .drawio (the engine)
• scripts/preview_png.py — render a .excalidraw to PNG for visual check
• scripts/build_icon_index.py — (re)build the msicons.com index
• scripts/add_icon_pack.py — import a local SVG pack as a new/updated provider
• scripts/bundle_microsoft.py — bundle the Microsoft set offline (official Power Platform + Dynamics 365 packs + msicons.com)
• scripts/find_drawio_shape.py — preview native draw.io stencil matches
• scripts/build_drawio_shape_index.py — (re)build the native-shape index from draw.io's stencil source
• references/spec-format.md — full spec schema, layout cookbook, icon synonyms
• references/icon-index.json — prebuilt unified icon index (aws + azure + gcp + microsoft)
• references/drawio-shape-index.json — native draw.io stencil index (aws + gcp + azure)
• assets/icons/aws/, assets/icons/azure/, assets/icons/gcp/, assets/icons/microsoft/ — bundled official SVGs (offline)
• assets/spec-example.json, assets/aws-spec-example.json, assets/gcp-spec-example.json — worked examples