aws-infra-drawio

日本語版はこちら

A Claude Code plugin that turns Terraform into AWS architecture diagrams (.drawio). It wraps the official draw.io MCP server (@drawio/mcp) and keeps your diagram data on your machine.

What it does

Diagram information is split into three layers, each owned by someone different.

| Layer | File | Owner | |---|---|---| | Structure | structure.yaml | Humans review it. The AI extracts it from IaC and proposes changes | | Conventions | conventions.md / layout.yaml | Humans decide. The AI appends decisions as they accumulate | | Appearance and coordinates | *.drawio | Generated by scripts |

The AI never draws coordinates, so the same structure.yaml always produces the same .drawio. Diffs in the diagram match diffs in the infrastructure, which makes them reviewable in a PR.

This split follows the design in a ZOZO article (Japanese). That article renders with D2; this one renders with draw.io, using the official AWS icons.

Setup

If you only need it occasionally, run it with npx instead of installing it.

npx aws-infra-drawio claude   # starts Claude Code with this plugin loaded

The MCP server is registered as drawio and the /aws-infra-drawio:aws-diagram skill becomes available. Close the session and nothing is left behind but the npx cache.

The individual commands are available through npx too.

npx aws-infra-drawio validate <dir>/structure.yaml
npx aws-infra-drawio render   <dir>/structure.yaml --route
npx aws-infra-drawio check    <dir>/structure.yaml
npx aws-infra-drawio export   <dir>/<view>.drawio png 1.5
npx aws-infra-drawio help

For regular use

To keep the plugin installed, add this repository as a marketplace.

/plugin marketplace add tanabe1478/aws-infra-drawio-integration-plugin
/plugin install aws-infra-drawio@aws-infra-drawio

The catalog (.claude-plugin/marketplace.json) lives in this repository, but the plugin itself is installed from npm. Using the repository directly as the plugin source would leave the dependencies (@drawio/mcp, yaml) uninstalled, requiring a separate setup.sh run.

For development

git clone https://github.com/tanabe1478/aws-infra-drawio-integration-plugin.git
cd aws-infra-drawio-integration-plugin
bash scripts/setup.sh          # install dependencies and place the shape index
claude --plugin-dir .

On staying local

The only network access is fetching the package itself (npx / npm install). The shape index ships inside the package, so nothing else is downloaded unless you clone the repository and run setup.sh. After that:

| Feature | Network | |---|---| | Generating .drawio | None | | PNG / SVG export | None (runs drawio-desktop or a Docker image locally) | | search_shapes (icon search) | None (setup.sh places the index locally) | | open_drawio_xml (open in an editor) | Whatever DRAWIO_BASE_URL points at. Defaults to http://localhost:8080/ | | --route (path optimization) | A conditional GET to a CDN on first use, falling back to the bundled copy |

To run the editor locally:

bash scripts/setup.sh --serve   # start jgraph/drawio on localhost:8080
bash scripts/setup.sh --status  # check the current state

Diagram data travels in the URL #fragment, so it is never sent to the server even when DRAWIO_BASE_URL points somewhere external. Self-host if you want to rule out external access entirely.

Usage

Ask Claude Code for a diagram.

/aws-infra-drawio:aws-diagram Draw the API architecture from the Terraform under infra/

The skill reads the IaC, proposes a structure.yaml, and generates the .drawio and PNG once you have reviewed it.

To drive it by hand:

node scripts/validate-structure.mjs <dir>/structure.yaml   # validate the structure
node scripts/render-drawio.mjs      <dir>/structure.yaml --route
node scripts/check-geometry.mjs     <dir>/structure.yaml   # check for overflow and overlap
bash scripts/export-drawio.sh       <dir>/<view>.drawio png 1.5

Example

examples/serverless-api/ holds Terraform, the structure.yaml derived from it, and the generated output.

How it works

| File | Role | |---|---| | skills/aws-diagram/ | The Claude Code skill: workflow and conventions | | scripts/lib/layout.mjs | Coordinate assignment. Columns = flow, rows = containment | | scripts/lib/containers.mjs | Definitions for AWS Cloud / Region / VPC / subnet frames | | scripts/shape-map.json | CloudFormation type to AWS icon style, generated from the draw.io shape index | | scripts/lib/route.mjs | Bakes in obstacle-avoiding routes using the libavoid bundled with @drawio/mcp | | vendor/search-index.json | The draw.io shape index (roughly 10,000 entries) |

Icon names (mxgraph.aws4.*) are never written by hand; npm run gen:shape-map resolves them from the official index. For resource types that aren't mapped yet, look them up with the MCP search_shapes tool and paste the result into style: in structure.yaml.

Checks

bash scripts/selftest.sh

Verifies the shape map, the example structures, geometric soundness, and rendering determinism.

Limitations

• Layout follows simple rules: columns for flow, rows for containment. Star-shaped topologies (many resources hanging off one Lambda) stretch vertically. Pin columns with column to adjust
• Edge labels sit near the start of the line. On long detours they can still land in hard-to-read positions
• The expected input is Terraform. CDK and CloudFormation work once you add their mappings to structure-spec.md