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

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.

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

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.

There are two approaches I use — one for production-ready AWS architecture diagrams with official icons, and another for quick hand-drawn sketches when polish would feel premature. Let me show you both.

Part 1: Official AWS Diagrams with Kiro + 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 is an AI-powered IDE that brings generative AI capabilities directly into your development workflow.

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:

• diagrams-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→ 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 dependencies

# uv — a fast Python package/environment manager.
# The diagrams-mcp server runs as a Python tool via uvx (uv's package runner).
pip install uv

# Python 3.10 — required by the diagrams package for generating architecture PNGs.
# If you already have 3.10+ installed, skip this.
uv python install 3.10

# GraphViz — the layout engine that positions nodes and routes arrows in diagrams.
# Without it, the diagrams package can generate code but can't render images.
# macOS: brew install graphviz
# Ubuntu: sudo apt install graphviz
# Windows: choco install graphviz

Step 2: Configure MCP servers

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

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

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

macOS note: If the servers fail to connect, uvx may not be in Kiro's PATH. Find your full path with which uvx in terminal and replace "uvx" with the full path (e.g. "/Users/yourname/.local/bin/uvx") in the config above.

Step 3: Verify the setup

Open the Kiro chat panel and check your MCP servers are connected from the MCP panel in the sidebar. 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."

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:

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

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

Final digram:

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

Setup (one-time)

Download the skill zip and install it:

unzip ~/Downloads/hand-drawn-diagrams.zip -d ~/.kiro/skills/

Kiro picks it up automatically. No restart needed.

The prompt I used

Create a hand-drawn architecture diagram showing the MCP flow:

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 a short annotation below each node describing its role.
Add a title: "MCP Architecture Flow"

Open it in the Excalidraw editor.

What Kiro did

• Routed the request to the hand-drawn-diagrams skill
• Generated a full Excalidraw JSON with 24 elements, validated clean (0 errors)
• Produced two live links instantly — no export, no download needed

👉 View & edit the diagram
— opens in Excalidraw, fully editable. Export PNG via hamburger menu → Export image → PNG.

👉 Watch it animate
— each node draws itself stroke by stroke. Perfect for screen recording as video content.

The animated version is genuinely great for explainer videos. 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

The SDLC pain point of "make a diagram" just became a one-liner.

If you're still dragging boxes in 2026 — try this. Your future self will thank you.

🔗 Reference: Build AWS architecture diagrams using Kiro CLI and MCP

What's the most painful diagram you've ever had to create? Drop it in the comments — I'll try generating it with a single prompt. 👇