If you’ve ever had to write a Design Document from scratch — you know the pain. You’re staring at dozens of Terraform files, cross-referencing module parameters, tracing spoke-to-transit attachments, figuring out which firewall image string maps to which vendor and license model… and then you have to turn all of that into a polished document that someone on a change management board can actually read.

I do this regularly for multi-cloud Aviatrix deployments. AWS, Azure, sometimes GCP — transit gateways, FireNet, DCF policies, edge connectivity back to on-prem. Every deployment is different, and every one needs an IDD. It’s easily a full day of work, and by the time you’re done, someone’s already pushed a change that makes half of it outdated.

So I built something to fix that.

What It Does

You drop your .tf and .tfvars files into a browser, hit “Generate,” and about 30 seconds later you get a complete Infrastructure Design Document. Network topology, firewall details, security policies, data flows, component inventory — the whole thing, broken into tabs you can browse through and export to Word.

That’s it. No templates to fill out. No copying values from Terraform into a spreadsheet. Just upload and go.

How It Actually Works

Under the hood, the app sends your Terraform files to Claude with a very specific system prompt. I spent a lot of time on this prompt — it’s not just “summarize this code.” It tells Claude to act as a senior cloud architect and return structured JSON matching an exact schema. Every field has constraints. Every description needs to explain the why, not just the what.

The trick that makes it work well is baking in Aviatrix domain knowledge. The prompt includes all the default values for mc-transit, mc-spoke, and mc-firenet modules. So when your Terraform doesn’t explicitly set gw_size, the AI knows that an AWS transit defaults to t3.medium — or c5n.xlarge if insane mode or FireNet is enabled. It knows how to parse firewall image strings like “Palo Alto Networks VM-Series Next-Generation Firewall Bundle 1” into vendor, product, and license fields. It traces spoke-to-transit attachments through aviatrix_spoke_transit_attachment resources and mc-spoke module parameters.

The result is a JSON object with 15+ sections, all populated with data pulled directly from your actual Terraform — not generic boilerplate.

The Diagrams Were the Hard Part

Getting a text document out of Claude was the easy part. The network diagram? That took some work.

The app generates an SVG-based topology diagram entirely in React — no layout library, no Mermaid, no external renderer. Everything is computed from the data. Each VPC gets the right cloud provider icon (AWS VPC shield, Azure VNet, GCP VPC grid) based on its name. Spoke VPCs connect to whichever transit they’re actually attached to in the Terraform. Firewall badges only show up on transits that have FireNet enabled. Connection labels adapt per provider — “VPN/DX” for AWS, “VPN/ER” for Azure, “VPN/Interconnect” for GCP.

Internet and On-Prem nodes appear only when the data supports it — public subnets, egress rules, external connections, or edge devices. It’s all driven by what’s in your code, not assumptions.

Some Things I Learned Along the Way

Prompt engineering is real engineering. The difference between a prompt that produces usable output and one that hallucinates garbage is huge. The schema constraints, the Aviatrix defaults, the firewall detection heuristics — all of that took iteration. Early versions would miss firewalls entirely or make up gateway sizes.

SVG in React has quirks. You can’t use React fragments (<>) inside SVG — they silently break rendering. Gradient IDs need to be unique per component instance or they bleed across icons. Small things, but they cost hours to debug.

Per-VPC provider detection matters. In a multi-cloud deployment, a VPC named “azure-aviatrix-transit” needs to show an Azure icon, not AWS. Sounds obvious, but when your detection logic concatenates the name with the purpose field and the purpose mentions “AWS peering” — suddenly your Azure transit has an AWS icon. Ask me how I know.

The Stack

The whole app is a single React file — about 1,200 lines. No router, no state management library. Tailwind for styling, Vite for dev/build, Vercel for hosting with a serverless proxy to the Anthropic API. It also exports to Word (.docx) with tables, embedded diagrams, and structured headings.

Intentionally simple. It does one thing and does it well. You can fetch it from: https://github.com/rtrentinavx/terraform-design-doc

What’s Next

I’m still improving the diagrams — better icons, cleaner layout for large deployments. I’d also like to add a diff mode so you can compare two versions of a design document side by side when infrastructure changes. And eventually, hooking this into CI/CD so an updated IDD gets generated automatically on every Terraform change.

But honestly, even as it is today, it’s already saving me hours every week. If you’re managing Aviatrix deployments and spending too much time on documentation — this is the kind of tool that pays for itself immediately.