architecture-diagrams

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: architecture-diagrams
description: Use when creating professional architecture diagrams, cloud infrastructure visuals, network topologies, Kubernetes cluster diagrams, or microservices architecture diagrams as PNG/SVG images using Python Diagrams library with real provider icons (AWS, Azure, GCP, K8s, OnPrem, Generic)
---

# Architecture Diagrams

**Portable Claude Agent Skill**

Professional architecture diagram generator using the [Diagrams](https://diagrams.mingrammer.com/) Python library. Produces publication-quality diagrams with real cloud provider icons (AWS, Azure, GCP, K8s, OnPrem, Generic).

**Portability:** This entire `architecture-diagrams/` folder is self-contained. Copy it to `~/.claude/skills/` or any project's `.claude/skills/` directory. Run `./scripts/setup.sh` once per location.

## Installation & Setup

### System Prerequisite

Graphviz must be installed system-wide (provides the `dot` binary):

```bash
# Ubuntu/Debian
sudo apt install graphviz

# macOS
brew install graphviz

# RHEL/Fedora
sudo dnf install graphviz
```

### One-Time Setup (Per Installation Location)

```bash
cd <path-to>/architecture-diagrams/
chmod +x scripts/setup.sh
./scripts/setup.sh
```

This creates `.venv/`, installs Python dependencies, and verifies graphviz.

### Automated Setup Check

```bash
cd <path-to>/architecture-diagrams/
if [ ! -d ".venv" ]; then
  ./scripts/setup.sh
fi
echo "Skill ready"
```

## Quick Start

```bash
# 1. Navigate to your project directory
cd ~/projects/my-project/

# 2. Set skill path for convenience
SKILL_DIR=~/.claude-wa/.claude/skills/architecture-diagrams

# 3. Verify setup
if [ ! -d "$SKILL_DIR/.venv" ]; then cd "$SKILL_DIR" && ./scripts/setup.sh && cd -; fi

# 4. Activate venv
source "$SKILL_DIR/.venv/bin/activate"

# 5. Create a diagram script in your project
cat > my-diagram.py << 'EOF'
from diagrams import Diagram, Cluster
from diagrams.aws.compute import EC2
from diagrams.aws.network import ELB

with Diagram("My Architecture", show=False):
    lb = ELB("Load Balancer")
    with Cluster("Web Tier"):
        web = [EC2("Web 1"), EC2("Web 2")]
    lb >> web
EOF

# 6. Generate PNG (output goes to ./output/png/ in current directory)
python "$SKILL_DIR/scripts/generate.py" my-diagram.py

# Output: ~/projects/my-project/output/png/my-diagram.png
```

## File Structure

```
architecture-diagrams/        <-- Skill root (portable)
  SKILL.md                    # This file
  requirements.txt            # Python deps (diagrams, graphviz)
  .venv/                      # Python virtual environment (created by setup.sh)
  scripts/
    setup.sh                  # Creates .venv and installs deps
    generate.py               # Runs diagram script, outputs to cwd/output/png/
  src/
    templates/                # Starter templates — copy these
      basic-template.py       # Minimal template with TODOs
    examples/                 # Working example diagrams
      cisco-network.py        # Network topology with routers, switches, firewall
      aws-architecture.py     # AWS cloud architecture with VPC, ALB, RDS
      kubernetes-cluster.py   # K8s cluster with namespaces, services, monitoring
  docs/
    icon-reference.md         # Index with top icons + navigation (load this first)
    icons/                    # Provider-specific icon catalogs (load on demand, all ≤450 lines)
      generic.md              # Generic infrastructure (26 icons)
      aws.md                  # Amazon Web Services (562 icons)
      azure-compute-network.md # Azure: Compute, Network, Database, Storage (~400 icons)
      azure-app-devops.md     # Azure: App Services, DevOps, Identity, Integration, IoT (~240 icons)
      azure-web-security.md   # Azure: Management, Security, Web Services (~170 icons)
      gcp.md                  # Google Cloud Platform (144 icons)
      kubernetes.md           # Kubernetes (69 icons)
      onprem.md               # On-Premise tools (211 icons)
      saas.md                 # SaaS providers (42