TerraVision

Professional cloud architecture diagrams in official AWS, Azure and GCP style, from a description in Claude or ChatGPT or from your Terraform

🌐 terravision.online · 📖 Full documentation →

TerraVision is a free, open-source cloud architecture diagram generator for AWS, Azure and Google Cloud that works in both directions: design to code (describe it to your AI assistant, get the diagram, then the Terraform) and code to diagram (draw what your Terraform deploys).

Ask your AI assistant for a cloud architecture diagram, in plain words, and get the diagram a cloud architect would draw: the official AWS, Azure and GCP icons, with every resource in its VPC, subnet, zone or resource group. From a description, from your Terraform code, or the other way round, with the Terraform written from the diagram. TerraVision runs on your own computer and needs no cloud access.

Draw prod without prod access.

TerraVision draws what your Terraform will deploy, from the code alone. The infrastructure doesn't have to exist yet, and you need no access to any account it deploys to. Live cloud scanners can't do that. See how →

---

Watch the 90-Second Intro

---

Gallery

The same three-tier design on each cloud, then a flagship for each. Every example comes with the prompt and the source file: see the full gallery →

AWS three-tier web app	Azure three-tier web app	Google Cloud three-tier web app
AWS EKS with Karpenter	Azure hub-and-spoke landing zone	Google Cloud GKE with Private Service Connect

More in the gallery: AWS serverless event-driven · AWS data lake · AWS multi-region failover · AWS multi-account network · Azure AKS · Google Cloud data pipeline

---

Get started in Claude or ChatGPT

TerraVision installs as an extension in Claude Desktop and a plugin in the ChatGPT desktop app, where the diagram appears right in the chat. It also works in Claude Code, Codex CLI, GitHub Copilot, Cursor and any other MCP client.

1. Install the prerequisites (once)

TerraVision needs Graphviz (to draw) and Git. uv runs TerraVision for Claude Code, Codex, Antigravity CLI and other MCP clients; Claude Desktop brings its own on Windows and macOS, so skip it there. Terraform is only needed to draw from Terraform code.

macOS

With Homebrew:

brew install graphviz git
brew install uv                        # not needed for Claude Desktop
brew install hashicorp/tap/terraform   # optional: to draw from Terraform code

Windows

In PowerShell:

winget install --id Graphviz.Graphviz -e
winget install --id Git.Git -e
winget install --id astral-sh.uv -e    # not needed for Claude Desktop
winget install --id Hashicorp.Terraform -e   # optional: to draw from Terraform code

Then open a new terminal, and restart your AI app, so they see the new programs.

Linux (Debian, Ubuntu)

sudo apt install graphviz git
# Ubuntu 26.04 and later only (also Debian 14 "forky"/testing).
# Skip on older releases such as Ubuntu 24.04: graphviz already includes it.
sudo apt install libgvplugin-neato-layout8

curl -LsSf https://astral.sh/uv/install.sh | sh   # Claude Desktop on Linux needs uv pre-installed

# optionally install terraform, to draw from Terraform code: HashiCorp's apt repository
wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install terraform

Other distributions: HashiCorp's install guide.

No admin rights, or no package manager? Each tool can be unpacked into your home folder and added to your PATH: installation guide.

2. Connect your assistant

Claude Desktop: download terravision-<version>.mcpb from the latest release and open it (or drag it into Settings → Extensions). Diagrams appear right in the chat, with buttons to open the image, edit it in draw.io, show it in its folder and see its source.

Claude Code (terminal, VS Code or JetBrains):

claude plugin marketplace add patrickchugh/terravision
claude plugin install terravision-cloud-diagrams@terravision

Then start a new Claude Code session. Diagrams are saved in a diagrams folder in your project. If /mcp shows TerraVision failed to connect on first start (the install can take longer than Claude Code waits), choose Reconnect, or pre-install with uvx --from "terravision[mcp]" terravision --version.

ChatGPT desktop app and OpenAI Codex CLI: in the desktop app, go to Settings, add the marketplace https://github.com/patrickchugh/terravision, then select terravision-cloud-diagrams. For the CLI:

codex plugin marketplace add https://github.com/patrickchugh/terravision
codex plugin add terravision-cloud-diagrams@terravision

Google Antigravity CLI (agy):

agy mcp add terravision -- uvx --from "terravision[mcp]" terravision mcp --output-dir /path/for/diagrams

VS Code with GitHub Copilot, Cursor and other MCP clients: add an MCP server that runs uvx --from "terravision[mcp]" terravision mcp --output-dir <folder for diagrams>. Configuration for each client, plus the npx skills add patrickchugh/terravision skill-only install, is in the setup guide.

3. Ask for a diagram (or code)

You have	Ask something like	You get
An idea	"Draw an AWS three-tier app: React on CloudFront, ECS Fargate behind an ALB in two AZs, SQL Server on RDS Multi-AZ"	The diagram (PNG, SVG, editable draw.io) and its graph. Refine it by asking: "add ElastiCache", "show how a request flows through it"
A diagram you like generated from TerraVision	"Write the Terraform for this architecture"	Terraform for the resources, zones and connections, with the diagram's flows and labels kept (quality depends on model used)
Terraform code, local or on GitHub but no VERIFIED diagram	"Draw the architecture of the Terraform in ./infra" or "Show me a cloud architecture diagram of https://github.com/patrickchugh/testcase-bastion//examples"	A diagram of what terraform plan says the code deploys
A TerraVision diagram of your Terraform that you want to publish in HTML documentation, or review resource by resource, for example in a security audit	"Make this diagram interactive" or "Give me an interactive version I can click through"	A single HTML page that works in any browser or docs site, no server needed: click any resource to see its settings (encryption, public access, ports, IAM), search and zoom. Built from terraform plan, so it needs the Terraform, not just a picture
Terraform with an existing TerraVision diagram in a repository	"Keep this diagram up to date in CI"	A workflow that redraws the diagram whenever the Terraform changes

The first diagram takes a little longer while TerraVision installs itself. If anything is missing, the assistant says what to install. To check at any time, ask: "Is TerraVision set up correctly?"

The full guide, with more example prompts: Use TerraVision with AI assistants.

---

Keep diagrams current in CI/CD

Point the TerraVision GitHub Action at your Terraform, and the diagram redraws itself on every change:

- uses: hashicorp/setup-terraform@v3
- uses: patrickchugh/terravision-action@v2
  with:
    source: ./infrastructure
    outfile: docs/architecture
    format: both

A terravision.yml next to the Terraform adds the title, numbered flows and connection labels to every version. GitLab, Jenkins, Azure DevOps and others: CI/CD Integration.

---

Why TerraVision?

• ✅ Built for AI assistants: extensions and plugins for Claude, ChatGPT, Codex, Copilot and Cursor, with the diagram shown in the chat (guide)
• ✅ Provably accurate: drawn from terraform plan, so the code is the source of truth and what you see is what deploys
• ✅ Draw prod without prod access: the infrastructure need not exist and you need no access to the account it deploys to; one codebase draws dev, staging and prod from their variables files (how)
• ✅ Official icons and conventions: AWS, Azure and GCP icons, with every resource in its VPC, subnet, zone or resource group
• ✅ JSON graph input: describe an architecture in a few lines of JSON, no custom DSL to learn (Graph Format)
• ✅ 100% client-side: runs locally, needs no cloud access, your code never leaves your machine
• ✅ Interactive HTML and editable draw.io output, flow annotations (YAML or AI-generated via Ollama or Bedrock), Terragrunt support, free and open source

---

How it compares

	TerraVision	Manual tools (draw.io, Lucidchart, Visio)	AI workspaces (Eraser)	Diagram as code (Mermaid, D2, Python Diagrams)	Live cloud scanners (e.g. Cloudcraft)
Draw from a plain-English description	✅ inside the assistant you already use (Claude, ChatGPT, Copilot)	only if your organisation approves third-party models	✅
Draw from Terraform	✅ built from terraform plan, client side		AI interprets the files you paste (potentially exposes code & secrets)
Draw an environment you have no access to, or one not built yet	✅ from the code and a variables file alone: the infrastructure need not exist, and no access to any account it deploys to is needed. --varfile prod.tfvars draws prod, --varfile dev.tfvars draws dev	drawn by hand from documents	from code you paste	written by hand	draws only an account it can connect to
Write the Terraform for a design	✅ by your assistant, checked by redrawing the code AI writes	Lucidchart beta, AWS only, paid add-on
Official icons and VPC, subnet, zone grouping conventions	✅ built in	icon libraries; correct grouping is up to you	icons, generic groups
Stays current automatically	✅ redrawn from the code in CI		repository sync		✅ follows the live account
High Security - No access to your cloud account or upload of your code	✅	✅		✅
Price	Free, open source	Free to paid	Free tier, paid plans	Free, open source	Paid

Already draw by hand? Generate the first version with TerraVision, then polish the exported file in draw.io or Lucidchart. Full comparison: TerraVision vs draw.io, Lucidchart, Eraser, Mermaid and others.

---

Supported Cloud Providers

Provider	Status	Resource types
AWS	✅ Full support	427 types
Google Cloud	✅ Full support	267 types
Azure	✅ Full support	263 types

Full list: Node types.

---

Use it from the command line

TerraVision is also a command-line tool, for scripts and for people who prefer to write the graph themselves.

Install

pipx install terravision   # or: uv tool install terravision
                           # or: pip install terravision in a virtual env

You also need Python 3.11+ (uv installs one for you), Graphviz and Git, plus Terraform 1.x (or OpenTofu) when drawing from Terraform code; JSON graphs don't need it. Platform-specific steps, Docker and Nix: Installation Guide.

Diagram from JSON (no Terraform needed)

Each key is <terraform_resource_type>.<name>; each value is what it connects to or contains. That is the whole format.

{
  "tv_aws_users.users": ["aws_cloudfront_distribution.cdn"],
  "aws_cloudfront_distribution.cdn": ["aws_s3_bucket.static_site", "aws_alb.api"],
  "aws_vpc.main": ["aws_subnet.public~1", "aws_subnet.private~1"],
  "aws_subnet.public~1": ["aws_alb.api"],
  "aws_subnet.private~1": ["aws_lambda_function.orders"],
  "aws_alb.api": ["aws_lambda_function.orders"],
  "aws_lambda_function.orders": ["aws_dynamodb_table.orders", "aws_sqs_queue.events"]
}

terravision draw --source architecture.tvg.json --format svg

Works for AWS (aws_*), Azure (azurerm_*) and GCP (google_*). Full spec, schema and Azure and GCP examples: Graph Format.

Diagram from Terraform

terravision draw --source ./path-to-your-terraform --show                    # local directory
terravision draw --source https://github.com/user/repo.git//subfolder --show # public Git repo
terravision draw --source ./path-to-your-terraform --varfile prod.tfvars     # draw prod without prod access
terravision visualise --source ./path-to-your-terraform --show               # interactive HTML

The diagram is derived from terraform plan, so it shows what the code actually deploys: conditionals, count, for_each and modules are resolved. Eraser and friends draw what the AI imagines; TerraVision proves what the code deploys.

Output formats, pre-generated plans, AI annotations, the simplified view and every option (terravision --help): Usage Guide.

Try the interactive demos

• 🟧 AWS demo: Wordpress on ECS Fargate with CloudFront, RDS, EFS
• 🟦 Azure demo: VM scale set with load balancer and VNet
• 🟩 GCP demo: Core GCP networking and compute

---

Documentation

Everything lives at patrickchugh.github.io/terravision (llms.txt for AI agents).

• Using TerraVision: Installation · Usage Guide · Draw prod without prod access · Annotations · CI/CD · MCP Server · FAQ · Troubleshooting
• Diagram generators: Cloud · AI (description to diagram) · Diagram to Terraform · AWS · Azure · Google Cloud · Terraform · Alternatives compared
• For collaborators: Contributing · Developer Guide · Resource Handler Guide · Constitution

---

Contributing and support

TerraVision accepts pull requests only from invited collaborators. Bug reports, feature requests and questions are welcome in Issues and Discussions; CONTRIBUTING.md says what to put in a bug report.

Licensed under AGPL-3.0, see LICENSE. Built on Graphviz, Terraform and Terragrunt, with the official AWS, Azure and GCP icon sets.