/architecture — Architecture Diagram Generator

Create professional architecture diagrams using the Draw.io MCP server (drawio/create_diagram) with verified Azure and AWS icons, and save them to the customer engagement repo's architecture/ folder.

Platform Compatibility

This skill runs on macOS, Linux, and Windows. Detect the OS first and pick the right syntax. See _shared/PLATFORM.md (skills repo root) for the full reference.

Note: the icon-catalog grep examples in this skill use bash. On Windows PowerShell, substitute Select-String -Pattern "<pattern>" -Path "$HOME/.copilot/skills/drawio-mcp-diagramming/references/<catalog>.txt".

Core Principles

• Customer-scoped output. All diagrams are saved to ~/customer-engagements/{slug}/architecture/ with a descriptive filename and committed to git.
• Azure-first defaults. Default to Azure icons and patterns unless the user specifies AWS or multi-cloud. Azure2 image-based icons are the primary style.
• Preserve bilingual labels. Section headings are always English. Service labels and annotations stay in their original language — do not translate content.
• Verified icons only. Never use an icon path or shape name in a diagram unless it has been confirmed by grepping the static catalogs. Unverified icons will not render.
• Clean before dense. Start with a clean, readable layout (3-4 lanes, left-to-right flow). Add detail only when the user explicitly asks.

Prerequisite Auto-Install

Before running, verify all dependencies are present. Install anything missing automatically.

Required Sibling Skills

This skill requires the following sibling skill from the same repository (https://github.com/roie9876/clawpilot-skills):

Check if it is installed:

# macOS / Linux
[ -f "$HOME/.copilot/skills/customer-repo/SKILL.md" ] && echo "✅ customer-repo" || echo "❌ customer-repo MISSING"

# Windows
if (Test-Path "$HOME\.copilot\skills\customer-repo\SKILL.md") { "✅ customer-repo" } else { "❌ customer-repo MISSING" }

If missing, install all skills from the repository:

1. Clone the repo (skip if already cloned):

   # macOS / Linux
   [ -d "$HOME/customer-skills/.git" ] || git clone https://github.com/roie9876/clawpilot-skills.git "$HOME/customer-skills"

   # Windows
   if (-not (Test-Path "$HOME\customer-skills\.git")) {
       git clone https://github.com/roie9876/clawpilot-skills.git "$HOME\customer-skills"
   }

2. Run the installer (idempotent — safe to re-run):

   # macOS / Linux
   bash "$HOME/customer-skills/scripts/install.sh"

   # Windows
   pwsh "$HOME\customer-skills\scripts\install.ps1"

3. Verify installed. If still missing, stop and report the error.

Required Tools

Draw.io MCP Server

This skill requires the Draw.io MCP server. Check if the drawio/create_diagram tool is available. If not: add the MCP server in Clawpilot settings → MCP Servers → URL: https://mcp.draw.io/mcp.

Step 1: Understand the Architecture

Ask the user to describe the architecture they want to diagram, or accept it directly from the prompt (e.g., "/architecture hub-spoke network for Contoso").

Gather:

• What services and components are involved?
• What is the primary flow (data pipeline, request path, network topology)?
• Which cloud provider? (Default: Azure. Support AWS and multi-cloud.)
• Any specific requirements? (VNet isolation, traffic labels, compliance zones)

If the user provides a text description or whiteboard sketch, extract the components and flows from it.

Step 2: Identify Cloud Provider and Icon Library

Determine which icon library to use:

Important style differences:

• Azure icons are SVG images — use image=img/lib/azure2/... style.
• AWS icons are stencils — use shape=mxgraph.aws4.<name> style. Do NOT use image=img/lib/aws4/....

Step 3: Look Up and Verify Icon Paths

For every service in the diagram, grep the appropriate static catalog to find the correct icon path. This is a hard gate — never guess icon paths.

Azure Icon Lookup

grep -i "gateway" ~/.copilot/skills/drawio-mcp-diagramming/references/azure2-complete-catalog.txt
grep -i "virtual_machine\|load_balancer\|key_vault" ~/.copilot/skills/drawio-mcp-diagramming/references/azure2-complete-catalog.txt

Azure icon style template:

image;aspect=fixed;html=1;points=[];align=center;image=img/lib/azure2/<category>/<Icon_Name>.svg;

If local rendering fails, use absolute URL fallback:

image;aspect=fixed;html=1;points=[];align=center;image=https://raw.githubusercontent.com/jgraph/drawio/dev/src/main/webapp/img/lib/azure2/<category>/<Icon_Name>.svg;

AWS Icon Lookup

grep -i "lambda" ~/.copilot/skills/drawio-mcp-diagramming/references/aws4-complete-catalog.txt
grep -i "load_balancing\|cloudfront\|route_53" ~/.copilot/skills/drawio-mcp-diagramming/references/aws4-complete-catalog.txt

AWS icon style template with service color conventions:

shape=mxgraph.aws4.<shape_name>;fillColor=<color>;fontColor=#ffffff;strokeColor=none;

AWS fill color conventions:

Validation Rule

If an icon path or shape name cannot be confirmed in the catalog:

1. Do NOT use it in the diagram.
2. Grep for alternatives (try partial names, synonyms).
3. If no match exists, use a generic rectangle with a text label instead.

Step 4: Build the mxGraphModel XML

Construct a valid mxGraphModel XML payload using the verified icons.

XML Wrapper Format

Every .drawio file uses this outer structure:

<mxfile host="app.diagrams.net" modified="2026-01-01T00:00:00.000Z" agent="architecture-skill" version="24.0.0" type="device">
  <diagram id="architecture" name="Architecture">
    <mxGraphModel dx="1422" dy="762" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1600" pageHeight="1200" math="0" shadow="0">
      <root>
        <mxCell id="0"/>
        <mxCell id="1" parent="0"/>
        <!-- Diagram content here -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

General Layout Rules

• Canvas sizing: Use pageWidth="1600" pageHeight="1200" for standard diagrams. Use pageWidth="1900" pageHeight="1500" for complex infrastructure/network topologies.
• Icon sizing: Use width="64" height="64" for service icons (or width="48" height="48" for compact layouts).
• Labels: Keep concise — service name + role (e.g., "App Gateway\n(WAF v2)"). Use whiteSpace=wrap;html=1; for multi-line.
• Edges: Use edgeStyle=orthogonalEdgeStyle for clean routing. Label with flow semantics (protocols, ports, data types).
• Cell IDs: Use descriptive IDs (e.g., id="app-gateway", id="subnet-app") for readability.

Step 5: Apply Network Topology Patterns (if applicable)

For infrastructure and network diagrams, apply these professional patterns.

Azure Network Topology

VNet styling:

• VNets: Thick borders (strokeWidth=4), large containers
  • DMZ VNet: Yellow (fillColor=#fff2cc, strokeColor=#d6b656)
  • Internal VNet: Green (fillColor=#d5e8d4, strokeColor=#82b366)
  • Management Zone: Blue (fillColor=#dae8fc, strokeColor=#6c8ebf)

Subnet styling:

• Dashed borders (strokeWidth=2, dashed=1, dashPattern=8 8)
• Position inside VNet containers
• Lighter shades of parent VNet color
• Label with subnet name and CIDR (e.g., "Application Subnet - 10.x.2.0/24")
• Delegated subnets: add delegation info (e.g., "PostgreSQL Subnet - 10.x.4.0/24 (Delegated)")

Resource positioning:

• All resources inside their respective subnet containers
• VMs, databases, load balancers visually contained within subnets
• This clearly shows network isolation boundaries

Traffic flow labeling:

• HTTPS:443 → red thick arrows for internet ingress
• HTTP:8080/8090 → gold arrows for backend pools
• PostgreSQL:5432 → blue dashed arrows for database connections
• NFS/Gluster → green arrows for shared storage
• RBAC/Identity → orange dashed arrows for management

Required boxes:

1. Traffic Legend (bottom-left): All traffic types with color-coded arrows and protocol/port info. Use thick bordered white box (strokeWidth=3).
2. Network Isolation Explanation (top-left): Visual conventions — VNets thick borders, subnets dashed borders, NSGs, private DNS. Use yellow background (fillColor=#fff9cc).
3. Zone Separation: VNet Peering Zone (grey #f5f5f5), External Services Zone (orange #ffe6cc).

Azure topology example:

<mxGraphModel pageWidth="1900" pageHeight="1500">
  <root>
    <mxCell id="0"/>
    <mxCell id="1" parent="0"/>
    <!-- VNet Container -->
    <mxCell id="vnet-internal" value="Internal VNet - 10.x.0.0/16"
      style="rounded=0;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;verticalAlign=top;fontSize=16;fontStyle=1;align=center;strokeWidth=4;"
      vertex="1" parent="1">
      <mxGeometry x="220" y="580" width="1340" height="820" as="geometry"/>
    </mxCell>
    <!-- Subnet inside VNet -->
    <mxCell id="subnet-app" value="Application Subnet - 10.x.2.0/24"
      style="rounded=1;whiteSpace=wrap;html=1;fillColor=#e6f4ea;strokeColor=#82b366;verticalAlign=top;fontSize=13;fontStyle=1;align=center;strokeWidth=2;dashed=1;dashPattern=8 8;"
      vertex="1" parent="vnet-internal">
      <mxGeometry x="40" y="70" width="480" height="340" as="geometry"/>
    </mxCell>
    <!-- Resource inside subnet -->
    <mxCell id="vm-app" value="App VM"
      style="image;aspect=fixed;html=1;points=[];align=center;image=img/lib/azure2/compute/Virtual_Machine.svg;"
      vertex="1" parent="subnet-app">
      <mxGeometry x="40" y="70" width="64" height="59" as="geometry"/>
    </mxCell>
    <!-- Labeled traffic edge -->
    <mxCell id="edge-db" value="PostgreSQL:5432"
      style="edgeStyle=orthogonalEdgeStyle;strokeWidth=2;strokeColor=#6c8ebf;dashed=1;"
      edge="1" source="vm-app" target="postgres" parent="1"/>
  </root>
</mxGraphModel>

AWS Network Topology

VPC styling:

• VPCs: Thick borders (strokeWidth=4)
  • Production: Green (fillColor=#d5e8d4, strokeColor=#82b366)
  • Development: Blue (fillColor=#dae8fc, strokeColor=#6c8ebf)
  • Shared Services: Yellow (fillColor=#fff2cc, strokeColor=#d6b656)

Subnet styling:

• Dashed borders (strokeWidth=2, dashed=1, dashPattern=8 8)
  • Public Subnets: Light green (fillColor=#e6f4ea, strokeColor=#82b366)
  • Private Subnets: Light blue (fillColor=#EFF7FF, strokeColor=#6c8ebf)
  • Isolated Subnets (databases): Light orange (fillColor=#fff3e0, strokeColor=#e6821e)
• Label with subnet name, AZ, and CIDR (e.g., "Public Subnet A - us-east-1a - 10.x.1.0/24")
• Use Availability Zone containers (light grey) inside VPCs

Traffic flow labeling:

• HTTPS:443 → red thick arrows for internet ingress via ALB/CloudFront
• Port 5432/3306 → blue dashed arrows for DB connections
• HTTPS:443 → green arrows for VPC Endpoints / AWS service calls
• SSH:22 / SSM → orange dashed for management / Bastion access

Required boxes:

1. Traffic Legend (bottom-left): Traffic types with color-coded arrows
2. Network Isolation Explanation (top-left): VPCs, subnets, Security Groups, NACLs, VPC Endpoints
3. Zone Separation: Internet/Edge Zone (orange), VPC Peering / Transit Gateway Zone (grey), AWS Managed Services Zone (purple)

AWS topology example:

<mxGraphModel pageWidth="1900" pageHeight="1500">
  <root>
    <mxCell id="0"/>
    <mxCell id="1" parent="0"/>
    <!-- VPC Container -->
    <mxCell id="vpc-prod" value="Production VPC - 10.x.0.0/16"
      style="rounded=0;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;verticalAlign=top;fontSize=16;fontStyle=1;align=center;strokeWidth=4;"
      vertex="1" parent="1">
      <mxGeometry x="220" y="200" width="1340" height="1100" as="geometry"/>
    </mxCell>
    <!-- Public Subnet -->
    <mxCell id="subnet-pub-a" value="Public Subnet A - us-east-1a - 10.x.1.0/24"
      style="rounded=1;whiteSpace=wrap;html=1;fillColor=#e6f4ea;strokeColor=#82b366;verticalAlign=top;fontSize=12;fontStyle=1;align=center;strokeWidth=2;dashed=1;dashPattern=8 8;"
      vertex="1" parent="vpc-prod">
      <mxGeometry x="40" y="80" width="550" height="200" as="geometry"/>
    </mxCell>
    <!-- ALB stencil -->
    <mxCell id="alb" value="ALB"
      style="shape=mxgraph.aws4.application_load_balancer;fillColor=#8C4FFF;fontColor=#ffffff;strokeColor=none;align=center;html=1;"
      vertex="1" parent="subnet-pub-a">
      <mxGeometry x="40" y="50" width="64" height="64" as="geometry"/>
    </mxCell>
  </root>
</mxGraphModel>

Step 6: Create the Diagram via MCP

Call the drawio MCP server to generate the diagram:

drawio/create_diagram

Pass the complete mxGraphModel XML as the input. The MCP server validates the XML and produces the diagram.

Before calling the tool, verify:

• All icon paths confirmed against the appropriate catalog
• XML is well-formed (no unclosed tags, proper escaping)
• Cell IDs are unique across the diagram
• Parent-child relationships are correct (resources inside subnets inside VNets/VPCs)

Step 7: Save to Customer Repo

1. Detect the customer from the conversation context or ask.

2. Compute the output path:

   ~/customer-engagements/{slug}/architecture/{descriptive-name}.drawio

   Where {descriptive-name} is a lowercase, hyphenated description of the diagram content.

   File naming examples:

   • network-topology.drawio
   • data-pipeline.drawio
   • hub-spoke-network.drawio
   • microservices-architecture.drawio
   • event-driven-pipeline.drawio

3. Create the directory if needed:

   # macOS / Linux / WSL / Git Bash
   mkdir -p "$HOME/customer-engagements/{slug}/architecture"

   # Windows PowerShell
   New-Item -ItemType Directory -Force -Path "$HOME/customer-engagements/{slug}/architecture" | Out-Null

4. Check if the file exists — If it does, read it and ask the user whether to overwrite, create a versioned copy (e.g., network-topology-v2.drawio), or skip.
5. Write the .drawio file using the full <mxfile> wrapper (see Step 4 XML wrapper format).

6. Commit to git:

   cd ~/customer-engagements/{slug}
   git add architecture/{descriptive-name}.drawio
   git commit -m "architecture: add {descriptive-name} diagram"

   If the repo is not a git repo or the commit fails, inform the user but do not fail — the diagram file is still written.

Visual Quality Guardrails

Apply these defaults unless the user explicitly asks for a dense or technical view:

• 3-4 major lanes/zones max (e.g., Source, Pipeline, Cloud target).
• Left-to-right primary flow with a single main path.
• Stage numbering (1, 2, 3, 4) instead of many edge labels.
• One icon per major service — avoid icon-per-step layouts.
• Limit cross-lane lines to one security/auth line and one optional telemetry line.
• Concise text — single purpose per box, no multiline overload.
• Clean variant first — add detail only if requested.

Error Handling

Troubleshooting

MCP Server Connectivity

• Confirm drawio MCP server appears in MCP server list.
• If tool list is stale, reset cached tools and retry.
• The drawio server URL is https://mcp.draw.io/mcp (HTTP transport).

Icon Rendering Issues

• Azure icons not showing: Verify style uses image=img/lib/azure2/... (not shape=mxgraph.azure2.*). Try absolute GitHub URL fallback.
• AWS icons not showing: Verify style uses shape=mxgraph.aws4.<name> (not image=img/lib/aws4/...). AWS4 icons are stencils, not SVG files.
• Icons work in app.diagrams.net but not in VS Code: This is a known limitation of the VS Code draw.io extension. Recommend opening in the web app for full rendering.

XML Validation

• Ensure all tags are properly closed.
• Escape special characters in labels (& → &, < → <).
• Verify cell IDs are unique.
• Check parent-child relationships match the container hierarchy.

Catalog Staleness

If icons that should exist are not in the catalog, the catalog may need refreshing (human-run, not per diagram):

cd ~/.copilot/skills/drawio-mcp-diagramming/scripts
python3 search_azure2_icons_github.py --max-results 9999 > ../references/azure2-complete-catalog.txt
python3 search_aws4_icons_github.py --max-results 9999 > ../references/aws4-complete-catalog.txt