az-diagram

name	az-diagram
description	Generate Azure architecture diagrams from Bicep/ARM templates. Use when user asks to create architecture diagrams, visualize infrastructure, or convert IaC to diagrams.
argument-hint	["bicep-file-path"]

Azure Architecture Diagram Generator

Generate professional Azure architecture diagrams from Bicep/ARM templates using the diagrams Python library.

Workflow

1. Analyze the Bicep/ARM template to identify resources and relationships
2. Generate a Python script using the diagrams library
3. Run the script: uv run python <script>.py Fix the bug if any
4. Verify that PNG, DOT, and Draw.io files are generated in diagrams/, view the png, check if it is horizontal layout, and if you like it or not
5. Iterate if needed until all outputs are successfully created

CRITICAL: Layout Requirements

Use Horizontal Layout (Left-to-Right)

with Diagram(
    "Architecture Name",
    filename="diagrams/output_name",
    outformat=["png", "dot", "svg"],
    direction="LR",  # ALWAYS use horizontal layout
    graph_attr=graph_attr,
    show=False
):

Generous Spacing Between Clusters

graph_attr = {
    "splines": "spline",     # Smooth curved lines (or "ortho" for orthogonal)
    "nodesep": "1.5",        # Horizontal spacing between nodes - USE 1.5+
    "ranksep": "2.0",        # Vertical spacing between ranks - USE 2.0+
    "fontsize": "12",
    "bgcolor": "white",
    "pad": "1.0"             # Padding around diagram
}

# Cluster margins should be generous
cluster_attr = {"bgcolor": "#E8F5E9", "style": "rounded", "margin": "25"}  # USE margin 25+

Cluster Color Coding

identity_cluster_attr = {"bgcolor": "#E8EAF6", "style": "rounded", "margin": "25"}   # Indigo - Identity
network_cluster_attr = {"bgcolor": "#E3F2FD", "style": "rounded", "margin": "25"}    # Blue - Networking
compute_cluster_attr = {"bgcolor": "#E8F5E9", "style": "rounded", "margin": "25"}    # Green - Compute
data_cluster_attr = {"bgcolor": "#FFF3E0", "style": "rounded", "margin": "25"}       # Orange - Data
storage_cluster_attr = {"bgcolor": "#FCE4EC", "style": "rounded", "margin": "25"}    # Pink - Storage
security_cluster_attr = {"bgcolor": "#F3E5F5", "style": "rounded", "margin": "25"}   # Purple - Security
monitoring_cluster_attr = {"bgcolor": "#E0F7FA", "style": "rounded", "margin": "25"} # Cyan - Monitoring

Azure Icon Imports

from diagrams import Diagram, Cluster, Edge
import subprocess

# Compute
from diagrams.azure.compute import AppServices, VM, AvailabilitySets, FunctionApps, ContainerInstances, ContainerRegistries

# Network
from diagrams.azure.network import (
    VirtualNetworks, Subnets, LoadBalancers,
    ApplicationGateway, FrontDoors,
    NetworkSecurityGroupsClassic,
    PublicIpAddresses, NetworkInterfaces,
    PrivateEndpoint, DNSPrivateZones
)

# Database
from diagrams.azure.database import SQLServers, SQLDatabases, DatabaseForPostgresqlServers, CacheForRedis

# Storage
from diagrams.azure.storage import StorageAccounts, BlobStorage

# Security
from diagrams.azure.security import KeyVaults

# Identity
from diagrams.azure.identity import ManagedIdentities, AppRegistrations

# Monitoring
from diagrams.azure.analytics import LogAnalyticsWorkspaces
from diagrams.azure.devops import ApplicationInsights

# External
from diagrams.onprem.client import Users

Check available icons:

from diagrams.azure import network
print([x for x in dir(network) if not x.startswith('_')])

DOT to Draw.io Conversion

ALWAYS include at end of script:

# Convert to Draw.io format
print("Converting to Draw.io format...")
subprocess.run([
    "graphviz2drawio",
    "diagrams/<name>.dot",
    "-o",
    "diagrams/<name>.drawio"
], check=True)

print("Done! Generated:")
print("  - diagrams/<name>.png  (accurate layout)")
print("  - diagrams/<name>.svg  (vector version)")
print("  - diagrams/<name>.dot  (GraphViz source)")
print("  - diagrams/<name>.drawio (editable)")

Edge Styling

# Connection examples with labels and colors
user >> Edge(label="HTTPS", color="darkgreen", style="bold") >> app_service
app_service >> Edge(label="uses identity", color="blue", style="bold") >> managed_id
managed_id >> Edge(label="Get Secrets", color="purple") >> key_vault
key_vault >> Edge(label="conn strings", color="gray", style="dotted") >> postgres
subnet >> Edge(label="Service Endpoint", color="crimson", style="bold") >> storage

Resource Type Mapping

Bicep Resource Type	Diagram Icon
Microsoft.Web/sites (kind: app,linux)	AppServices
Microsoft.Web/serverfarms	(App Service Plan - usually not shown)
Microsoft.ContainerRegistry/registries	ContainerRegistries
Microsoft.Network/virtualNetworks	VirtualNetworks
Microsoft.Network/publicIPAddresses	PublicIpAddresses
Microsoft.Network/natGateways	PublicIpAddresses (labeled as NAT Gateway)
Microsoft.DBforPostgreSQL/flexibleServers	DatabaseForPostgresqlServers
Microsoft.Cache/redis	CacheForRedis
Microsoft.Storage/storageAccounts	StorageAccounts
Microsoft.KeyVault/vaults	KeyVaults
Microsoft.ManagedIdentity/userAssignedIdentities	ManagedIdentities
Microsoft.Graph/applications	AppRegistrations
Microsoft.Insights/components	ApplicationInsights
Microsoft.OperationalInsights/workspaces	LogAnalyticsWorkspaces

Common Issues

Error	Solution
cannot import name 'PublicIPAddresses'	Use PublicIpAddresses (case-sensitive)
ExecutableNotFound: 'dot'	GraphViz not installed
Cluttered layout	Increase nodesep/ranksep to 1.5+/2.0+, use margin: "25" in clusters
Overlapping clusters	Use direction="LR" and increase margins
cannot import name 'PublicIPAddresses'	Use PublicIpAddresses (case-sensitive)
ExecutableNotFound: 'dot'	GraphViz not installed - see README
Cluttered layout	Adjust nodesep/ranksep, use direction="TB" or "LR"
draw.io missing Azure icons	graphviz2drawio limitation - manually add Azure icons in draw.io
draw.io layout differs from PNG	Use splines: ortho, add ratio/size constraints (Mode B)
Diagram too cramped	Increase nodesep, ranksep, and cluster margin values

Execution

After generating the script, run:

uv run python <script_name>.py

IMPORTANT!!! Keep executing till you get a success picture.

Verify these files exist in diagrams/:

• <name>.png - Main output image
• <name>.dot - GraphViz source
• <name>.drawio - Editable in draw.io
• <name>.svg - Vector format (optional)

Example

See examples/ directory for:

• resource.bicep - Input Bicep template
• example_diagram.py - Generated Python script
• example.png - Output diagram
• example.dot - GraphViz source
• example.drawio - Editable draw.io file