Varsha Das for AWS

Posted on May 26

I Stopped Dragging Boxes in Draw.io. Here's What I Do Instead.

#aws #architecture #mcp #productivity

If you're a Java developer, solutions architect, or anyone who's ever lost an afternoon to draw.io — this one's for you.

Being part of 5 engineering teams over 8 years, here's something I experienced on almost every engineering team I've been part of. And you must have been too.

Product manager drops a PRD. We huddle in meeting rooms as devs with whiteboard markers flying, design discussions getting heated, someone sketching a system on the glass wall that actually makes sense.

And then came the part everyone dreaded.

"Ok, now create a design doc and add the diagrams."

Design documents. Sequence diagrams. Class diagrams. Architecture diagrams. All of it — formalized, version-controlled, and painstakingly created in draw.io.

I genuinely hated it.

And I think you know exactly what I mean. Dragging boxes. Aligning arrows. Snapping to grid. Unsnapping from grid because it snapped to the wrong thing. Spending 30 minutes on something or maybe more. It felt like the least productive version and the unglamorous part of engineering work and yet somehow it was always blocking the design review.

Honestly? I would have been happy to just take a photo of the whiteboard sketch and call it done. If only someone could magically understand it. Or if I could just speak out what I wanted to draw and have it appear.

I actually didn't mind sequence diagrams. The logic was satisfying. Mapping out the flow, seeing the interactions, watching the system tell its own story. I could get into that.

But then again with AWS architecture diagrams the problem wasn't really the icons.

And here's the thing — this isn't just a "me" problem.

If you've ever been responsible for architecture diagrams in a real team, you know exactly what I'm talking about. The pain is universal. And it's actually well-documented:

Creating professional AWS architecture diagrams is one of those tasks that sounds simple and never is. Solutions architects, developers, tech leads — everyone has to do it. And everyone has the same complaints.

It takes forever. A detailed architecture diagram can eat hours. Sometimes days if you're doing a full system design for a compliance review or a new product pitch.

The tools have a learning curve. draw.io, Lucidchart, Visio — they're not hard, but they're not fast either. And every new person on the team has to learn them from scratch.

Consistency is a constant battle. You make one diagram in one style, someone else makes another, and suddenly your documentation looks like it was designed by three different teams. Because it was.

AWS icons go stale. AWS releases new services, updates icon sets, renames things. Keeping your diagrams in sync with the official AWS visual language is a part-time job nobody signed up for.

And maintenance? Every time the architecture evolves — and it always evolves — you're back in the tool, reorganizing boxes, re-routing arrows, hoping nothing breaks the layout.

The result is that diagrams become a bottleneck. Or worse — they become outdated the moment they're published and nobody updates them because it's too painful.

Here's what I keep thinking about: architecture diagrams exist to communicate. That's their only job. To take the system in your head and make it legible to other humans.

And yet the tools we use to create them get in the way of that communication. The medium becomes the obstacle.

So when I say I stopped dragging boxes — I mean I found a way to close that gap. To go from "system in my head" to "diagram on screen" without the tax in between.

Let me show you how.

The problem was the thinking tax.

You'd find the right Lambda icon. Great. Now drag it. Now connect it to API Gateway. Now label the arrow. Now someone in the review says "can you add the VPC boundary?" and you spend 20 minutes reorganizing everything because the layout breaks when you add a container.

And then AWS releases a new service. Or renames one. Or the icon set gets updated. And suddenly your "official" diagram looks slightly off from the reference architecture in the AWS docs.

It was never really about the icons. It was about the gap between the system in your head and the diagram on the screen. That gap was always too wide. Too manual. Too slow.

I used to sit there thinking — what if I could just say what I want to draw?

Like, literally describe my architecture out loud and have it appear. Correct icons. Proper groupings. Best practices baked in.

Turns out — that's exactly what's possible now.

I stopped dragging boxes. Here's what I do instead.

Part 1: Official AWS Diagrams with Kiro CLI + MCP

Before we get into the setup, let me quickly explain what's actually happening under the hood — because understanding this makes everything click.

Kiro CLI is a command line interface that brings generative AI capabilities directly to your terminal. You interact with it through natural language prompts.

MCP (Model Context Protocol) — developed by Anthropic as an open protocol — provides a standardized way to connect AI models to virtually any data source or tool. Think of it as a plugin system for AI. MCP servers act as specialized extensions that give Kiro domain-specific capabilities it wouldn't have on its own.

The two MCP servers we're using:

AWS Diagram MCP → generates diagrams using the Python diagrams package with the complete official AWS icon set
AWS Documentation MCP → searches and reads AWS documentation to validate best practices before generating

Together, they give Kiro the ability to produce architecture diagrams that are both visually correct AND architecturally sound.

Setup (5 minutes, once)

Step 1: Install Kiro CLI

Download and install from the official docs, then verify:

kiro-cli --version
# kiro-cli x.x.x

kiro-cli login
# Recommended: use AWS Builder ID for experimenting

Step 2: Install dependencies

pip install uv
uv python install 3.10
# Also install GraphViz for your OS

Step 3: Configure MCP servers

Add this to ~/.kiro/settings/mcp.json:

{
  "mcpServers": {
    "awslabs.aws-diagram-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.aws-diagram-mcp-server"],
      "env": { "FASTMCP_LOG_LEVEL": "ERROR" },
      "autoApprove": [],
      "disabled": false
    },
    "awslabs.aws-documentation-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.aws-documentation-mcp-server@latest"],
      "env": { "FASTMCP_LOG_LEVEL": "ERROR" },
      "autoApprove": [],
      "disabled": false
    }
  }
}

Kiro CLI automatically discovers MCP servers from this file. That's it.

Step 4: Verify the setup

Start Kiro CLI and check your MCP servers are loaded:

kiro-cli
/mcp

Then test with a simple prompt:

"Please create a diagram showing an EC2 instance in a VPC connecting to an external S3 bucket. Include essential networking components (VPC, subnets, Internet Gateway, Route Table), security elements (Security Groups, NACLs), and clearly mark the connection between EC2 and S3. Label everything appropriately and indicate all resources are in us-east-1. Check AWS documentation to ensure it adheres to best practices before creating the diagram."

Kiro will ask you to trust the tool — enter t. If you see a diagram, you're set up correctly.

What's happening when you run a prompt

When you describe what you want, here's the actual sequence:

Kiro searches AWS documentation for best practices using search_documentation
Reads the relevant docs using read_documentation
Lists the needed AWS service icons using list_icons
Generates Python code using the diagrams package
Executes it and returns a PNG

You describe what you want. The MCP servers handle the rest.

Real examples

Simple web app:

Create a diagram for a simple web application with an Application Load Balancer,
two EC2 instances, and an RDS database. Check AWS documentation to ensure it
adheres to best practices before creating the diagram.

Multi-tier architecture:

Create a diagram for a three-tier web application with a presentation tier
(ALB and CloudFront), application tier (ECS with Fargate), and data tier
(Aurora PostgreSQL). Include VPC with public and private subnets across
multiple AZs. Check AWS documentation for best practices.

Serverless:

Create a diagram for a serverless web application using API Gateway, Lambda,
DynamoDB, and S3 for static website hosting. Include Cognito for user
authentication and CloudFront for content delivery. Check AWS documentation
for best practices.

Data pipeline:

Create a diagram for a data processing pipeline with components organized
in clusters for data ingestion (Kinesis, SQS), processing (Lambda, Glue),
storage (S3, DynamoDB), and analytics (Athena, QuickSight). Check AWS
documentation for best practices.

And you iterate by just… talking to it:

"Add a WAF in front of CloudFront."
"Show DynamoDB Streams connecting to a Lambda for event processing."
"Make it multi-region with Route 53."

Each change takes seconds. Not 20 minutes of reorganizing boxes.

Part 2: Hand-Drawn Diagrams with Kiro Skills

Here's where it gets fun.

Sometimes you don't want a polished, corporate-looking diagram. Sometimes you want that whiteboard sketch feel — the kind you'd draw during a design discussion when everyone's still figuring things out.

Kiro has a hand-drawn-diagrams skill that generates Excalidraw-style sketchy diagrams. The aesthetic is intentional — it looks like a human drew it. Which makes it perfect for:

Blog posts (feels approachable, not intimidating)
Video explainers (you can animate it drawing itself)
Quick architecture discussions where polish would feel premature

The prompt I used

Create a hand-drawn architecture diagram showing:
AI Agent → MCP Client → MCP Server → Spring Boot App → Amazon Bedrock

Layout: left-to-right flow
Style: hand-drawn sketch, monochrome
Shapes:
- AI Agent and Amazon Bedrock as ellipses (external actors)
- MCP Client, MCP Server, Spring Boot App as rectangles (services)

Label each arrow with the protocol:
- AI Agent → MCP Client: "tool call"
- MCP Client → MCP Server: "JSON-RPC"
- MCP Server → Spring Boot App: "HTTP/REST"
- Spring Boot App → Amazon Bedrock: "Bedrock API"

Add annotations below each node describing its role.

What Kiro did

Routed the request to its hand-drawn-diagrams skill
Generated a full Excalidraw JSON with proper element positioning
Validated the schema (24 elements, 0 errors)
Produced an editable link AND an animated version that draws itself stroke by stroke

The animated version is genuinely 🔥 for video content. Each node appears sequentially. Arrows draw themselves. Labels fade in. The kind of thing that would take hours in After Effects — done in one prompt.

Why This Actually Matters

This isn't just about saving time. Though it does — massively.

It's about removing friction from communication.

Architecture diagrams exist to explain systems to other humans. The faster you can go from "idea in your head" to "visual that others understand," the better engineer you become. The better communicator. The better collaborator.

And here's the thing I keep coming back to — MCP is the unlock. It's a standard protocol that lets AI tools connect to specialized capabilities.

Need AWS icons? MCP server for that.
Need best practices validation? MCP server for that.
Need hand-drawn aesthetics? Kiro skill for that.

The pattern is simple: describe what you want → get what you need.

TL;DR

What	How	Result
Official AWS diagrams	Kiro CLI + `aws-diagram-mcp-server`	Production-ready PNGs with correct icons
Best practices check	`aws-documentation-mcp-server`	Diagrams follow AWS Well-Architected
Hand-drawn sketches	Kiro `hand-drawn-diagrams` skill	Excalidraw-style, animatable diagrams
Iteration	Natural language follow-ups	Seconds per change, not hours