Aws Diagram

AWS Architecture Diagram Generator

Generate professional AWS architecture diagrams with official service icons, guaranteed orthogonal arrow routing, and standard AWS design system.

Quick Start

# 1. Create JSON definition (see Schema below)
# 2. Generate SVG + PNG
python3 scripts/generate_diagram.py -i diagram.json -o output.svg --png

# 3. Verify: read the PNG and visually inspect
# 4. PPTX needed? Build it from NATIVE PowerPoint shapes (editable in PPT) —
#    read references/pptx-native-workflow.md and scripts/pptx_native_lib.py.
#    Embedding the diagram as a flat PNG via add_picture is NOT an acceptable
#    substitute (only as an optional companion slide next to the native one).
#    generate_diagram.py --pptx exists but produces broken layouts on complex
#    diagrams (CJK labels, 4+ containers) — avoid it for customer deliverables

---

Workflow

Primary: JSON-Driven Generation (Recommended)

The Python engine handles layout, routing, and rendering deterministically. Claude produces a JSON definition; the engine guarantees correct output.

1. Analyze user requirements -> identify services, connections, containers
2. Choose diagram type: Infrastructure (VPC-centric) or High-Level (logical grouping)
3. Create a JSON diagram definition (see Schema below)
4. Run: python3 scripts/generate_diagram.py -i diagram.json -o output.svg --png
5. QA: visually inspect the PNG output (MANDATORY)
6. PPTX deliverable: see "Native PPTX" path below — do NOT default to --pptx

Native PPTX: Editable PowerPoint Slides (the default for ANY PPTX request)

Whenever the deliverable is a PPTX, the diagram must be drawn with native PowerPoint objects — real shapes, connectors, and text boxes the user can select, move, recolor, and re-label directly in PowerPoint. Do NOT satisfy a PPTX request by rendering the diagram to PNG/SVG and pasting it onto a slide as a picture. A pasted image looks identical in a review but is dead weight the moment the customer opens it: they cannot fix a label typo, move a box, or adapt the architecture — which is the whole reason they asked for PPTX instead of PNG. Treat every PPTX request as an editable-shapes request unless the user explicitly says an image-only slide is fine.

The px->EMU exporter behind --pptx is unreliable for complex diagrams — field-verified failure (2026-06: 12 nodes / 5 containers / Korean labels) produced 20 visual defects: containers piercing icons, orphaned labels, arrows through text, CJK labels wrapped to 3 lines.

Instead, write a small build script against scripts/pptx_native_lib.py (NativeSlideBuilder: container/line/ arrow_label/node helpers with AWS design-system colors baked in), using explicit inch coordinates. Then render via LibreOffice and QA with a subagent — self-review of your own layout reliably misses defects.

Read references/pptx-native-workflow.md before starting — it has the workflow, a script skeleton, and a layout-rule table where each rule maps to a real observed defect (node pitch >= 1.55in, container clearance, vertical arrows must clear label blocks, etc.).

The common 2-slide deliverable: slide 1 = PNG embed (best-looking), slide 2 = native shapes (editable), both from one build script. The native slide is the mandatory part; the PNG slide is an optional bonus — never ship a PPTX that contains only the picture.

Fallback: Manual SVG

For very simple diagrams (2-3 services, no containers), hand-craft SVG following the rules in Sections 3-7 below. Use icons/ directory for service icons.

---

JSON Diagram Schema

Claude generates this JSON; the Python engine handles the rest.

{
  "title": "3-Tier Web Application",
  "subtitle": "ALB + EC2 + RDS on AWS",
  "theme": "light",
  "size": "standard",
  "nodes": [
    {"id": "alb", "service": "elb", "label": "Application\nLoad Balancer", "x": 1, "y": 1, "container": "pub-sub"},
    {"id": "ec2", "service": "ec2", "label": "Amazon EC2", "sublabel": "Web Server", "x": 2, "y": 1, "container": "priv-sub"}
  ],
  "connections": [
    {"source": "alb", "target": "ec2", "label": "HTTP", "style": "solid", "step_number": 1},
    {"source": "dc", "target": "alb", "label": "Direct Connect", "style": "dashed", "color": "#8C4FFF", "source_port": "right"}
  ],
  "containers": [
    {"id": "cloud", "type": "aws-cloud", "label": "AWS Cloud", "children": ["vpc"]},
    {"id": "vpc", "type": "vpc", "label": "VPC", "parent": "cloud", "children": ["pub-sub", "priv-sub"]},
    {"id": "pub-sub", "type": "public-subnet", "label": "Public subnet", "parent": "vpc", "children": ["alb"]},
    {"id": "priv-sub", "type": "private-subnet", "label": "Private subnet", "parent": "vpc", "children": ["ec2"]}
  ]
}

Node fields: id, service (icon filename without .svg), label, x/y (grid), sublabel?, container? Connection fields: source, target, label?, style (solid/dashed/bidirectional), step_number?, color? (hex), source_port? (left/right/top/bottom), target_port? (left/right/top/bottom) Container fields: id, type, label, parent?, children[] Container types: aws-cloud, region, vpc, az, public-subnet, private-subnet, security-group, auto-scaling-group, generic Size presets: simple (800x500), standard (1024x768), complex (1200x900), wide (1400x600) Themes: light (white bg, default), dark (AWS Squid Ink #232F3E bg)

---

Engine Architecture

The Python engine consists of 7 modules with clear separation of concerns:

| Module | Responsibility | |--------|---------------| | generate_diagram.py | CLI entry point, orchestrates pipeline | | diagram_schema.py | JSON schema, data classes (DiagramNode, DiagramConnection, DiagramContainer, DiagramDefinition), serialization | | layout_engine.py | Grid-to-pixel coordinate computation, container bounding box calculation | | orthogonal_router.py | Arrow routing (L-shape, Z-shape), obstacle avoidance, label/callout placement | | svg_renderer.py | SVG assembly with inline icon symbols, container styling, arrow rendering | | pptx_export.py | Automated PPTX export (px->EMU translation) — unreliable on complex/CJK diagrams, prefer pptxnativelib.py | | pptx_native_lib.py | NativeSlideBuilder — hand-coordinate editable PPTX helpers (containers, arrows, labeled nodes, icon rasterizer) | | pptx_connector.py | OOXML connector injection for native PowerPoint arrows | | icon_rasterizer.py | SVG-to-PNG rasterization for PPTX icon embedding |

Layout Constants (for precise positioning)

| Constant | Value | Description | |----------|-------|-------------| | ICON_SIZE | 48px | Service icon dimensions | | CELL_WIDTH | 180px | Grid cell width (x-axis spacing) | | CELL_HEIGHT | 160px | Grid cell height (y-axis spacing) | | CANVAS_MARGIN | 60px | Outer margin around all content | | HEADER_HEIGHT | 26px | Container header bar height | | ICON_LABEL_GAP | 14px | Gap between icon and label text | | CALLOUT_RADIUS | 12px | Step number circle radius | | PARALLEL_OFFSET | 15px | Offset between parallel arrows |

---

CLI Usage

# SVG only
python3 scripts/generate_diagram.py -i diagram.json -o architecture.svg

# SVG + PNG (for QA and embedding)
python3 scripts/generate_diagram.py -i diagram.json -o architecture.svg --png

# SVG + PNG + PPTX
python3 scripts/generate_diagram.py -i diagram.json -o architecture.svg --png --pptx architecture.pptx

# Validate JSON before generating
python3 scripts/generate_diagram.py -i diagram.json -o architecture.svg --validate

# Custom icons directory
python3 scripts/generate_diagram.py -i diagram.json -o architecture.svg --icons-dir ./icons

# Custom PNG resolution
python3 scripts/generate_diagram.py -i diagram.json -o architecture.svg --png --png-width 3072

---

Diagram Types & When to Use

Type 1: Infrastructure Diagram (VPC-centric)

Use for: deployment architecture, network topology, security boundaries. Containers: AWS Cloud > Region > VPC > AZ > Subnet > Services. Examples: 3-tier web, microservices on EKS, multi-AZ RDS.

Type 2: High-Level Architecture (Logical Grouping)

Use for: platform overviews, service interactions, solution architecture briefs. Characteristics:

• NO VPC/Subnet containers -- use generic container type with dashed borders for logical groupings
• Hub-spoke layout -- central service (e.g., AgentCore Runtime, EventBridge) with radiating connections
• AWS Cloud container optional -- omit for cleaner presentation when all services are obviously AWS
• Multi-directional arrows -- not just left-to-right; use top/bottom/left/right ports freely
• Descriptive arrow labels -- "Agent invocations (Streamable HTTP)", "IdP integration", "Metrics & logs"
• Observability services at bottom -- CloudWatch, X-Ray placed below the main flow

High-Level Layout Pattern (Hub-Spoke):

x=0: External (User client at y=2)
x=1: Entry (Amplify/CloudFront at y=2), Auth (Cognito at y=1)
x=2: API Layer -- horizontal chain: API GW (y=0) → Lambda (y=0) → DynamoDB (y=0)
x=2: Hub center (AgentCore Runtime at y=2) inside generic dashed container
x=3: Spoke services (CodeInterpreter y=1, Identity y=2, Memory y=3)
x=4: External integrations (IdP at y=2, Custom Tool at y=3)
x=2~3 bottom: Observability (CloudWatch y=5, X-Ray y=5)

Generic container for logical grouping:

{"id": "platform", "type": "generic", "label": "Amazon Bedrock AgentCore", "children": ["runtime", "code-interp", "identity", "memory", "gateway", "observability"]}

Each child node inside the container should use the bedrock-agentcore icon so the whole platform reads as a single AWS service family, e.g.:

{"id": "runtime", "service": "bedrock-agentcore", "label": "AgentCore Runtime", "sublabel": "Strands + Memory", "x": 2, "y": 2, "container": "platform"}

AgentCore component-specific icons (May 2026 release)

For presentations that need to distinguish individual AgentCore sub-services at a glance, AgentCore-specific outline icons are available in icons/ with the pattern agentcore-{component}-{color}-{theme}.svg:

Components (9 total): logo, ai-agent, runtime, gateway, identity, code-interpreter, observability, browser-tool, memory

Color variants: teal (AWS brand #01A88D), blue (#538DF7), purple (#7B27FF), cyan (#7CF9FF, dark theme only)

Themes: light (black outline + accent color, for white/light backgrounds), dark (white outline + accent color, for dark backgrounds)

Examples:

• agentcore-runtime-teal-light.svg — AgentCore Runtime in AWS teal on light bg
• agentcore-memory-purple-dark.svg — AgentCore Memory in purple on dark bg

These icons share a visual motif (hexagonal brain glyph + service-specific accent) and are suited for slide decks or detailed L200 diagrams. For standard architecture diagrams, prefer the single bedrock-agentcore icon with sublabel for consistency with other AWS services.

---

AWS Category Color System

| Category | Hex | Services | |----------|-----|----------| | Compute | #ED7100 | EC2, Lambda, ECS, EKS, Fargate, Batch, App Runner, Lightsail, Auto Scaling, ECR | | Storage | #7AA116 | S3, EBS, EFS, FSx, Storage Gateway, S3 Glacier | | Database | #C925D1 | RDS, DynamoDB, Aurora, ElastiCache, Redshift, Neptune, DocumentDB, MemoryDB | | Networking | #8C4FFF | VPC, CloudFront, Route 53, API Gateway, ELB, Direct Connect, Transit Gateway, VPC Lattice, PrivateLink | | Security | #DD344C | IAM, WAF, Shield, KMS, Secrets Manager, ACM, Cognito, GuardDuty, Security Hub | | App Integration | #E7157B | SQS, SNS, EventBridge, Step Functions, AppSync, MQ | | AI/ML | #01A88D | Bedrock, Bedrock AgentCore, SageMaker, Rekognition, Textract, Comprehend, Lex, Amazon Q | | Management | #E7157B | CloudWatch, CloudFormation, CloudTrail, Systems Manager, Config, Organizations, X-Ray | | Analytics | #8C4FFF | Athena, Glue, Kinesis, QuickSight, Lake Formation, EMR, OpenSearch, Data Firehose |

Container Hierarchy & Styling

Nesting order (outermost to innermost):

AWS Cloud > Region > VPC > Availability Zone > Subnet > Service Icons

| Container | Border | Fill | Header | |-----------|--------|------|--------| | AWS Cloud | solid #232F3E 2px, rx=8 | none | dark bg, white text | | Region | dashed #00A4A6 1.5px | none | teal bg, white text | | VPC | solid #8C4FFF 1.5px | none | purple bg, white text | | AZ | dashed #147EBA 1px | none | text label only | | Public Subnet | solid #7AA116 1px | #E8F5E9/50% | green bg, white text | | Private Subnet | solid #147EBA 1px | #E3F2FD/50% | blue bg, white text | | Security Group | dashed #DD344C 1px | none | red text label | | Auto Scaling | dashed #ED7100 1px | none | orange text label | | Generic | solid #AEB6BF 1px, rx=4 | none | gray text label |

Generic container tip: For high-level diagrams, use "type": "generic" with descriptive labels to group related services without implying infrastructure boundaries.

Arrow Rules (AWS Architecture Icon Deck)

ALL arrows use straight lines and right angles. This is enforced by the Python engine.

• Style: Open Arrow, stroke-width 2, color #545B64 (light) / #D5DBDB (dark)
• Routing: Horizontal + vertical segments ONLY (M/L path commands, no curves)
• Diagonal: ONLY when right angles are impossible (rare edge case)
• Endpoints: Connect to CENTER of icon edge (not corners)
• Parallel arrows: Offset by >= 15px
• Labels: Italic, above the arrow line, >= 15px from callout circles
• Numbered callouts: Black circles (#232F3E) with white bold numbers
• Custom colors: Use color field (hex) for category-matched arrows (e.g., #8C4FFF for networking). Arrowhead markers auto-match the arrow color.
• Forced ports: Use source_port/target_port to control which edge arrows exit/enter. Useful when multiple arrows share a node.
• Title bar avoidance: Arrows auto-reroute below container title bars (VPC, AWS Cloud, Subnet headers).
• Multi-arrow separation: When multiple arrows exit the same icon, assign different ports (top=monitoring, right=main flow, bottom=data, left=bus pattern).

Arrow Style by Diagram Type

| Diagram Type | Default Arrow Style | |-------------|-------------------| | Infrastructure | Solid gray #545B64, numbered steps for request flow | | High-Level | Mix of solid (traffic) + dashed (internal/async), descriptive labels instead of step numbers |

Arrow Semantics

| Arrow Style | Use For | Example | |------------|---------|---------| | Solid | Direct traffic flow, synchronous calls | Users → CloudFront, API GW → Lambda | | Dashed | Async, internal, sidecar associations | Auth check, monitoring, event notifications | | Bidirectional | Two-way data exchange | DynamoDB Streams, WebSocket, sync replication |

Icon Labels (AWS Architecture Icon Deck)

• Font: 12pt Arial (Amazon Ember when available)
• Max 2 lines, "Amazon" or "AWS" prefix on first line
• Centered below icon with 12px gap
• Lines must NOT break mid-word

Sub-Agent Strategy (Complex Diagrams)

For diagrams with 8+ services, use sub-agents to speed up the workflow:

# Sub-agent 1: Generate the JSON diagram definition
"Analyze the user request and create a JSON diagram definition
following the aws-diagram schema. Services: [list]. Save to /tmp/diagram.json"

# Sub-agent 2: Run the Python engine (after JSON is ready)
"Run: python3 scripts/generate_diagram.py -i /tmp/diagram.json -o output.svg --png --pptx output.pptx"

# Sub-agent 3: QA inspection (after SVG/PNG are ready)
"Visually inspect the PNG. Check: arrows are orthogonal, no overlaps,
containers nested correctly, labels readable. Report issues."

Architecture Pattern Examples

See examples/ directory for complete JSON definitions:

| Pattern | File | Services | Type | |---------|------|----------|------| | 3-Tier Web (Multi-AZ) | examples/3-tier-web.json | CloudFro

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jesamkim
• Source: jesamkim/oh-my-skills
• License: MIT

Install and usage instructions live in the source repository linked above.