# Aws Diagram

> |

- **Type:** Skill
- **Install:** `agentstack add skill-jesamkim-oh-my-skills-aws-diagram`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jesamkim](https://agentstack.voostack.com/s/jesamkim)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jesamkim](https://github.com/jesamkim)
- **Source:** https://github.com/jesamkim/oh-my-skills/tree/main/my-skills/aws-diagram

## Install

```sh
agentstack add skill-jesamkim-oh-my-skills-aws-diagram
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# AWS Architecture Diagram Generator

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

## Quick Start

```bash
# 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.

```json
{
  "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 pptx_native_lib.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

```bash
# 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:**
```json
{"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.:
```json
{"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](https://github.com/jesamkim)
- **Source:** [jesamkim/oh-my-skills](https://github.com/jesamkim/oh-my-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jesamkim-oh-my-skills-aws-diagram
- Seller: https://agentstack.voostack.com/s/jesamkim
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.