TerraVision

Turn Terraform code into professional cloud architecture diagrams that stay in sync with your infrastructure — automatic, secure, living documents

📖 Full documentation site →

Watch a 4-Minute Intro

What is TerraVision?

TerraVision automatically converts your Terraform code into professional-grade cloud architecture diagrams using the official AWS, GCP, and Azure icon sets. Your diagrams stay in sync with your infrastructure — no more outdated Visio, draw.io or Lucidchart files.

Why TerraVision?

• ✅ Always up-to-date — diagrams generated directly from your Terraform code
• ✅ 100% client-side — no cloud access required, runs locally, your code never leaves your machine
• ✅ CI/CD ready — automate diagram updates on every PR merge
• ✅ Free & open source — no expensive diagramming tool licenses
• ✅ Multi-cloud — AWS (full), GCP, and Azure (core services)
• ✅ Interactive HTML output — clickable nodes, pan/zoom, search, animated data flow
• ✅ Editable draw.io export — open in draw.io, Lucidchart, or any mxGraph editor
• ✅ Optional AI annotations — labels, titles, and flow sequences from Ollama (local) or AWS Bedrock
• ✅ Terragrunt compatible — auto-detects single- and multi-module Terragrunt projects
• ✅ MCP server — let AI agents generate diagrams from your Terraform, see the guide

Supported Cloud Providers

Quick Start

Install

pipx install terravision   # or: pip install terravision if in a virtual env

You also need Python 3.10+, Terraform 1.x, Graphviz, and Git. See the Installation Guide for platform-specific instructions, Docker, and Nix.

Generate your first diagram

git clone https://github.com/patrickchugh/terravision.git
cd terravision

# EKS cluster example
terravision draw --source tests/fixtures/aws_terraform/eks_automode --show

# Azure VM scale set
terravision draw --source tests/fixtures/azure_terraform/test_vm_vmss --show

# From a public Git repo (note the // for subfolder)
terravision draw --source https://github.com/patrickchugh/terraform-examples.git//aws/wordpress_fargate --show

That's it — your diagram is saved as architecture.png and opens automatically.

Generate an interactive HTML diagram

terravision visualise --source ./path-to-your-terraform --show

Click any resource to see its Terraform metadata, search resources, pan/zoom, and watch animated data flow on edges. The HTML is a single self-contained file that works fully offline.

Try the Interactive Demos

Click any of these to see the interactive HTML output TerraVision produces:

• 🟧 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

Basic Usage

Generate a diagram

# From a local directory
terravision draw --source ./path-to-your-terraform

# From a Git repository
terravision draw --source https://github.com/user/repo.git

# Custom format and filename
terravision draw --source ./path-to-your-terraform --format svg --outfile my-architecture

# Editable draw.io file
terravision draw --source ./path-to-your-terraform --format drawio --outfile my-architecture

Use a pre-generated Terraform plan (no cloud credentials needed)

# Step 1: in your Terraform environment
terraform plan -out=tfplan.bin
terraform show -json tfplan.bin > plan.json
terraform graph > graph.dot

# Step 2: diagram generation, no Terraform or cloud access required
terravision draw --planfile plan.json --graphfile graph.dot --source ./path-to-your-terraform

AI-powered annotations (optional)

terravision draw --source ./path-to-your-terraform --ai-annotate ollama   # local LLM (no data leaves your machine)
terravision draw --source ./path-to-your-terraform --ai-annotate bedrock  # AWS Bedrock via boto3 (uses your AWS credentials)
terravision draw --source ./path-to-your-terraform --ai-annotate restapi  # any OpenAI-compatible endpoint (OpenAI, LiteLLM, vLLM, ...)

Only metadata and the summary graph are sent to the LLM — never your .tf source. The bedrock backend authenticates via the standard AWS credential chain (no infrastructure to deploy); restapi is configured via TV_RESTAPI_URL, TV_RESTAPI_KEY, and TV_RESTAPI_MODEL. See the Annotations Guide and AI-Powered Annotations for the full configuration.

Simplified view

terravision draw --source ./path-to-your-terraform --simplified

Strips VPCs, subnets, and networking plumbing. Great for executive presentations.

Common options

terravision --help shows full help text details.

Documentation

The complete documentation lives at patrickchugh.github.io/terravision.

For users:

• Installation Guide
• Usage Guide
• Annotations Guide
• CI/CD Integration
• MCP Server Guide
• FAQ
• Troubleshooting

For contributors:

• Contributing Guide
• Developer Guide
• Resource Handler Guide
• Project Constitution

FAQ

Common questions — cloud credentials, LLM data privacy, offline use, Terragrunt, output formats, and more — are answered in the FAQ on the documentation site.

Contributing

Contributions are very welcome. See CONTRIBUTING.md for development setup, coding standards, and the PR process.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: patrickchugh.github.io/terravision

License

See LICENSE.

Acknowledgments