/azure-diagrams

name: azure-diagrams
description: Comprehensive technical diagramming toolkit for solutions architects, presales, and developers. Creates Azure architecture diagrams (800+ Azure service icons), business process flows (swimlanes, workflows), ERD diagrams (database schemas), project timelines, UI wireframes, and network topology diagrams. Perfect for proposals, documentation, and architecture reviews. Also generates diagrams from Bicep, Terraform, and ARM templates.
compatibility: Requires the Graphviz system package and the Python diagrams library (>=0.25.1). Works with Claude Code, GitHub Copilot, Cursor, Windsurf, VS Code, and any Agent Skills or AGENTS.md compatible tool.
license: MIT
metadata:
  author: community
  version: "2.0.0"
  repository: https://github.com/cmb211087/azure-diagrams-skill

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.

⚡ Execution Method

Run the Python directly to generate the image, and keep the image but do not leave a throwaway `.py` script behind. The generated file is the deliverable.

**Output location (portable).** Write to a `diagrams/` folder in the current working directory - this works in every tool and on every OS. If you are running in a sandbox that provides `/mnt/user-data/outputs` (e.g. Claude Code on the web), prefer that. Create the folder first.

**POSIX shells** (Claude Code, Cursor, Linux/macOS - `bash`/`zsh`):

mkdir -p diagrams
python3 << 'EOF'
from diagrams import Diagram
from diagrams.azure.compute import AKS
from diagrams.azure.database import CosmosDb

with Diagram("My Architecture", filename="diagrams/architecture", show=False, outformat="png"):
    AKS("aks-prod") >> CosmosDb("cosmos-prod")
EOF

**Windows PowerShell** (e.g. GitHub Copilot on Windows - no heredoc): write a short script, run it, then delete it so nothing is left behind:

New-Item -ItemType Directory -Force diagrams > $null
@'
from diagrams import Diagram
from diagrams.azure.compute import AKS
from diagrams.azure.database import CosmosDb
with Diagram("My Architecture", filename="diagrams/architecture", show=False, outformat="png"):
    AKS("aks-prod") >> CosmosDb("cosmos-prod")
'@ | Set-Content _diagram.py; python _diagram.py; Remove-Item _diagram.py

**Canned patterns** (cross-platform) - use the bundled generator instead of writing code:

python scripts/generate_diagram.py --list                       # list available patterns
python scripts/generate_diagram.py --pattern <name> --output diagrams/arch

📊 Diagram Types

| Type | Reference File | Example Prompt | |------|----------------|----------------| | **Azure Architecture** | `references/azure-components.md` | "Design a microservices architecture with AKS and Cosmos DB" | | **Business Process Flow** | `references/business-process-flows.md` | "Create a swimlane for invoice approval workflow" | | **Entity Relationship (ERD)** | `references/entity-relationship-diagrams.md` | "Generate an ERD for customer and order entities" | | **Timeline / Gantt** | `references/timeline-gantt-diagrams.md` | "Create a 6-month migration roadmap" | | **UI Wireframe** | `references/ui-wireframe-diagrams.md` | "Design a KPI dashboard layout" | | **Common Patterns** | `references/common-patterns.md` | "Show a hub-spoke network topology" |

🔥 Bonus: Generate from Code

Can also create diagrams directly from infrastructure code:

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

Analyze our Terraform modules and create a diagram grouped by subnet

Read azure-pipelines.yml and create a CI/CD pipeline diagram

Supports: **Bicep**, **Terraform**, **ARM Templates**, **Azure Pipelines YAML**, **GitHub Actions**

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

---

Prerequisites

# 1) Graphviz - the rendering engine (system package, not pip). Restart the terminal after.
winget install -e --id Graphviz.Graphviz   # Windows  (or: choco install graphviz)
brew install graphviz                       # macOS
sudo apt-get install -y graphviz            # Linux (Debian/Ubuntu)

# 2) Python library (a virtual environment is recommended):
pip install "diagrams>=0.25.1"
# optional extras: matplotlib (timeline/Gantt/wireframe), cairosvg (portable SVG)

Quick Start

from diagrams import Diagram, Cluster, Edge
from diagrams.azure.compute import FunctionApps, AKS, 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 = AKS("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("Logic Apps")
    
    users >> gateway >> web >> api
    api >> [functions, aks]
    functions >> [cosmos, bus]
    aks >> [sql, redis]
    bus >> logic >> blob

Supported Diagram Types

| Type | Reference File | Use Case | |------|----------------|----------| | **Azur