azure-diagrams

name	azure-diagrams
description	Azure architecture diagram generation skill for high-quality, non-Mermaid outputs. Produces deterministic Python `diagrams` + Graphviz artifacts (`.py` + `.png`/`.svg`) for design and as-built documentation. Use for Step 3 and Step 7 architecture visuals, dependency visuals, and topology diagrams with enforced layout and naming conventions.
compatibility	Requires graphviz system package and Python diagrams library; works with Claude Code, GitHub Copilot, VS Code, and any Agent Skills compatible tool.
license	MIT
metadata	{"author":"cmb211087","version":"4.0","repository":"https://github.com/mingrammer/diagrams"}

Azure Architecture Diagrams Skill

A comprehensive technical diagramming toolkit for solutions architects, presales engineers, and developers. Generate professional diagrams for proposals, documentation, and architecture reviews using Python's diagrams library.

🎯 Output Format

Default behavior: Generate PNG images via Python code

Format	File Extension	Tool	Use Case
Python PNG	.py + .png	diagrams library	Programmatic, version-controlled, CI
SVG	.svg	diagrams library	Web documentation (optional)

Output Naming Convention

agent-output/{project}/
├── 03-des-diagram.py          # Python source (version controlled)
├── 03-des-diagram.png         # PNG from Python diagrams
└── 07-ab-diagram.py/.png      # As-built diagrams

⚡ Execution Method

Always save diagram source to file first, then execute it:

# Example (Design phase)
python3 agent-output/{project}/03-des-diagram.py

# Example (As-built phase)
python3 agent-output/{project}/07-ab-diagram.py

Required workflow:

• ✅ Generate and save .py source in agent-output/{project}/
• ✅ Execute saved script to produce .png (and optional .svg)
• ✅ Keep source version-controlled for deterministic regeneration
• ✅ Never use inline heredoc execution for diagram generation

📊 Architecture Diagram Contract (Mandatory)

For Azure workflow artifacts, generate non-Mermaid diagrams using Python diagrams only.

Required outputs

• 03-des-diagram.py + 03-des-diagram.png (Step 3)
• 04-dependency-diagram.py + 04-dependency-diagram.png (Step 4)
• 04-runtime-diagram.py + 04-runtime-diagram.png (Step 4)
• 07-ab-diagram.py + 07-ab-diagram.png (Step 7, when requested)

Required naming conventions

• Cluster vars: clu_<scope>_<slug> where scope ∈ sub|rg|net|tier|zone|ext
• Node vars: n_<domain>_<service>_<role> where domain ∈ edge|web|app|data|id|sec|ops|int
• Edge vars (if reused): e_<source>_to_<target>_<flow>
• Flow taxonomy only: auth|request|response|read|write|event|replicate|secret|telemetry|admin

Required layout/style defaults

• direction="LR" unless explicitly justified
• deterministic spacing via graph_attr (nodesep, ranksep, splines)
• short labels (2–4 words)
• max 3 edge styles (runtime/control/observability)

Quality gate (score /10)

1. Readable at 100% zoom
2. No major label overlap
3. Minimal line crossing
4. Clear tier grouping
5. Correct Azure icons
6. Security boundary visible
7. Data flow direction clear
8. Identity/auth flow visible
9. Telemetry path visible
10. Naming conventions followed

If score < 9/10, regenerate once with simplification.

🔥 Generate from Infrastructure Code

Create diagrams directly from Bicep, Terraform, or ARM templates:

Read the Bicep files in /infra and generate an architecture diagram

Analyze our Terraform modules and create a diagram grouped by subnet

See references/iac-to-diagram.md for detailed prompts and examples.

---

Prerequisites

# Core requirements
pip install diagrams matplotlib pillow

# Graphviz (required for PNG generation)
apt-get install -y graphviz  # Ubuntu/Debian
# or: brew install graphviz  # macOS
# or: choco install graphviz  # Windows

Quick Start

from diagrams import Diagram, Cluster, Edge
from diagrams.azure.compute import FunctionApps, KubernetesServices, AppServices
from diagrams.azure.network import ApplicationGateway, LoadBalancers
from diagrams.azure.database import CosmosDb, SQLDatabases, CacheForRedis
from diagrams.azure.storage import BlobStorage
from diagrams.azure.integration import LogicApps, ServiceBus, APIManagement
from diagrams.azure.security import KeyVaults
from diagrams.azure.identity import ActiveDirectory
from diagrams.azure.ml import CognitiveServices

with Diagram("Azure Solution Architecture", show=False, direction="TB"):
    users = ActiveDirectory("Users")

    with Cluster("Frontend"):
        gateway = ApplicationGateway("App Gateway")
        web = AppServices("Web App")

    with Cluster("Backend"):
        api = APIManagement("API Management")
        functions = FunctionApps("Functions")
        aks = KubernetesServices("AKS")

    with Cluster("Data"):
        cosmos = CosmosDb("Cosmos DB")
        sql = SQLDatabases("SQL Database")
        redis = CacheForRedis("Redis Cache")
        blob = BlobStorage("Blob Storage")

    with Cluster("Integration"):
        bus = ServiceBus("Service Bus")
        logic = LogicApps()

    users >> gateway >> web >> api
    api >> [functions, aks]
    functions >> [cosmos, bus]
    aks >> [sql, redis]
    bus >> logic >> blob

Azure Service Categories

Category	Import	Key Services
Compute	diagrams.azure.compute	VM, AKS, Functions, App Service, Container Apps, Batch
Networking	diagrams.azure.network	VNet, Load Balancer, App Gateway, Front Door, Firewall, ExpressRoute
Database	diagrams.azure.database	SQL, Cosmos DB, PostgreSQL, MySQL, Redis, Synapse
Storage	diagrams.azure.storage	Blob, Files, Data Lake, NetApp, Queue, Table
Integration	diagrams.azure.integration	Logic Apps, Service Bus, Event Grid, APIM, Data Factory
Security	diagrams.azure.security	Key Vault, Sentinel, Defender, Security Center
Identity	diagrams.azure.identity	Entra ID, B2C, Managed Identity, Conditional Access
AI/ML	diagrams.azure.ml	Azure OpenAI, Cognitive Services, ML Workspace, Bot Service
Analytics	diagrams.azure.analytics	Synapse, Databricks, Data Explorer, Stream Analytics, Event Hubs
IoT	diagrams.azure.iot	IoT Hub, IoT Edge, Digital Twins, Time Series Insights
DevOps	diagrams.azure.devops	Azure DevOps, Pipelines, Repos, Boards, Artifacts
Web	diagrams.azure.web	App Service, Static Web Apps, CDN, Media Services
Monitor	diagrams.azure.monitor	Monitor, App Insights, Log Analytics

See references/azure-components.md for the complete list of 700+ components.

Common Architecture Patterns

Web Application (3-Tier)

from diagrams.azure.network import ApplicationGateway
from diagrams.azure.compute import AppServices
from diagrams.azure.database import SQLDatabases

gateway >> AppServices("Web") >> SQLDatabases("DB")

Microservices with AKS

from diagrams.azure.compute import KubernetesServices, ContainerRegistries
from diagrams.azure.network import ApplicationGateway
from diagrams.azure.database import CosmosDb

gateway >> KubernetesServices("Cluster") >> CosmosDb("Data")
ContainerRegistries("Registry") >> KubernetesServices("Cluster")

Serverless / Event-Driven

from diagrams.azure.compute import FunctionApps
from diagrams.azure.integration import EventGridTopics, ServiceBus
from diagrams.azure.storage import BlobStorage

EventGridTopics("Events") >> FunctionApps("Process") >> ServiceBus("Queue")
BlobStorage("Trigger") >> FunctionApps("Process")

Data Platform

from diagrams.azure.analytics import DataFactories, Databricks, SynapseAnalytics
from diagrams.azure.storage import DataLakeStorage

DataFactories("Ingest") >> DataLakeStorage("Lake") >> Databricks("Transform") >> SynapseAnalytics("Serve")

Hub-Spoke Networking

from diagrams.azure.network import VirtualNetworks, Firewall, VirtualNetworkGateways

with Cluster("Hub"):
    firewall = Firewall("Firewall")
    vpn = VirtualNetworkGateways("VPN")

with Cluster("Spoke 1"):
    spoke1 = VirtualNetworks("Workload 1")

spoke1 >> firewall

Connection Syntax

# Basic connections
a >> b                              # Simple arrow
a >> b >> c                         # Chain
a >> [b, c, d]                      # Fan-out (one to many)
[a, b] >> c                         # Fan-in (many to one)

# Labeled connections
a >> Edge(label="HTTPS") >> b       # With label
a >> Edge(label="443") >> b         # Port number

# Styled connections
a >> Edge(style="dashed") >> b      # Dashed line (config/secrets)
a >> Edge(style="dotted") >> b      # Dotted line
a >> Edge(color="red") >> b         # Colored
a >> Edge(color="red", style="bold") >> b  # Combined

# Bidirectional
a >> Edge(label="sync") << b        # Two-way
a - Edge(label="peer") - b          # Undirected

Diagram Attributes

with Diagram(
    "Title",
    show=False,                    # Don't auto-open
    filename="output",             # Output filename (no extension)
    direction="TB",                # TB, BT, LR, RL
    outformat="png",               # png, jpg, svg, pdf
    graph_attr={
        "splines": "spline",       # Curved edges
        "nodesep": "1.0",          # Horizontal spacing
        "ranksep": "1.0",          # Vertical spacing
        "pad": "0.5",              # Graph padding
        "bgcolor": "white",        # Background color
        "dpi": "150",              # Resolution
    }
):

Clusters (Azure Hierarchy)

Use Cluster() for proper Azure hierarchy: Subscription → Resource Group → VNet → Subnet

with Cluster("Azure Subscription"):
    with Cluster("rg-app-prod"):
        with Cluster("vnet-spoke (10.1.0.0/16)"):
            with Cluster("snet-app"):
                vm1 = VM("VM 1")
                vm2 = VM("VM 2")
            with Cluster("snet-data"):
                db = SQLDatabases("Database")

Cluster styling:

with Cluster("Styled", graph_attr={"bgcolor": "#E8F4FD", "style": "rounded"}):

⚠️ Professional Output Standards

The Key Setting: labelloc='t'

To keep labels inside cluster boundaries, put labels ABOVE icons:

node_attr = {
    "fontname": "Arial Bold",
    "fontsize": "11",
    "labelloc": "t",  # KEY: Labels at TOP - stays inside clusters!
}

with Diagram("Title", node_attr=node_attr, ...):
    # Your diagram code

Full Professional Template

from diagrams import Diagram, Cluster, Edge
from diagrams.azure.compute import KubernetesServices
from diagrams.azure.database import SQLDatabases

graph_attr = {
    "bgcolor": "white",
    "pad": "0.8",
    "nodesep": "0.9",
    "ranksep": "0.9",
    "splines": "spline",
    "fontname": "Arial Bold",
    "fontsize": "16",
    "dpi": "150",
}

node_attr = {
    "fontname": "Arial Bold",
    "fontsize": "11",
    "labelloc": "t",           # Labels ABOVE icons - KEY!
}

cluster_style = {"margin": "30", "fontname": "Arial Bold", "fontsize": "14"}

with Diagram("My Architecture",
             direction="TB",
             graph_attr=graph_attr,
             node_attr=node_attr):

    with Cluster("Data Tier", graph_attr=cluster_style):
        sql = SQLDatabases("sql-myapp-prod\nS3 tier")

Professional Standards Checklist

Check	Requirement
✅ labelloc='t'	Labels above icons (stays in clusters)
✅ Bold fonts	fontname="Arial Bold" for readability
✅ Full resource names	Actual names from IaC, not abbreviations
✅ High DPI	dpi="150" or higher for crisp text
✅ Azure icons	Use diagrams.azure.* components
✅ Cluster margins	margin="30" or higher
✅ CIDR blocks	Include IP ranges in VNet/Subnet labels

Troubleshooting

Overlapping Nodes

Increase spacing for complex diagrams:

graph_attr={
    "nodesep": "1.2",   # Horizontal (default 0.25)
    "ranksep": "1.2",   # Vertical (default 0.5)
    "pad": "0.5"
}

Labels Outside Clusters

Use labelloc="t" in node_attr to place labels above icons.

Missing Icons

Check available icons:

from diagrams.azure import network
print(dir(network))

See references/preventing-overlaps.md for detailed guidance.

Scripts

Script	Purpose
scripts/generate_diagram.py	Interactive pattern generator
scripts/multi_diagram_generator.py	Multi-type diagram generator
scripts/ascii_to_diagram.py	Convert ASCII diagrams from markdown
scripts/verify_installation.py	Check prerequisites

Reference Files

File	Content
references/iac-to-diagram.md	Generate diagrams from Bicep/Terraform/ARM
references/azure-components.md	Complete list of 700+ Azure components
references/common-patterns.md	Ready-to-use architecture patterns
references/business-process-flows.md	Workflow and swimlane diagrams
references/entity-relationship-diagrams.md	Database ERD patterns
references/timeline-gantt-diagrams.md	Project timeline diagrams
references/ui-wireframe-diagrams.md	UI mockup patterns
references/preventing-overlaps.md	Layout troubleshooting guide
references/sequence-auth-flows.md	Authentication flow patterns
references/quick-reference.md	Copy-paste code snippets

Workflow Integration

This skill produces artifacts in Step 3 (design) or Step 7 (as-built).

Workflow Step	File Pattern	Description
Step 3 (Design)	03-des-diagram.py, 03-des-diagram.png	Proposed architecture visualization
Step 7 (As-Built)	07-ab-diagram.py, 07-ab-diagram.png	Deployed architecture documentation

Artifact Suffix Convention

Apply the appropriate suffix based on when the diagram is generated:

• -des: Design diagrams (Step 3 artifacts)

  • Example: 03-des-diagram.py, 03-des-diagram.png
  • Represents: Proposed architecture, conceptual design
  • Called after: Architecture assessment (Step 2)

• -ab: As-built diagrams (Step 7 artifacts)

  • Example: 07-ab-diagram.py, 07-ab-diagram.png
  • Represents: Actual deployed infrastructure
  • Called after: Deployment (Step 6)

Suffix Rules:

1. Design/proposal/planning language → use -des
2. Deployed/implemented/current state language → use -ab

Generation Workflow

Follow these steps when creating diagrams:

1. Gather Context - Read Bicep templates, deployment summary, or architecture assessment
2. Identify Resources - List all Azure resources to visualize
3. Determine Hierarchy - Map Subscription → RG → VNet → Subnet structure
4. Generate Python Code - Create diagram with proper clusters and edges
5. Execute Script - Run Python to generate PNG
6. Verify Output - Confirm PNG file was created successfully

Guardrails

DO

• ✅ Create diagram files in agent-output/{project}/
• ✅ Use step-prefixed filenames (03-des-* or 07-ab-*)
• ✅ Use valid diagrams.azure.* imports only
• ✅ Include docstring with prerequisites and generation command
• ✅ Match diagram to actual architecture design/deployment
• ✅ Use Cluster() for Azure hierarchy (Subscription → RG → VNet → Subnet)
• ✅ Include CIDR blocks in VNet/Subnet labels
• ✅ ALWAYS execute the Python script to generate the PNG file
• ✅ Verify PNG file exists after generation

DO NOT

• ❌ Use invalid or made-up diagram node types
• ❌ Create diagrams that don't match the actual architecture
• ❌ Skip the PNG generation step
• ❌ Overwrite existing diagrams without user consent
• ❌ Output to legacy docs/diagrams/ folder (use agent-output/ instead)
• ❌ Leave diagram in Python-only state without generating PNG
• ❌ Use placeholder or generic names instead of actual resource names

What This Skill Does NOT Do

• ❌ Generate Bicep or Terraform code (use bicep-code agent)
• ❌ Create workload documentation (use azure-artifacts skill)
• ❌ Deploy resources (use deploy agent)
• ❌ Create ADRs (use azure-adr skill)
• ❌ Perform WAF assessments (use architect agent)