mpuig-claude-cloud-diagrams

Claude Cloud Diagrams

Architecture diagrams aren't hard to make. They're impossible to maintain.

You spend hours lining up boxes in Miro. It looks great. Then someone merges a "quick fix," adds three SQS queues and a Lambda, and your diagram quietly becomes a historical document.

This project pays an AI to explore your AWS account and draw what it finds. Not a perfect map. A useful one.

How it works

Instead of a rigid parser that maps resource A to icon B, this uses an AI agent with two simple skills:

1. Discovery by exploration

The agent doesn't rely on a predefined list of what to look for. It runs AWS CLI describe commands, follows references, and looks for patterns.

If it finds an ALB, it looks for target groups. If it sees a queue named order-processor, it reasonably assumes it belongs to the order service.

It isn't checking a configuration file. It's reading the room.

2. Reasoning instead of rigid mapping

Once the agent has a snapshot of the environment, it writes Python code to generate the diagram.

Traditional tools mechanically map resources to shapes. Claude looks at the whole mess and asks: what's actually central here? Which services define the architecture, and which ones are supporting actors?

Two runs might produce slightly different layouts. That's not a bug. You're getting a perspective on the system, not a mathematical proof.

Installation

Option 1: Claude Code Plugin (Recommended)

Install directly from GitHub as a Claude Code plugin:

# Add the marketplace
/plugin marketplace add mpuig/claude-cloud-diagrams

# Install the plugin
/plugin install aws-diagrams@mpuig/claude-cloud-diagrams

Then use in any project (see Usage section below for tips).

Option 2: Clone and use locally

Clone this repository and run Claude Code from within:

git clone https://github.com/mpuig/claude-cloud-diagrams.git
cd claude-cloud-diagrams
claude

Usage

Tip: If using AWS SSO, log in before starting Claude Code for a smoother experience:

aws sso login --profile myprofile

Then from within Claude Code:

You: discover my AWS infrastructure using profile myprofile and region eu-west-1
Claude: [explores your account, creates aws_infrastructure.json]

You: generate AWS architecture diagram
Claude: [creates diagram files]

Specifying the profile and region upfront works best—it avoids extra back-and-forth.

The trade-offs (and why I'm okay with them)

"It's not 100% accurate."

Correct. It's about 90% accurate and takes thirty seconds. A hand-drawn diagram is 100% accurate for a version of the system that existed three weeks ago.

"Isn't this expensive?"

It costs API credits to have an LLM explore your account. A local script is free. But the script requires constant maintenance as AWS adds services. You're paying to avoid the ongoing labor of keeping the tool up to date.

"What about hallucinations?"

An AI can misinterpret a relationship. So can a human. The difference is the AI logs its reasoning, explaining why it thinks a Lambda connects to a specific database. The uncertainty is visible.

Output

The generator creates four views of your infrastructure:

Diagram	Purpose
aws_architecture.png	The big picture: compute, databases, storage, connections
aws_security.png	WAF, Cognito, KMS, traffic through security layers
aws_network.png	VPC topology: subnets, NAT gateways, VPC endpoints
aws_data_flow.png	How data moves through the system

Example

The example/ directory contains sample output from a fictional e-commerce platform, so you can see what the diagrams look like without connecting your own AWS account.

Prerequisites

1. Graphviz (for PNG/SVG output):

   # macOS
   brew install graphviz
   
   # Ubuntu/Debian
   sudo apt-get install graphviz
   

2. Python dependencies:

   uv sync
   

3. AWS CLI configured and authenticated:

   # For SSO (recommended)
   aws sso login --profile <profile>
   
   # Or traditional credentials
   aws configure
   

Alternative: Python scripts

For automation or CI/CD, standalone scripts are available:

# Discover infrastructure
uv run discover.py --profile myprofile --region eu-west-1

# Generate diagrams
uv run generate_diagram.py all --format png

API configuration

Claude Code supports two backends:

Anthropic API:

export ANTHROPIC_API_KEY=sk-ant-...

AWS Bedrock:

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=eu-west-1

---

These diagrams aren't audit records or sources of truth. They're for onboarding, sanity checks, and rediscovering parts of the system everyone forgot existed.

Cloud infrastructure isn't static. It's a living, expensive mess. Trying to freeze it into a perfect diagram is a comforting illusion.