aws-arch-drawio

AWS Architecture Diagram Plugin — Draw.io

Equip AI coding agents with the skill to generate professional Draw.io architecture diagrams with official AWS icons from AWS infrastructure-as-code. Works with Claude Code, Kiro, Cursor, Windsurf, and any MCP-compatible editor.

Note: Always review generated diagrams before using them in production documentation. AI can occasionally misclassify resources or miss relationships.

---

What This Plugin Does

The AWS Arch Draw.io plugin gives your AI agent a /arch-drawio command that scans your IaC codebase and produces a professional Draw.io diagram with official AWS icons (mxgraph.aws4.*), tier-based layout, layer management, and support for PNG/SVG export.

Agent Skill Triggers

The skill activates when you ask questions like:

Trigger Phrase	What It Does
"/arch-drawio"	Full scan → parse → diagram pipeline
"Generate a Draw.io architecture diagram"	Scans IaC, opens diagram in Draw.io editor
"Draw my AWS infrastructure with official icons"	Places mxgraph.aws4.* shapes with tier layout
"Show me the service relationships in this project"	Infers connections from IAM, env vars, event sources
"Create an architecture diagram with VPC boundaries"	Adds region/VPC/subnet/AZ boundary containers
"Export my architecture to PNG"	Generates diagram and provides export instructions

---

Pipeline

When you run /arch-drawio, the plugin follows this pipeline:

1. Scan & Detect — Walks the project looking for IaC files (CloudFormation, SAM, CDK, Terraform, Serverless Framework) and application code (AWS SDK usage)
2. Parse Resources — Extracts AWS resource definitions and builds a resource inventory with service name, tier, and mxgraph.aws4.* shape name
3. Infer Relationships — Analyses IAM policies, environment variables, event source mappings, API Gateway integrations, S3 notifications, Step Functions states, and SNS subscriptions
4. Detect Boundaries — Groups resources into Account → Region → VPC → Subnet → AZ containers; ECS services under clusters
5. Generate Diagram — Calls drawio-mcp-server tool sequence: creates layers, places boundary containers, places AWS icon nodes with explicit coordinates, draws edges
6. Report — Provides diagram location (http://localhost:3000/), resource count, layer summary, and export instructions

---

Supported IaC Frameworks

Framework	Detection
AWS CloudFormation	AWSTemplateFormatVersion: "2010-09-09" in .yaml/.json
AWS SAM	Transform: AWS::Serverless-2016-10-31
AWS CDK (TypeScript)	cdk.json at root or aws-cdk-lib imports in bin/*.ts, lib/*.ts
Terraform	*.tf files with resource "aws_*" blocks
Serverless Framework	serverless.yml / serverless.yaml
Application Code	*.ts, *.py, *.java scanned for AWS SDK client instantiation

---

Relationship Inference

The skill infers service connections from:

Source	What It Detects
IAM policies	dynamodb:PutItem → Lambda writes to DynamoDB
Environment variables	TABLE_NAME: !Ref OrdersTable → Lambda connects to table
Event source mappings	SQS/Kinesis/DynamoDB Stream → Lambda triggers
API Gateway integrations	API GW → Lambda/HTTP proxy routing
S3 notifications	NotificationConfiguration → Lambda/SQS/SNS triggers
SNS subscriptions	SNS → SQS/Lambda/HTTP subscriptions
Step Functions	State machine definition → Lambda/ECS invocations
AWS SDK usage	new DynamoDBClient(), boto3.client('s3') → inferred data flows

---

Draw.io Backends

Backend	Flag	Description
lgazo (default)	--backend lgazo	Live editor via drawio-mcp-server at localhost:3000
sujimoshi	--backend sujimoshi	File-based output, no running editor required
official	--backend official	One-shot mxGraph XML via @drawio/mcp

---

Style Modes

Mode	Description
--style minimal	Only edge + compute + data tiers. No boundaries or monitoring. Clean for presentations.
--style standard	All tiers. VPC/subnet boundaries. Inferred edges as dashed grey. 3 layers. (default)
--style detailed	AZ boundaries, security group nodes, CloudWatch alarms, IAM roles, ARN metadata on all nodes.

---

Plugin Components

Agent Skill

Component	Description
skills/arch-drawio/SKILL.md	Core skill — pipeline stages, AWS shape map, style modes, layout guide
skills/arch-drawio/references/aws-shape-map.md	Complete mxgraph.aws4.* shape name reference for 50+ AWS services
skills/arch-drawio/references/drawio-style-guide.md	Boundary styles, edge styles, tier coordinates, layer management
skills/arch-drawio/references/iac-parsing-patterns.md	Parsing reference for CloudFormation, SAM, CDK, Terraform, Serverless

MCP Servers