AWS DrawIO Diagram Generator

Generates professional DrawIO XML diagrams for Amazon Web Services architectures.

Capabilities

1. Extract - Analyze existing DrawIO XML files to identify AWS shapes, connections, and structure
2. Identify - Recognize AWS service icons from architecture diagram images
3. Generate - Create valid DrawIO XML from images or text descriptions
4. Convert - Transform AWS architecture diagrams into editable DrawIO format

Quick Reference

AWS Shape Patterns

There are two icon types. Use service icons when labeling the AWS service itself, and instance icons when representing a specific resource.

Service icon (colored square background) — for labeling the service:

shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.{shape_name}

Instance icon (bare icon, no background) — for specific resources:

shape=mxgraph.aws4.{shape_name};fillColor={category_color}

CRITICAL: Always keep

fillColor

set to the category color. Without it the icon renders white/invisible. The only difference from a service icon is the absence of the

resourceIcon

background square — never remove

fillColor

when using an instance icon.

CRITICAL: Underscore-Separated Names

Multi-word AWS shape names use UNDERSCORES in style properties!

• step_functions

  (correct)

• api_gateway

  (correct)

• kinesis_data_streams

  (correct)

• step functions

  (WRONG - will not render)

• api gateway

  (WRONG - will not render)

The aws4.xml stencil defines names with spaces, but DrawIO's style parser requires underscores.

Always look up exact names in

assets/aws-icons.json

Common AWS Services

shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.lambda

shape=mxgraph.aws4.lambda

shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.s3

shape=mxgraph.aws4.s3

shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.ec2

shape=mxgraph.aws4.ec2

shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.dynamodb

shape=mxgraph.aws4.dynamodb

shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.api_gateway

shape=mxgraph.aws4.api_gateway

shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.sqs

shape=mxgraph.aws4.sqs

shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.sns

shape=mxgraph.aws4.sns

shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.step_functions

shape=mxgraph.aws4.step_functions

shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.ecs

shape=mxgraph.aws4.ecs

shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.rds

shape=mxgraph.aws4.rds

AWS Container Types

Task 1: Analyze a DrawIO File

Use this workflow to extract and document all components from an existing DrawIO file.

Steps

1. Read the file - Load the

   .drawio

   XML file
2. Parse structure - Extract all

   <mxCell>

   elements
3. Identify shapes - Find cells with

   vertex="1"

4. Identify connections - Find cells with

   edge="1"

5. Extract styles - Parse style strings for each element
6. Map hierarchy - Build container/child relationships using

   parent

   attribute
7. Generate report - Output findings in structured format

Input

• Path to

  .drawio

  file

Output

Generate a Markdown report with:

# DrawIO Analysis Report

## Summary
- Total shapes: X
- Total connections: Y
- Containers: Z

## Shape Inventory

| ID | Label | Type | Position | Parent |
|----|-------|------|----------|--------|
| abc | Lambda | mxgraph.aws4.lambda | (100,200) | vpc1 |

## Connection Matrix

| From | To | Label | Type |
|------|-----|-------|------|
| Lambda | DynamoDB | API | solid |

## Container Hierarchy

- VPC (vpc1)
  - Lambda (lambda1)
  - Lambda (lambda2)
  - DynamoDB (db1)

## Style Analysis

### Unique Shapes Found
- mxgraph.aws4.lambda (4 instances)
- mxgraph.aws4.dynamodb (2 instances)

Task 2: Convert Image to DrawIO

Use this workflow to recreate an AWS architecture diagram from an image.

Steps

1. Analyze image - Identify all visual elements:

   • AWS service icons (shape, color, label)
   • Containers/boundaries (color, border style)
   • Connections (solid, dashed, arrows)
   • Labels and text

2. Map to library - For each identified element:

   • Look up in

     assets/aws-icons.json

     by visual signature or label
   • Match containers to

     assets/aws-containers.json

   • CRITICAL: Verify underscore-separated names for multi-word services (e.g.,

     step_functions

     , not

     step functions

     )
   • Note any unrecognized elements

3. Estimate layout - Determine positions:

   • Identify container boundaries first
   • Place icons within containers
   • Estimate x,y coordinates and dimensions
   • Standard icon size: 64x64 pixels

4. Generate XML - Build the DrawIO structure:

   • Start with base template from

     assets/templates/drawio-base.xml

   • Add containers first (they become parents)
   • Add service icons with correct parent references
   • Add connections between shapes

5. Create confidence report - Document accuracy:

   • List all identified components
   • Note any uncertain matches
   • Flag potential issues

Input

• AWS architecture diagram image (PNG/JPG)

Output

1. Valid

   .drawio

   XML file
2. Confidence report (Markdown)

Confidence Report Format

# Conversion Confidence Report

## Overall Confidence: 85%

## Identified Components

### High Confidence (>90%)
- Lambda x4 - Clear icon match
- DynamoDB x2 - Clear icon match
- VPC container - Purple border, correct label

### Medium Confidence (70-90%)
- Step Functions - Icon similar, label confirms (using `step_functions` with underscores)

### Low Confidence (<70%)
- Unknown icon at position (300, 400) - Mapped to generic service

## Connection Accuracy
- 12/14 connections clearly visible
- 2 connections inferred from layout

## Notes
- VPC subnet grouping identified
- Bidirectional arrows on 3 connections

Task 3: Create DrawIO from Description

Use this workflow to generate a new AWS diagram from text specifications.

Steps

1. Parse requirements - Extract from description:

   • Required AWS services
   • Container/grouping needs
   • Connection requirements
   • Layout preferences

2. Select components - From libraries:

   • Look up services in

     assets/aws-icons.json

   • Choose containers from

     assets/aws-containers.json

   • Choose icon type: Use service icons (with background) for generic service labels, instance icons (no background) for specific resources (see Quick Reference)
   • VERIFY: Underscore-separated names for multi-word services in style strings
   • Select connection styles

3. Plan layout - Design the arrangement:

   • Determine canvas size
   • Position containers first
   • Arrange services logically (left-to-right data flow, top-to-bottom hierarchy)
   • Standard spacing: 120px between 64x64 icons

4. Generate XML - Build the diagram:

   • Use

     assets/templates/drawio-base.xml

     as starting point
   • Add elements in order: containers, services, connections
   • Assign unique IDs to all elements

5. Validate - Check the output:

   • All requested components present
   • Connections reference valid IDs
   • Layout is logical and readable

Input

• Text description of desired AWS architecture

Output

• Valid

  .drawio

  XML file

Example Input

Create an AWS serverless architecture with:
- VPC container
- API Gateway triggering Lambda
- Lambda connecting to DynamoDB and S3
- Step Functions orchestrating the workflow

Example Output Structure

<mxfile ...>
  <diagram name="AWS Architecture">
    <mxGraphModel ...>
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
        <!-- VPC Container -->
        <mxCell id="vpc" value="VPC" style="..." vertex="1" parent="1">
          <mxGeometry x="50" y="50" width="700" height="400" />
        </mxCell>
        <!-- API Gateway -->
        <mxCell id="api_gateway" value="API Gateway" style="...resIcon=mxgraph.aws4.api_gateway" vertex="1" parent="vpc">
          <mxGeometry x="50" y="100" width="64" height="64" />
        </mxCell>
        <!-- More shapes... -->
        <!-- Connections -->
        <mxCell id="conn_api_gateway_to_lambda" edge="1" source="api_gateway" target="lambda" style="..." />
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

Shape Library Reference

Looking Up an AWS Service

1. Open

   assets/aws-icons.json

2. Search by

   service_name

   or

   recognition_keywords

3. Use the

   drawio_shape.full_style

   for complete styling
4. Or construct style using:

   shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.{shape_name}

Service Coverage:

• 264 AWS services across 24 categories
• 96.6% validated against mxgraph.aws4 library (255/264 services)
• 9 unvalidated services (deprecated or newer than aws4.xml stencil) — see

  references/ICON-COMPATIBILITY.md

  for the list. For these, use a visually similar validated service icon or a generic shape.

Key AWS Specifications

• Icon size: 64x64 pixels
• Font color: #232F3E universally (dark gray)
• Fill color varies by category (not per-service)
• Arrow style: open arrow, 2pt stroke,

  #232F3E

Look up the exact

category

fillColor

full_style

assets/aws-icons.json

Visual Best Practices

See references/DIAGRAM-BEST-PRACTICES.md for full guidelines. Key rules:

• Connection labels — always add:

  labelBackgroundColor=#FFFFFF;fontSize=10;fontColor=#232F3E;

• strokeWidth — use

  1

  for most connections,

  2

  only for primary data paths (max 1–3 per diagram)
• Consolidate connections when 3+ cross the same corridor into a single labeled edge

XML Structure Quick Reference

For complete XML examples and detailed structure, see references/xml-examples.md.

The key building blocks:

• Shape:

  <mxCell id="api_gateway" value="Label" style="..." vertex="1" parent="1">

  with

  <mxGeometry>

• Connection:

  <mxCell id="conn_api_gateway_to_lambda" edge="1" source="api_gateway" target="lambda" style="...">

• Container: Shape with

  container=1

  in style; children set

  parent

  to container ID
• Root cells: Every diagram needs

  <mxCell id="0"/>

  and

  <mxCell id="1" parent="0"/>

ID Naming Rules

• Full service names —

  api_gateway

  , not

  apigw

  ;

  step_functions

  , not

  stepfn

• Role suffixes for duplicates —

  lambda_api_handler

  ,

  lambda_processor

  , not

  lambda1

  ,

  lambda2

• Connection IDs —

  conn_{source}_to_{target}

  using full IDs

See references/DIAGRAM-BEST-PRACTICES.md for complete ID naming convention.

For XML parsing and extraction techniques, see references/xml-parser-guide.md.

Troubleshooting

Icon Not Displaying

• CRITICAL: Verify multi-word shape names use UNDERSCORES:

  step_functions

  , NOT

  step functions

• For service icons: verify both

  shape=mxgraph.aws4.resourceIcon

  AND

  resIcon=mxgraph.aws4.{name}

  are present
• For instance icons: verify

  shape=mxgraph.aws4.{name}

  is used directly (no

  resourceIcon

  wrapper)
• NEVER use

  productIcon

  /

  prIcon

  — always use

  resourceIcon

  /

  resIcon

  for service icons
• Check assets/aws-icons.json for exact shape name
• Ensure

  vertex="1"

  is present
• Check that

  <mxGeometry>

  has valid width/height (64x64)

Wrong Icon Type (Background vs No Background)

See the Quick Reference section for the full definition of each icon type. In summary:

• Service icon:

  shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.{name}

  — labels the AWS service itself
• Instance icon:

  shape=mxgraph.aws4.{name};fillColor={category_color}

  — represents a specific resource;

  fillColor

  is required or the icon renders white

Connection Not Rendering

• Verify source and target IDs exist
• Ensure

  edge="1"

  is set
• Check that source/target shapes are vertices

Shapes Not Inside Container

• Set child's

  parent

  attribute to container's ID
• Ensure container has

  container=1

  in style
• Position child coordinates relative to container (not absolute)

Label Not Showing

• Check

  value

  attribute is set
• Verify

  fontSize

  is reasonable (12-14 for AWS)
• Ensure

  fontColor=#232F3E

  is set

File Won't Open in DrawIO

• Validate XML structure (proper closing tags)
• Ensure

  id="0"

  and

  id="1"

  root cells exist
• Check for special characters in labels (use

  


  for newlines)

Desktop Integration

After generating a

.drawio

1. Validate:

   python scripts/validate-drawio.py output.drawio --verbose

2. Analyze:

   python scripts/analyze-existing.py output.drawio --markdown

3. Validate Icons:

   python scripts/validate-aws-icons.py

4. Export PNG:

   ./scripts/export-diagram.sh output.drawio png

5. Open in DrawIO:

   ./scripts/open-diagram.sh output.drawio

Requires DrawIO Desktop. Install on macOS:

brew install drawio

Files in This Skill

SKILL.md

assets/aws-icons.json

assets/aws-containers.json

assets/templates/drawio-base.xml

assets/templates/node-template.xml

assets/templates/connection-template.xml

references/ICON-COMPATIBILITY.md

references/DIAGRAM-BEST-PRACTICES.md

references/xml-parser-guide.md

references/xml-examples.md

references/coordinate-system.md

references/style-guide.md

scripts/validate-drawio.py

scripts/validate-aws-icons.py

scripts/fix-aws-icons.py

scripts/fix-drawio-icons.py

scripts/extract-shape-names.py

scripts/analyze-existing.py

scripts/export-diagram.sh

scripts/open-diagram.sh