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:

1. architecture.drawio

   - Editable draw.io XML file

2. architecture.png

   - Exported PNG image (if draw.io CLI is installed)
3. 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

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

# Install draw.io CLI (one-time)
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

# Export
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:

mxgraph.aws4.group_aws_cloud

orthogonalEdgeStyle

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" />
        <!-- All content here -->
      </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="One-line description" vertex="1" parent="title-group">
  <mxGeometry x="5" y="40" width="800" height="25" as="geometry" />
</mxCell>
<mxCell id="title-sep" style="line;strokeWidth=2;html=1;strokeColor=#FF9900;fontFamily=Helvetica;" value="" vertex="1" parent="title-group">
  <mxGeometry x="5" y="70" width="1190" height="10" as="geometry" />
</mxCell>

AWS Cloud Group

Use

container=0

parent="1"

<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" />
</mxCell>

Service Container (120x120 with 48x48 Icon)

Container

value

value

<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&lt;div&gt;&lt;i&gt;detail&lt;/i&gt;&lt;/div&gt;" vertex="1" parent="lambda-ctr">
  <mxGeometry x="36" y="30" width="48" height="48" as="geometry" />
</mxCell>

Service Category Colors

#FFF2E8

#ED7100

#ED7100

#F5E6F7

#C925D1

#C925D1

#EDE7F6

#8C4FFF

#8C4FFF

#E8F5E9

#3F8624

#3F8624

#FCE4EC

#E7157B

#E7157B

#E0F2F1

#01A88D

#01A88D

#FFEBEE

#DD344C

#DD344C

#F5F5F5

#666666

#666666

AWS Service Icon Names (mxgraph.aws4.*)

Compute:

lambda

ec2

fargate

elastic_beanstalk

app_runner

batch

dynamodb

rds

aurora

elasticache

neptune

s3

glacier

elastic_file_system

elastic_block_store

kinesis

athena

glue

emr

redshift

quicksight

sqs

sns

eventbridge

step_functions

apigateway

appsync

cognito

identity_and_access_management

secrets_manager

waf

route_53

cloudfront

vpc

transit_gateway

ecs

eks

ecr

sagemaker

bedrock

rekognition_2

comprehend

textract

cloudwatch_2

cloudtrail

systems_manager

cloudformation

Group Shapes

mxgraph.aws4.group_aws_cloud

#232F3E

mxgraph.aws4.group_region

#00A4A6

mxgraph.aws4.group_vpc2

#8C4FFF

mxgraph.aws4.group_public_subnet

#248814

mxgraph.aws4.group_private_subnet

#147EBA

mxgraph.aws4.group_security_group

#DD344C

CRITICAL: Regions MUST use

container=0

parent="1"

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:

1. Use different exit points: Assign distinct

   exitX

   /

   exitY

   values as XML attributes on each edge
2. 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>
   

3. Separate lanes: Query edges (solid) and registration/async edges (dashed) should exit at different Y positions and use separate horizontal/vertical lanes
4. 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

• 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

All fonts:

fontFamily=Helvetica

Critical Rules

1. Service icons connect to edges, NOT containers - always use the icon ID as edge source/target
2. Container value = category (e.g., "Compute"), Icon value = service name (e.g., "AWS Lambda")
3. No emojis in any element values
4. All positions aligned to grid multiples of 10
5. Edge labels always have

   connectable="0"

   and

   labelBackgroundColor=none

6. Use

   light-dark()

   for adaptive colors; add

   fillStyle=auto

7. Run

   validate_drawio.py

   before delivery - all 6 checks must pass