aws-architecture-diagram

name	aws-architecture-diagram
description	Generate AWS architecture diagrams in draw.io format. Activates when the user asks to create, generate, or build an architecture diagram, system diagram, or draw.io diagram for AWS services.

Instructions

Generate a draw.io (.drawio) XML file representing an AWS architecture diagram.

Layout

• Left-to-right flow for data/request path
• UI/Frontend on the LEFT (users access from left side)
• Data sources / external systems on the RIGHT
• Use horizontal lanes for parallel paths (top lane, bottom lane)
• Minimum 220px horizontal spacing between icons (to leave room for edge labels)
• Minimum 250px vertical spacing between lanes (so vertical edges don't crowd)
• Secondary/auxiliary services (monitoring, DLQ, error paths) go BELOW the main flow with 280px+ vertical gap

Canvas

• Large canvas: pageWidth="2400" pageHeight="1400" minimum
• Set dx="2800" dy="1600" for proper viewport
• Always include a title block as the first element after the background:

<mxCell value="&lt;b&gt;Diagram Title&lt;/b&gt;&lt;br&gt;Author | Date | Version" style="text;html=1;align=left;verticalAlign=top;whiteSpace=wrap;rounded=0;fontSize=14;spacing=8;" vertex="1" parent="1">
  <mxGeometry x="40" y="30" width="420" height="60" as="geometry" />
</mxCell>

Icon Style

• Icons are from draw.io's built-in mxgraph.aws4 stencil library — the official AWS Architecture Icons (https://aws.amazon.com/architecture/icons/, updated quarterly)
• Icon size: 78x78px for main services, 65x65px for secondary
• Use sketch=0 on all icons
• Use strokeColor=#ffffff on all AWS service icons
• Font size: 12px for labels

Edge Style — CRITICAL FOR CLEAN DIAGRAMS

Base edge style (all edges):

edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;

Rules for edge labels:

• Keep labels SHORT (1-2 words max). Use icon labels for detail, not edge labels.
• On horizontal edges: position label ABOVE the line using verticalAlign=bottom; in the edge style
• On vertical edges: position label to the LEFT using align=right; in the edge style
• Always add labelBackgroundColor=#F5F5F5; so labels don't overlap lines
• For edges WITHOUT labels: omit the value attribute entirely (don't use value="")

Edge label positioning (prevents overlap with icons):

<mxCell value="Label" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;labelBackgroundColor=#F5F5F5;fontSize=11;" edge="1" source="a" target="b" parent="1">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

For edges that go to services ABOVE or BELOW the main flow:

• Use explicit exit/entry points to control routing:
  • Exit bottom: exitX=0.5;exitY=1;exitDx=0;exitDy=0;
  • Enter top: entryX=0.5;entryY=0;entryDx=0;entryDy=0;
  • Exit top: exitX=0.5;exitY=0;exitDx=0;exitDy=0;
  • Enter bottom: entryX=0.5;entryY=1;entryDx=0;entryDy=0;
• This prevents draw.io from routing lines through other icons

Edge types:

• Solid black (strokeWidth=2): primary data flow
• Dashed black (strokeWidth=2;dashed=1;): optional/async path
• Dashed red (strokeWidth=2;dashed=1;strokeColor=#DD344C;): error path

When NOT to label edges:

• If the flow is obvious from context (e.g., Lambda → DynamoDB doesn't need "Write")
• If the icon labels already explain the relationship
• Prefer fewer, more meaningful labels over labeling every edge

Two Icon Patterns — CRITICAL

Pattern 1: Service-level (resourceIcon frame)

• Style: shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.<name>
• MUST use strokeColor=#ffffff — without it, the white glyph disappears
• Size: 78x78

Pattern 2: Resource-level (standalone shape)

• Style: shape=mxgraph.aws4.<name> directly (no resIcon)
• MUST use strokeColor=none — using #ffffff breaks these
• Size: 78x78 or 48x48

Confusing these patterns guarantees broken icons.

Icon Reference Files (load by category as needed)

• references/aws-icons-compute.md — Lambda, EC2, ECS, EKS, Fargate
• references/aws-icons-database.md — DynamoDB, RDS, Aurora, ElastiCache
• references/aws-icons-integration.md — API Gateway, SQS, SNS, EventBridge, Step Functions
• references/aws-icons-networking.md — CloudFront, Route 53, VPC, ELB
• references/aws-icons-storage.md — S3, EFS, EBS, Glacier, Backup
• references/aws-icons-security.md — IAM, Cognito, KMS, WAF, Shield
• references/aws-icons-analytics-ml.md — Kinesis, Athena, Bedrock, SageMaker
• references/aws-icons-common.md — Groups, general resources, edge styles, base template

Always look up icons from reference files. Never guess icon names.

Group Boundaries

• AWS Cloud: shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_aws_cloud_alt;strokeColor=#232F3E;fillColor=none
• Account: shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_account;strokeColor=#CD2264;fillColor=none
• On-premise: shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_on_premise;strokeColor=#5A6C86;fillColor=none
• Logical groups: Simple dashed boxes: whiteSpace=wrap;html=1;fillColor=none;dashed=1;dashPattern=8 8
• NO colored backgrounds on group boxes — always fillColor=none

PNG Export Background Fix

Place a full-canvas rectangle as the FIRST element (lowest z-order):

<mxCell value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#F5F5F5;strokeColor=none;" vertex="1" parent="1">
  <mxGeometry x="0" y="0" width="2400" height="1400" as="geometry" />
</mxCell>

This prevents black background on PNG export. Use strokeColor=none (not E0E0E0).

Multi-page Diagrams

For complex architectures, use multiple pages (tabs) in one .drawio file:

<mxfile>
  <diagram id="overview" name="Overview">...</diagram>
  <diagram id="networking" name="Networking Detail">...</diagram>
  <diagram id="data-flow" name="Data Flow">...</diagram>
</mxfile>

• Page 1: High-level overview (service-level icons only)
• Page 2+: Detail views (resource-level icons, subnet layouts, etc.)

Edge Legend (optional, for complex diagrams)

Place below the title block if the diagram has multiple edge types:

• Solid line: primary data flow
• Dashed line: optional/async
• Red dashed: error path

File Splitting

Since draw.io XML can be large, split creation across multiple tool calls:

1. Header + left side (frontend, delivery layer)
2. Middle (processing lambdas, database)
3. Right side (ingest, messaging, data sources)
4. Bottom (optional/outbound flows) + close XML

Audience Mode

Before generating, assess the target audience:

• Technical: Use service names, protocol labels (HTTPS, gRPC), CIDR blocks, instance types
• Non-technical: Use action labels ("Store Data", "Send Notification"), hide implementation details, use numbered flow (① ② ③)

If unclear, ask: "Technical audience or executive/non-technical?"

Numbered Flow Edges (for non-technical mode)

Instead of technical labels, show flow order with circled numbers:

• Flow A: ① → ② → ③ → ④ (white circled numbers)
• Flow B: ❶ → ❷ → ❸ → ❹ (black circled numbers for second flow)

Use edge labels: value="①" with fontSize=14;fontStyle=1;labelBackgroundColor=#ffffff;

Companion Guide

After generating the .drawio file, also generate a markdown guide:

• Same filename with .md extension (e.g., serverless-api.drawio + serverless-api.md)
• Contents: diagram title, flow description (numbered steps matching edge labels), service list with purpose, key design decisions

Two-Step Edit Approach

After generating the initial .drawio file:

1. Export to PNG using the draw.io CLI (see Output section)
2. Review the PNG visually — check for empty/broken icons, overlapping edges, misaligned labels
3. Fix issues in the .drawio XML and re-export

This catches rendering problems (wrong stencil names, broken styles) that are invisible in raw XML.

Icon Name Gotchas — CRITICAL

draw.io stencil names do NOT always match current AWS service names. Services that were renamed keep their legacy stencil names:

AWS Service Name	draw.io resIcon name	Why
Amazon OpenSearch Service	elasticsearch_service	Renamed from Elasticsearch in 2021
Amazon EventBridge	eventbridge	Was CloudWatch Events
AWS Fargate	fargate	Correct

Rule: Always verify icon names from the reference files. If a service icon renders as an empty box, the stencil name is wrong. Check the draw.io source at src/main/webapp/js/diagramly/sidebar/Sidebar-AWS4.js for the canonical name.

Validation Step

After generating XML, mentally verify:

1. Every resIcon= value exists in the reference files
2. Service-level icons have strokeColor=#ffffff
3. Resource-level icons have strokeColor=none
4. No XML comments present
5. All cell IDs are unique
6. Every edge has <mxGeometry relative="1" as="geometry" />
7. No icon uses a guessed stencil name — all verified against reference files

Output

• Save with descriptive filename ending in .drawio
• Open with open command (macOS) or xdg-open (Linux) after creation
• For PNG/SVG/PDF export, use draw.io CLI:
  • macOS: /Applications/draw.io.app/Contents/MacOS/draw.io -x -f png -e -b 10 -o output.drawio.png input.drawio
  • Linux: drawio -x -f png -e -b 10 -o output.drawio.png input.drawio Flags: -x export, -f format, -e embed diagram XML, -b 10 border
• Exported files use double extension: name.drawio.png (signals embedded XML, re-editable in draw.io)

XML Well-formedness (CRITICAL)

• NEVER include XML comments (<!-- -->) — they cause parse errors
• Escape special characters in values: & < > "
• Always use unique id values for each mxCell
• Every edge MUST have <mxGeometry relative="1" as="geometry" /> as child element
• Basic structure must include root cells id="0" and id="1" (parent="0")

Official Reference

• Full XML/style reference: https://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/xml-reference.md
• Style properties: https://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/style-reference.md