---
name: a5c-ai/generating-aws-diagrams
source: https://app.decimal.ai/s/a5c-ai-generating-aws-diagrams@1/SKILL.md
source_sha256: d6dc82540864
---

# 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.

| Scenario | Icon Type | Label Example |
|----------|-----------|---------------|
| The AWS service itself | **Service** (with background) | "AWS Lambda", "Amazon RDS" |
| A specific resource/instance | **Instance** (no background) | "Order Processor", "Users Table" |
| Multiple instances of same service | **Instance** (no background) | "ECS Task 1", "ECS Task 2" |

### 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` before using.**

### Common AWS Services

| Service | Service Icon (with background) | Instance Icon (no background) |
|---------|-------------------------------|-------------------------------|
| Lambda | `shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.lambda` | `shape=mxgraph.aws4.lambda` |
| Amazon S3 | `shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.s3` | `shape=mxgraph.aws4.s3` |
| Amazon EC2 | `shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.ec2` | `shape=mxgraph.aws4.ec2` |
| DynamoDB | `shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.dynamodb` | `shape=mxgraph.aws4.dynamodb` |
| API Gateway | `shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.api_gateway` | `shape=mxgraph.aws4.api_gateway` |
| Amazon SQS | `shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.sqs` | `shape=mxgraph.aws4.sqs` |
| Amazon SNS | `shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.sns` | `shape=mxgraph.aws4.sns` |
| Step Functions | `shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.step_functions` | `shape=mxgraph.aws4.step_functions` |
| Amazon ECS | `shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.ecs` | `shape=mxgraph.aws4.ecs` |
| Amazon RDS | `shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.rds` | `shape=mxgraph.aws4.rds` |

### AWS Container Types

| Container | Use Case |
|-----------|----------|
| aws_cloud | Top-level AWS Cloud boundary |
| aws_region | Region grouping |
| aws_availability_zone | AZ grouping |
| aws_vpc | VPC boundary |
| aws_public_subnet | Public subnet |
| aws_private_subnet | Private subnet |
| aws_security_group | Security group boundary |
| aws_auto_scaling_group | Auto scaling group |
| aws_account | AWS Account boundary |
| aws_corporate_datacenter | Corporate datacenter |
| aws_generic_group | Generic grouping |
| aws_step_functions_workflow | Step Functions workflow |
| aws_elastic_beanstalk_container | Elastic Beanstalk app |

---

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

```markdown
# 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

```markdown
# 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

```xml
<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`, and `full_style` for any service in `assets/aws-icons.json`. All 24 categories with colors are listed there.

---

## Visual Best Practices

See [references/DIAGRAM-BEST-PRACTICES.md](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](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](references/DIAGRAM-BEST-PRACTICES.md) for complete ID naming convention.

For XML parsing and extraction techniques, see [references/xml-parser-guide.md](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](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 `&#xa;` for newlines)

---

## Desktop Integration

After generating a `.drawio` file, you can validate and preview it:

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

| File | Purpose |
|------|---------|
| `SKILL.md` | This file - main instructions |
| **Assets** | |
| `assets/aws-icons.json` | AWS service icon database (264 services) |
| `assets/aws-containers.json` | AWS container/group and connection styles |
| `assets/templates/drawio-base.xml` | Base XML template |
| `assets/templates/node-template.xml` | Shape insertion template |
| `assets/templates/connection-template.xml` | Connection template |
| **References** | |
| `references/ICON-COMPATIBILITY.md` | Icon validation reference (255/264 validated) |
| `references/DIAGRAM-BEST-PRACTICES.md` | Visual design and layout guidelines |
| `references/xml-parser-guide.md` | Detailed XML parsing reference |
| `references/xml-examples.md` | Copy-paste XML examples |
| `references/coordinate-system.md` | Positioning and layout guide |
| `references/style-guide.md` | Style string reference |
| **Scripts** | |
| `scripts/validate-drawio.py` | Validate .drawio XML structure |
| `scripts/validate-aws-icons.py` | Validate AWS icon compatibility |
| `scripts/fix-aws-icons.py` | Auto-fix icon shape names |
| `scripts/fix-drawio-icons.py` | Bulk fix icon references in .drawio files |
| `scripts/extract-shape-names.py` | Extract available shapes from DrawIO stencil |
| `scripts/analyze-existing.py` | Extract shapes/connections from .drawio files |
| `scripts/export-diagram.sh` | Export to PNG/PDF via DrawIO Desktop CLI |
| `scripts/open-diagram.sh` | Open .drawio file in DrawIO Desktop |