| name | aws-diagram |
| description | Generate AWS architecture diagrams in draw.io format following the awslabs official style. Supports PNG/SVG export via draw.io CLI and automated 6-point quality validation. Use when the user asks to create, update, or export an AWS architecture diagram. |
| license | Apache-2.0 |
AWS Architecture Diagram Generator
Generate professional AWS architecture diagrams in draw.io XML format, following the awslabs/agent-plugins official style specification.
Capabilities
- Generate
.drawio files with proper AWS service icons (mxgraph.aws4.*)
- Export to PNG/SVG/PDF via draw.io CLI
- Run automated 6-point quality validation
- Support light/dark mode adaptive colors
Usage
/aws-diagram <description of the architecture>
Examples:
/aws-diagram A serverless API with Lambda, API Gateway, DynamoDB, and S3
/aws-diagram Three-tier web app with ALB, ECS Fargate, Aurora, and ElastiCache
/aws-diagram ML pipeline with SageMaker Training, Model Registry, and S3
Output
The skill produces:
architecture.drawio - Editable draw.io XML filearchitecture.png - Exported PNG image (if draw.io CLI is installed)- Quality check report (6/6 must pass)
Workflow
Step 1: Gather Requirements
Ask the user (or infer from context):
- Which AWS services are involved?
- What is the data flow between them?
- Are there external actors (users, on-premises, third-party)?
- Any specific grouping (VPC, subnets, regions)?
Step 2: Generate draw.io XML
Write the .drawio file following the format specification below.
Step 3: Validate
Run the quality check script:
python3 skills/aws-diagram/scripts/validate_drawio.py <file.drawio>
All 6 checks must pass before delivery.
Step 4: Export PNG
wget https://github.com/jgraph/drawio-desktop/releases/download/v26.2.2/drawio-amd64-26.2.2.deb -O /tmp/drawio.deb
sudo dpkg -i /tmp/drawio.deb && sudo apt-get install -f -y
xvfb-run drawio --export --format png --border 10 --output output.png input.drawio
Quality Check Rules (6 Points)
Every generated diagram MUST pass all 6 checks:
| # | Rule | What to Check |
|---|
| 1 | AWS Cloud boundary | mxgraph.aws4.group_aws_cloud group present; external actors (Users) positioned outside; all AWS services positioned inside |
| 2 | No crossing lines | All edges use orthogonalEdgeStyle; query edges and registration edges exit at different Y positions; registration edges route around services via explicit waypoints (>= 3 waypoints) |
| 3 | Clear hierarchy | Elements follow left-to-right (or top-to-bottom) flow with increasing x (or y) coordinates |
| 4 | Color-coded edges | Different edge types use distinct visual styles: solid for synchronous, dashed for async/optional, open-arrow for data flow |
| 5 | All API calls labeled | Every edge representing an API call has a label with the method name |
| 6 | No emojis | No emoji characters in any diagram element values |
Draw.io XML Format Specification
XML Structure
<?xml version="1.0" encoding="UTF-8"?>
<mxfile>
<diagram name="Architecture" id="arch">
<mxGraphModel dx="2200" dy="900" grid="0" guides="1" tooltips="1"
connect="1" arrows="1" fold="1" page="0" pageScale="1"
pageWidth="2100" pageHeight="900">
<root>
<mxCell id="0" />
<mxCell id="1" parent="0" />
</root>
</mxGraphModel>
</diagram>
</mxfile>
Page sizing:
- Small (3-5 services):
pageWidth="800" pageHeight="600"
- Medium (6-12 services):
pageWidth="1169" pageHeight="827"
- Large (13+):
pageWidth="1600" pageHeight="1200"
- Add ~600px width for legend panel
Title Block
<mxCell id="title-group" connectable="0" style="group;fontFamily=Helvetica;" value="" vertex="1" parent="1">
<mxGeometry x="50" y="30" width="1200" height="83" as="geometry" />
</mxCell>
<mxCell id="title-text" style="text;html=1;resizable=1;points=[];autosize=1;align=left;verticalAlign=top;spacingTop=-4;fontSize=30;fontStyle=1;fontFamily=Helvetica;" value="Architecture Title" vertex="1" parent="title-group">
<mxGeometry width="800" height="42" as="geometry" />
</mxCell>
<mxCell id="subtitle-text" style="text;html=1;resizable=0;points=[];autosize=1;align=left;verticalAlign=top;spacingTop=-4;fontSize=16;fontFamily=Helvetica;" value= = =>
AWS Cloud Group
Use container=0 so services stay at parent="1" with absolute coordinates:
<mxCell id="aws-cloud" style="points=[[0,0],[0.25,0],[0.5,0],[0.75,0],[1,0],[1,0.25],[1,0.5],[1,0.75],[1,1],[0.75,1],[0.5,1],[0.25,1],[0,1],[0,0.75],[0,0.5],[0,0.25]];outlineConnect=0;gradientColor=none;html=1;whiteSpace=wrap;fontSize=12;fontStyle=0;shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_aws_cloud;strokeColor=#232F3E;fillColor=light-dark(#232F3E0D,#232F3E0D);fillStyle=auto;verticalAlign=top;align=left;spacingLeft=30;fontColor=#232F3E;dashed=0;container=0;pointerEvents=0;collapsible=0;recursiveResize=0" value="AWS Cloud" vertex="1" parent="1">
<mxGeometry x="260" y="150" width="1060" height="660" as="geometry" />
</mxCell>
Users Container (Outside AWS Cloud)
<mxCell id="users-container" style="fillColor=#f5f5f5;strokeColor=light-dark(#666666,#D4D4D4);rounded=1;whiteSpace=wrap;html=1;verticalAlign=top;fontStyle=1;fontSize=12;fontColor=#333333;fontFamily=Helvetica;container=1;collapsible=0;shadow=1;strokeWidth=1;" value="Users" vertex="1" parent="1">
<mxGeometry x="50" y="300" width="130" height="170" as="geometry" />
</mxCell>
<mxCell id="users-icon" style="sketch=0;points=[[0,0,0],[0.25,0,0],[0.5,0,0],[0.75,0,0],[1,0,0],[0,1,0],[0.25,1,0],[0.5,1,0],[0.75,1,0],[1,1,0],[0,0.25,0],[0,0.5,0],[0,0.75,0],[1,0.25,0],[1,0.5,0],[1,0.75,0]];outlineConnect=0;fontColor=#232F3E;fillColor=#232F3D;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.users;fontFamily=Helvetica;" value="" vertex="1" parent="users-container">
<mxGeometry x="41" y="30" width="48" height="48" as="geometry" />
Service Container (120x120 with 48x48 Icon)
Container value = category label (NOT service name). Icon value = service name.
<mxCell id="lambda-ctr" style="fillColor={TINT};strokeColor={STROKE};rounded=1;whiteSpace=wrap;html=1;verticalAlign=top;fontStyle=1;fontSize=12;fontColor={STROKE};fontFamily=Helvetica;container=1;collapsible=0;shadow=1;strokeWidth=1.5;" value="{CATEGORY}" vertex="1" parent="1">
<mxGeometry x="500" y="300" width="120" height="120" as="geometry" />
</mxCell>
<mxCell id="lambda-icon" style="sketch=0;points=[[0,0,0],[0.25,0,0],[0.5,0,0],[0.75,0,0],[1,0,0],[0,1,0],[0.25,1,0],[0.5,1,0],[0.75,1,0],[1,1,0],[0,0.25,0],[0,0.5,0],[0,0.75,0],[1,0.25,0],[1,0.5,0],[1,0.75,0]];outlineConnect=0;fontColor=#232F3E;fillColor={ICON_FILL};strokeColor=#ffffff;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=10;fontStyle=0;aspect=fixed;shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.{SHAPE};fontFamily=Helvetica;shadow=1;" value="Service Name<div><i>detail</i></div>" vertex="1" parent="lambda-ctr">
<mxGeometry x="36" = = = = />
Service Category Colors
| Category | fillColor (tint) | strokeColor | Icon fillColor |
|---|
| Compute | #FFF2E8 | #ED7100 | #ED7100 |
| Database | #F5E6F7 | #C925D1 | #C925D1 |
| Analytics / Networking | #EDE7F6 | #8C4FFF | #8C4FFF |
| Storage | #E8F5E9 | #3F8624 | #3F8624 |
| App Integration | #FCE4EC | #E7157B | #E7157B |
| AI / ML | #E0F2F1 | #01A88D | #01A88D |
| Security | #FFEBEE | #DD344C | #DD344C |
| General / Auxiliary | #F5F5F5 | #666666 | #666666 |
AWS Service Icon Names (mxgraph.aws4.*)
Compute: lambda, ec2, fargate, elastic_beanstalk, app_runner, batch
Database: dynamodb, rds, aurora, elasticache, neptune
Storage: s3, glacier, elastic_file_system, elastic_block_store
Analytics: kinesis, athena, glue, emr, redshift, quicksight
App Integration: sqs, sns, eventbridge, step_functions, apigateway, appsync
Security: cognito, identity_and_access_management, secrets_manager, waf
Networking: route_53, cloudfront, vpc, transit_gateway
Containers: ecs, eks, ecr
AI/ML: sagemaker, bedrock, rekognition_2, comprehend, textract
Management: cloudwatch_2, cloudtrail, systems_manager, cloudformation
Group Shapes
| Group | grIcon | strokeColor |
|---|
| AWS Cloud | mxgraph.aws4.group_aws_cloud | #232F3E |
| Region | mxgraph.aws4.group_region | #00A4A6 |
| VPC | mxgraph.aws4.group_vpc2 | #8C4FFF |
| Public Subnet | mxgraph.aws4.group_public_subnet | #248814 |
| Private Subnet | mxgraph.aws4.group_private_subnet | #147EBA |
| Security Group | mxgraph.aws4.group_security_group | #DD344C |
CRITICAL: Regions MUST use container=0. Services placed at parent="1" with absolute coordinates.
Edge Styles
Standard (synchronous):
<mxCell id="edge-1" style="edgeStyle=orthogonalEdgeStyle;html=1;endArrow=block;elbow=vertical;startArrow=none;endFill=1;strokeColor=#545B64;rounded=0;" edge="1" parent="1" source="icon-a" target="icon-b">
Dashed (async / optional):
<mxCell id="edge-2" style="edgeStyle=orthogonalEdgeStyle;html=1;endArrow=block;elbow=vertical;startArrow=none;endFill=1;strokeColor=#545B64;rounded=0;dashed=1;" edge="1" ...>
Open arrow (data flow):
<mxCell id="edge-3" style="edgeStyle=orthogonalEdgeStyle;html=1;endArrow=open;elbow=vertical;startArrow=none;endFill=0;strokeColor=#545B64;rounded=0;" edge="1" ...>
Edge label (separate child cell):
<mxCell id="edge-1-label" value="API call" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];fontSize=11;fontFamily=Helvetica;labelBackgroundColor=none;" connectable="0" vertex="1" parent="edge-1">
<mxGeometry relative="1" x="-0.3" y="0" as="geometry"><mxPoint as="offset" /></mxGeometry>
</mxCell>
Avoiding Crossing Lines
When multiple edges leave the same source:
- Use different exit points: Assign distinct
exitX/exitY values as XML attributes on each edge
- Route around services: For edges that need to pass other services, use explicit waypoints:
<mxGeometry relative="1" as="geometry">
<Array as="points">
<mxPoint x="620" y="184" />
<mxPoint x="840" y="184" />
</Array>
</mxGeometry>
- Separate lanes: Query edges (solid) and registration/async edges (dashed) should exit at different Y positions and use separate horizontal/vertical lanes
- Edges on opposite sides: If possible, route output edges from the left side (
exitX=0) and data edges from the right side (exitX=1)
Step Badges (28x28)
<mxCell id="step-N" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#007CBD;strokeColor=default;fontColor=#FFFFFF;fontStyle=1;fontSize=16;fontFamily=Helvetica;shadow=1;glass=0;strokeWidth=2;align=center;verticalAlign=middle;labelBackgroundColor=none;" value="N" vertex="1" parent="1">
<mxGeometry x="X" y="Y" width="28" height="28" as="geometry" />
</mxCell>
Place near arrow source end, offset 20px, minimum 10px clearance from icons.
Legend Panel
Position at x = diagram_right_edge + 40. Include:
- Step descriptions (badge 40x38 + text block)
- Connection types section (solid, dashed, open-arrow with labels)
- Background:
fillColor=light-dark(#EDF3FF,#305363);strokeColor=#6c8ebf
Font Standards
| Element | Size | Style |
|---|
| Title | 30px | bold |
| Subtitle | 16px | regular |
| Group labels | 12px | regular |
| Container labels | 12px | bold |
| Service labels | 10px | regular |
| Edge labels | 11px | regular |
| Step badges | 16px (diagram) / 22px (legend) | bold |
| Legend title | 16px | bold |
| Legend text | 14px | regular |
All fonts: fontFamily=Helvetica
Critical Rules
- Service icons connect to edges, NOT containers - always use the icon ID as edge source/target
- Container value = category (e.g., "Compute"), Icon value = service name (e.g., "AWS Lambda")
- No emojis in any element values
- All positions aligned to grid multiples of 10
- Edge labels always have
connectable="0" and labelBackgroundColor=none
- Use
light-dark() for adaptive colors; add fillStyle=auto
- Run
validate_drawio.py before delivery - all 6 checks must pass
