# AWS Architecture Diagram Generator

> Generate professional AWS architecture diagrams with official icons using Python's diagrams library, then auto-validate against AWS best practices (bounding box, no crossing lines, color-coded edges, labeled APIs).

- Skill: `tsaol/aws-architecture-diagram-generator` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tsaol/aws-architecture-diagram-generator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tsaol/aws-architecture-diagram-generator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: Apache-2.0
- Author: tsaol (https://skillmd.com/u/tsaol)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tsaol/aws-architecture-diagram-generator

---


# AWS Architecture Diagram Generator

You are an AI assistant that generates professional AWS architecture diagrams and validates them against quality standards.

## What This Skill Does

1. **Generate** — Create AWS architecture diagrams using Python's `diagrams` library with official AWS icons
2. **Validate** — Auto-check diagrams against 5 quality rules after every generation
3. **Iterate** — Fix issues and regenerate until all checks pass

## Quality Checklist (enforced automatically)

Every generated diagram MUST pass these 5 checks:

| # | Rule | Why |
|---|------|-----|
| 1 | **Outer bounding box** — An "AWS Cloud" cluster wraps all AWS services. User/external nodes stay outside. | AWS standard: shows cloud boundary clearly |
| 2 | **No crossing lines** — Use `splines="ortho"` + top-down flow + no back-edges | Clean, readable layout |
| 3 | **Clear hierarchy** — Nodes defined in layer order: user → app → services → storage | Top-down flow matches mental model |
| 4 | **Color-coded edges** — Different colors for different edge types (user input, API calls, data flow, etc.) | Visual distinction between connection types |
| 5 | **All API calls labeled** — Every edge to an AWS service has the API name as a label | Shows exactly what's called |

## How to Generate

### Step 1: Understand the architecture

Ask the user what AWS services are involved and how they connect. Identify:
- External actors (users, developers, CI/CD)
- Application layer (Lambda, ECS, EC2, agent skills, etc.)
- AWS services (S3, DynamoDB, SageMaker, etc.)
- Data flow direction

### Step 2: Write the Python script

Use the `diagrams` library with these best practices:

```python
from diagrams import Diagram, Cluster, Edge

graph_attr = {
    "fontsize": "18",
    "fontname": "Helvetica",
    "bgcolor": "white",
    "pad": "0.5",
    "nodesep": "0.8",
    "ranksep": "1.0",
    "splines": "ortho",        # Straight-angle lines (professional)
}

with Diagram(
    "My Architecture",
    filename="architecture",
    show=False,
    direction="TB",              # Top-to-bottom (clearest for AWS)
    graph_attr=graph_attr,
    outformat=["png", "svg"],    # Both formats
):
    # External actors OUTSIDE the AWS Cloud cluster
    user = Users("Developer")

    # AWS Cloud bounding box
    with Cluster("AWS Cloud", graph_attr={
        "bgcolor": "#F5F5F5",
        "style": "rounded",
        "pencolor": "#232F3E",
        "penwidth": "2",
    }):
        # Nest services inside
        with Cluster("Application Layer"):
            app = Lambda("My Function")
        
        with Cluster("Storage"):
            db = DynamoDB("Table")
            s3 = S3("Bucket")

    # Edges: top-down only, no back-edges
    user >> Edge(label="API call", color="#1565C0") >> app
    app >> Edge(label="PutItem()", color="#E65100") >> db
    app >> Edge(label="PutObject()", color="#E65100") >> s3
```

**Key rules:**
- `direction="TB"` — top-to-bottom flow
- `splines="ortho"` — straight-angle lines, not curves
- External nodes (users) OUTSIDE the "AWS Cloud" cluster
- All AWS services INSIDE the "AWS Cloud" cluster
- NO back-edges (edges pointing upward) — they cause line crossings
- Output both PNG and SVG

### Step 3: Run and validate

After generating, run the built-in quality checks:

```bash
python3 scripts/validate_diagram.py <script_path>
```

Or embed checks directly in the generation script (see `scripts/validate_diagram.py`).

### Step 4: Iterate

If any check fails, fix the script and regenerate. Common fixes:
- **Missing bounding box** → Add `Cluster("AWS Cloud", ...)`
- **Crossing lines** → Remove back-edges, ensure `splines="ortho"`
- **Wrong hierarchy** → Reorder node definitions top-to-bottom
- **Missing colors** → Add `color=` to all `Edge()` calls
- **Missing labels** → Add `label=` with API name to all service edges

## Edge Color Convention

| Color | Hex | Use for |
|-------|-----|---------|
| Blue | `#1565C0` | User/external input |
| Orange | `#E65100` | API calls to AWS services |
| Green | `#2E7D32` | Success/output/registration |
| Green dashed | `#2E7D32` + `style="dashed"` | Optional/async actions |
| Grey | `#999999` | Internal data flow (storage) |

## AWS Icon Reference

Common imports from the `diagrams` library:

```python
# Compute
from diagrams.aws.compute import Lambda, ECS, EC2, Fargate

# Storage
from diagrams.aws.storage import S3

# Database
from diagrams.aws.database import DynamoDB, RDS, Aurora, Redshift

# ML
from diagrams.aws.ml import Sagemaker, SagemakerModel, SagemakerNotebook

# Analytics
from diagrams.aws.analytics import Glue, Athena, EMR, KinesisDataStreams

# Networking
from diagrams.aws.network import ELB, APIGateway, CloudFront, Route53

# Security
from diagrams.aws.security import IAM, KMS, WAF

# General
from diagrams.aws.general import General, User
from diagrams.onprem.client import Users
from diagrams.programming.language import Python
```

## Prerequisites

```bash
pip install diagrams
sudo apt install graphviz  # or: brew install graphviz
```

## Output

- `architecture.png` — for README, submissions, presentations
- `architecture.svg` — for slides (scales without blur)
- `architecture.drawio` — optional, for manual editing in draw.io