Run any Skill in Manus with one click

aws-architecture-diagram

Stars116

Forks14

UpdatedJuly 22, 2026 at 11:06

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.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

vidanov

vidanov/aws-architecture-diagram-skill

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

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;outlineConnect=0; on all icons
Use strokeColor=#ffffff on all AWS service icons
MUST include fillColor — without it, icons render as invisible/white in PNG export
Font size: 12px for labels
Always include: fontColor=#232F3E;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;aspect=fixed;

fillColor by AWS service category:

Category	fillColor	Services
Compute	`#ED7100`	Lambda, EC2, ECS, EKS, Fargate
Networking	`#8C4FFF`	VPC, ELB, CloudFront, Route 53, API Gateway
Database	`#C925D1`	RDS, DynamoDB, Aurora, ElastiCache
Storage	`#3F8624`	S3, EFS, EBS
Security	`#DD344C`	IAM, Cognito, KMS, WAF
Integration	`#E7157B`	SQS, SNS, EventBridge, Step Functions
Analytics	`#8C4FFF`	Kinesis, Athena, Redshift
Management	`#E7157B`	CloudWatch, CloudTrail
AI/ML	`#01A88D`	Bedrock, SageMaker

3D / Isometric Diagrams — use a different icon library

If the user asks for a 3D, isometric, or "AWS 3D" diagram, do NOT fake it by placing flat aws4 icons on hand-built platform/pedestal shapes. draw.io has a real, separate built-in library for this: mxgraph.aws3d.*.

Load references/aws-icons-3d.md before picking any icon — it has the verified shape table, style prefix, sizes, and the native isometricEdgeStyle edge templates.
This library is a legacy pre-2019 icon set with much smaller coverage than aws4 (no API Gateway, ECS/EKS/Fargate, Step Functions, EventBridge, SNS, Aurora, CloudWatch, IAM, etc.). Check the gap table in that reference file before assuming an icon exists, and flag substitutions to the user rather than guessing a stencil name.
For generic hardware (clients, on-prem servers, racks, switches) with no AWS-specific icon, see references/aws-icons-allied-telesis.md — a separate bundled isometric image library that fills that gap.
These icons are already 3D on their own — arrange them in an ascending isometric staircase (diagonal offsets between nodes), don't add fake platforms underneath.
Use edgeStyle=isometricEdgeStyle (with endArrow=block override for reliable arrowheads) instead of orthogonalEdgeStyle for connectors.

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

Edge attachment (CRITICAL — fixes "green cross" problem):

Every edge MUST have both source="<cell-id>" and target="<cell-id>" attributes referencing valid cell IDs
NEVER create floating/unattached edges — all edges must be bound to shapes at both ends
Always include exitX/exitY and entryX/entryY to define exact connection points on the shape perimeter
In draw.io, properly attached edges show a "blue dot" anchor; unattached edges show a "green cross"
If an edge connects to a child inside a container, reference the child's ID directly (not the container)
Cross-container edges: When source and target are in different containers, set the edge's parent="1" (root layer) so draw.io can route it across boundaries

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

Visual Quality: straight arrows, no overlaps, professional layout

A diagram with correct icons but a messy layout still reads as unprofessional. Check every diagram against these rules before finishing — they're deliberately concrete/checkable, not vague "make it look nice" advice:

Align nodes to a consistent axis so edges are single, straight segments. Keep the horizontal or vertical delta between adjacent nodes in a flow constant (same lane y-coordinate, same column spacing) so connecting edges render as one clean line instead of a dogleg.
Align branch/secondary nodes on the exact same centerline as their parent. If a node branches off vertically (e.g. an auxiliary service below the main flow), its horizontal center must match its parent's horizontal center exactly — compute child.x = parent.center_x - child.width/2, don't eyeball it. A few pixels of misalignment turns a "straight down" edge into a visibly crooked diagonal.
One bend maximum per edge, ideally zero. If a computed edge path would need more than one bend to avoid an obstacle, the layout is wrong — move the node, don't add more bends to route around the problem.
No edge may cross through an unrelated icon's bounding box. Before finalizing coordinates, check each edge's path against every icon's (x, y, width, height) rectangle it isn't connected to. If it would cross one, move the node or add an explicit exit/entry point to route around it.
No two edges may run on top of each other or visually merge. If two edges would travel the same corridor (e.g. two parallel flows between the same pair of lanes), offset them — different exit/entry points, or an explicit waypoint — so there's a visible gap between them.
Minimize edge crossings overall. Order nodes in the direction the data actually flows so edges rarely need to cross each other. If a crossing is unavoidable (e.g. a feedback/response path), route it with a visible offset rather than letting it overlap another edge.
Keep spacing consistent, not just "enough." Use the same minimum step size between every pair of adjacent nodes in a flow — a diagram where some gaps are 400px and others are 250px reads as sloppy even if nothing technically overlaps.
Balance the composition on the canvas. Don't leave one half of the page dense and the other empty; size the canvas to the actual content plus a consistent margin.
Self-check before finishing: after placing every coordinate, mentally trace each edge from source to target and verify (1) it doesn't cross any icon, (2) it doesn't overlap another edge, (3) it has at most one bend, (4) its endpoints are flush with the icons it connects. Fix the layout, not just the intent, if any check fails.

Two Icon Patterns — CRITICAL

Pattern 1: Service-level (resourceIcon frame)

Style: sketch=0;outlineConnect=0;fontColor=#232F3E;fillColor=<CATEGORY_COLOR>;strokeColor=#ffffff;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=12;fontStyle=0;aspect=fixed;shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.<name>
MUST use strokeColor=#ffffff — without it, the white glyph disappears
MUST use fillColor=<color> — without it, icon renders as white/invisible square in PNG export
Size: 78x78

Pattern 2: Resource-level (standalone shape)

Style: sketch=0;outlineConnect=0;fontColor=#232F3E;fillColor=<CATEGORY_COLOR>;strokeColor=none;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=12;fontStyle=0;aspect=fixed;shape=mxgraph.aws4.<name>
MUST use strokeColor=none — using #ffffff breaks these
MUST use fillColor=<color> — same reason as above
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
references/aws-icons-3d.md — 3D/isometric diagrams: legacy aws3d icon library, coverage gaps, isometric edge style
references/aws-icons-allied-telesis.md — bonus isometric computer/server/network icons for 3D diagrams (fills aws3d gaps)

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

Fallback for unmapped services: If a service is NOT found in any reference file, use this generic AWS cloud icon with the service name as label:

sketch=0;outlineConnect=0;fontColor=#232F3E;fillColor=#232F3E;strokeColor=#ffffff;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=12;fontStyle=0;aspect=fixed;shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.general_AWScloud

Never render an unknown service as a plain colored rectangle with no label.

Group Boundaries

AWS Cloud: shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_aws_cloud_alt;strokeColor=#232F3E;fillColor=none;container=1;dropTarget=1;
Account: shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_account;strokeColor=#CD2264;fillColor=none;container=1;dropTarget=1;
On-premise: shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_on_premise;strokeColor=#5A6C86;fillColor=none;container=1;dropTarget=1;
VPC: shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_vpc2;strokeColor=#8C4FFF;fillColor=none;container=1;dropTarget=1;
Subnet (public): shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_security_group;strokeColor=#7AA116;fillColor=none;container=1;dropTarget=1;
Subnet (private): shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_security_group;strokeColor=#147EBA;fillColor=none;container=1;dropTarget=1;
Logical groups: Simple dashed boxes: whiteSpace=wrap;html=1;fillColor=none;dashed=1;dashPattern=8 8;container=1;dropTarget=1;
NO colored backgrounds on group boxes — always fillColor=none

Container nesting (CRITICAL for grouping):

ALL boundary/group shapes MUST include container=1;dropTarget=1; in their style
Child cells inside a boundary MUST set parent="<boundary-cell-id>" instead of parent="1"
This ensures moving a boundary moves all its children together
Example:

<mxCell id="vpc1" value="VPC" style="shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_vpc2;strokeColor=#8C4FFF;fillColor=none;container=1;dropTarget=1;" vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="800" height="500" as="geometry" />
</mxCell>
<mxCell id="lambda1" value="Lambda" style="shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.lambda;strokeColor=#ffffff;" vertex="1" parent="vpc1">
  <mxGeometry x="50" y="50" width="78" height="78" as="geometry" />
</mxCell>

Note: child geometry coordinates are relative to the parent container, not the canvas.

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:

Header + left side (frontend, delivery layer)
Middle (processing lambdas, database)
Right side (ingest, messaging, data sources)
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:

Export to PNG using the draw.io CLI (see Output section)
Review the PNG visually — check for empty/broken icons, overlapping edges, misaligned labels
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; `opensearch_service` also works
Amazon EventBridge	`eventbridge`	Was CloudWatch Events
AWS Fargate	`fargate`	Correct
VPC Peering	`peering`	Resource-level: `shape=mxgraph.aws4.peering;strokeColor=none` — NOT `vpc_peering` or `peering_connection` (those render as blank squares)
Amazon MSK	`managed_streaming_for_kafka`	NOT `msk` (renders as blank square)
IAM Identity Center	`single_sign_on`	NOT `iam_identity_center` (renders as blank square)

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 (or Sidebar-AWS3D.js for the legacy 3D/isometric library, or Sidebar-AlliedTelesis.js for the generic hardware image library — note the 3D library's shape names are camelCase, e.g. dynamoDb not dynamodb).

Validation Step

After generating XML, mentally verify:

Every resIcon= value exists in the reference files
Service-level icons have strokeColor=#ffffff
Resource-level icons have strokeColor=none
No XML comments present
All cell IDs are unique
Every edge has <mxGeometry relative="1" as="geometry" />
No icon uses a guessed stencil name — all verified against reference files
Every edge has both source and target attributes referencing valid cell IDs (no floating edges)
All group/boundary shapes include container=1;dropTarget=1; in their style
Children inside boundaries use parent="<boundary-id>" (not parent="1")

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

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;outlineConnect=0; on all icons
Use strokeColor=#ffffff on all AWS service icons
MUST include fillColor — without it, icons render as invisible/white in PNG export
Font size: 12px for labels
Always include: fontColor=#232F3E;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;aspect=fixed;

fillColor by AWS service category:

Category	fillColor	Services
Compute	`#ED7100`	Lambda, EC2, ECS, EKS, Fargate
Networking	`#8C4FFF`	VPC, ELB, CloudFront, Route 53, API Gateway
Database	`#C925D1`	RDS, DynamoDB, Aurora, ElastiCache
Storage	`#3F8624`	S3, EFS, EBS
Security	`#DD344C`	IAM, Cognito, KMS, WAF
Integration	`#E7157B`	SQS, SNS, EventBridge, Step Functions
Analytics	`#8C4FFF`	Kinesis, Athena, Redshift
Management	`#E7157B`	CloudWatch, CloudTrail
AI/ML	`#01A88D`	Bedrock, SageMaker

3D / Isometric Diagrams — use a different icon library

Load references/aws-icons-3d.md before picking any icon — it has the verified shape table, style prefix, sizes, and the native isometricEdgeStyle edge templates.
This library is a legacy pre-2019 icon set with much smaller coverage than aws4 (no API Gateway, ECS/EKS/Fargate, Step Functions, EventBridge, SNS, Aurora, CloudWatch, IAM, etc.). Check the gap table in that reference file before assuming an icon exists, and flag substitutions to the user rather than guessing a stencil name.
For generic hardware (clients, on-prem servers, racks, switches) with no AWS-specific icon, see references/aws-icons-allied-telesis.md — a separate bundled isometric image library that fills that gap.
These icons are already 3D on their own — arrange them in an ascending isometric staircase (diagonal offsets between nodes), don't add fake platforms underneath.
Use edgeStyle=isometricEdgeStyle (with endArrow=block override for reliable arrowheads) instead of orthogonalEdgeStyle for connectors.

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

Edge attachment (CRITICAL — fixes "green cross" problem):

Every edge MUST have both source="<cell-id>" and target="<cell-id>" attributes referencing valid cell IDs
NEVER create floating/unattached edges — all edges must be bound to shapes at both ends
Always include exitX/exitY and entryX/entryY to define exact connection points on the shape perimeter
In draw.io, properly attached edges show a "blue dot" anchor; unattached edges show a "green cross"
If an edge connects to a child inside a container, reference the child's ID directly (not the container)
Cross-container edges: When source and target are in different containers, set the edge's parent="1" (root layer) so draw.io can route it across boundaries

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

Visual Quality: straight arrows, no overlaps, professional layout

Align nodes to a consistent axis so edges are single, straight segments. Keep the horizontal or vertical delta between adjacent nodes in a flow constant (same lane y-coordinate, same column spacing) so connecting edges render as one clean line instead of a dogleg.
Align branch/secondary nodes on the exact same centerline as their parent. If a node branches off vertically (e.g. an auxiliary service below the main flow), its horizontal center must match its parent's horizontal center exactly — compute child.x = parent.center_x - child.width/2, don't eyeball it. A few pixels of misalignment turns a "straight down" edge into a visibly crooked diagonal.
One bend maximum per edge, ideally zero. If a computed edge path would need more than one bend to avoid an obstacle, the layout is wrong — move the node, don't add more bends to route around the problem.
No edge may cross through an unrelated icon's bounding box. Before finalizing coordinates, check each edge's path against every icon's (x, y, width, height) rectangle it isn't connected to. If it would cross one, move the node or add an explicit exit/entry point to route around it.
No two edges may run on top of each other or visually merge. If two edges would travel the same corridor (e.g. two parallel flows between the same pair of lanes), offset them — different exit/entry points, or an explicit waypoint — so there's a visible gap between them.
Minimize edge crossings overall. Order nodes in the direction the data actually flows so edges rarely need to cross each other. If a crossing is unavoidable (e.g. a feedback/response path), route it with a visible offset rather than letting it overlap another edge.
Keep spacing consistent, not just "enough." Use the same minimum step size between every pair of adjacent nodes in a flow — a diagram where some gaps are 400px and others are 250px reads as sloppy even if nothing technically overlaps.
Balance the composition on the canvas. Don't leave one half of the page dense and the other empty; size the canvas to the actual content plus a consistent margin.
Self-check before finishing: after placing every coordinate, mentally trace each edge from source to target and verify (1) it doesn't cross any icon, (2) it doesn't overlap another edge, (3) it has at most one bend, (4) its endpoints are flush with the icons it connects. Fix the layout, not just the intent, if any check fails.

Two Icon Patterns — CRITICAL

Pattern 1: Service-level (resourceIcon frame)

Style: sketch=0;outlineConnect=0;fontColor=#232F3E;fillColor=<CATEGORY_COLOR>;strokeColor=#ffffff;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=12;fontStyle=0;aspect=fixed;shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.<name>
MUST use strokeColor=#ffffff — without it, the white glyph disappears
MUST use fillColor=<color> — without it, icon renders as white/invisible square in PNG export
Size: 78x78

Pattern 2: Resource-level (standalone shape)

Style: sketch=0;outlineConnect=0;fontColor=#232F3E;fillColor=<CATEGORY_COLOR>;strokeColor=none;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=12;fontStyle=0;aspect=fixed;shape=mxgraph.aws4.<name>
MUST use strokeColor=none — using #ffffff breaks these
MUST use fillColor=<color> — same reason as above
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
references/aws-icons-3d.md — 3D/isometric diagrams: legacy aws3d icon library, coverage gaps, isometric edge style
references/aws-icons-allied-telesis.md — bonus isometric computer/server/network icons for 3D diagrams (fills aws3d gaps)

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

Fallback for unmapped services: If a service is NOT found in any reference file, use this generic AWS cloud icon with the service name as label:

sketch=0;outlineConnect=0;fontColor=#232F3E;fillColor=#232F3E;strokeColor=#ffffff;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=12;fontStyle=0;aspect=fixed;shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.general_AWScloud

Never render an unknown service as a plain colored rectangle with no label.

Group Boundaries

AWS Cloud: shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_aws_cloud_alt;strokeColor=#232F3E;fillColor=none;container=1;dropTarget=1;
Account: shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_account;strokeColor=#CD2264;fillColor=none;container=1;dropTarget=1;
On-premise: shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_on_premise;strokeColor=#5A6C86;fillColor=none;container=1;dropTarget=1;
VPC: shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_vpc2;strokeColor=#8C4FFF;fillColor=none;container=1;dropTarget=1;
Subnet (public): shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_security_group;strokeColor=#7AA116;fillColor=none;container=1;dropTarget=1;
Subnet (private): shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_security_group;strokeColor=#147EBA;fillColor=none;container=1;dropTarget=1;
Logical groups: Simple dashed boxes: whiteSpace=wrap;html=1;fillColor=none;dashed=1;dashPattern=8 8;container=1;dropTarget=1;
NO colored backgrounds on group boxes — always fillColor=none

Container nesting (CRITICAL for grouping):

ALL boundary/group shapes MUST include container=1;dropTarget=1; in their style
Child cells inside a boundary MUST set parent="<boundary-cell-id>" instead of parent="1"
This ensures moving a boundary moves all its children together
Example:

<mxCell id="vpc1" value="VPC" style="shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_vpc2;strokeColor=#8C4FFF;fillColor=none;container=1;dropTarget=1;" vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="800" height="500" as="geometry" />
</mxCell>
<mxCell id="lambda1" value="Lambda" style="shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.lambda;strokeColor=#ffffff;" vertex="1" parent="vpc1">
  <mxGeometry x="50" y="50" width="78" height="78" as="geometry" />
</mxCell>

Note: child geometry coordinates are relative to the parent container, not the canvas.

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:

Header + left side (frontend, delivery layer)
Middle (processing lambdas, database)
Right side (ingest, messaging, data sources)
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:

Export to PNG using the draw.io CLI (see Output section)
Review the PNG visually — check for empty/broken icons, overlapping edges, misaligned labels
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; `opensearch_service` also works
Amazon EventBridge	`eventbridge`	Was CloudWatch Events
AWS Fargate	`fargate`	Correct
VPC Peering	`peering`	Resource-level: `shape=mxgraph.aws4.peering;strokeColor=none` — NOT `vpc_peering` or `peering_connection` (those render as blank squares)
Amazon MSK	`managed_streaming_for_kafka`	NOT `msk` (renders as blank square)
IAM Identity Center	`single_sign_on`	NOT `iam_identity_center` (renders as blank square)

Validation Step

After generating XML, mentally verify:

Every resIcon= value exists in the reference files
Service-level icons have strokeColor=#ffffff
Resource-level icons have strokeColor=none
No XML comments present
All cell IDs are unique
Every edge has <mxGeometry relative="1" as="geometry" />
No icon uses a guessed stencil name — all verified against reference files
Every edge has both source and target attributes referencing valid cell IDs (no floating edges)
All group/boundary shapes include container=1;dropTarget=1; in their style
Children inside boundaries use parent="<boundary-id>" (not parent="1")

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

aws-architecture-diagram

More from this repository

More from this repository

Instructions

Layout

Canvas

Icon Style

3D / Isometric Diagrams — use a different icon library

Edge Style — CRITICAL FOR CLEAN DIAGRAMS

Visual Quality: straight arrows, no overlaps, professional layout

Two Icon Patterns — CRITICAL

Icon Reference Files (load by category as needed)

Group Boundaries

PNG Export Background Fix

Multi-page Diagrams

Edge Legend (optional, for complex diagrams)

File Splitting

Audience Mode

Numbered Flow Edges (for non-technical mode)

Companion Guide

Two-Step Edit Approach

Icon Name Gotchas — CRITICAL

Validation Step

Output

XML Well-formedness (CRITICAL)

Official Reference

Instructions

Layout

Canvas

Icon Style

3D / Isometric Diagrams — use a different icon library

Edge Style — CRITICAL FOR CLEAN DIAGRAMS

Visual Quality: straight arrows, no overlaps, professional layout

Two Icon Patterns — CRITICAL

Icon Reference Files (load by category as needed)

Group Boundaries

PNG Export Background Fix

Multi-page Diagrams

Edge Legend (optional, for complex diagrams)

File Splitting

Audience Mode

Numbered Flow Edges (for non-technical mode)

Companion Guide

Two-Step Edit Approach

Icon Name Gotchas — CRITICAL

Validation Step

Output

XML Well-formedness (CRITICAL)

Official Reference