aws-architecture-diagram-generator

name	AWS Architecture Diagram Generator
description	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).
allowed-tools	["Bash","Read","Write","Edit","Glob","Grep"]
compatibility	["claude-code","kiro","cursor","vscode"]
license	Apache-2.0
metadata	{"author":"hackathon-team","version":"1.0.0","aws-services":["general"]}

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:

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:

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:

# 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

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