patrickchugh / terravision

TerraVision **AI-Powered Terraform to Architecture Diagram Generator** > **⚠️ Alpha Software Notice** > This software is in alpha testing. Code is shared "AS IS" without warranties. Use at your own risk. --- Table of Contents • What is TerraVision? • Quick Start • Key Features • Installation • Basic Usage • Documentation • Supported Cloud Providers • Contributing • License --- What is TerraVision? TerraVision automatically converts your Terraform code into professional cloud architecture diagrams. Quickly visualise any Terraform code to analyse what would be created in the cloud, AND keep your documentation in sync with your infrastructure. No more outdated diagrams! **Turn this Terraform code:** **Into these architecture diagrams:** Why TerraVision? • ✅ **Always Up-to-Date**: Diagrams generated from actual Terraform code as the single source of truth • ✅ **100% Client-Side**: No cloud access required, runs locally to keep your data secure • ✅ **CI/CD Ready**: Automate diagram generation in a pipeline whenever a PR is merged • ✅ **Free & Open Source**: No expensive diagramming tool licenses • ✅ **Multi-Cloud**: Supports AWS, GCP, and Azure --- Key Features 🎨 Professional Diagrams • Industry-standard cloud provider icons (AWS, GCP, Azure) • Automatic resource grouping (VPCs, subnets, security groups) • Clean, readable layouts • Multiple output formats (PNG, SVG, PDF, JPG, and many more) • **Editable draw.io export** - open in draw.io, Lucidchart, or your favorite diagram editor 🤖 AI-Powered Refinement • Automatically fixes resource relationships • Adds missing logical connections, labels, titles and icons as needed • Ensures architectural diagramming best practices 📝 Customizable Annotations • Add custom labels and titles • Include external resources not in Terraform • Override automatic connections 🔄 CI/CD Integration • GitHub Actions, GitLab CI, Jenkins support • Show multiple environments using TF Variables to document variants of your infrastructure (e.g. prod vs dev) • **Pre-generated plan mode**: Use and to skip Terraform execution entirely — no cloud credentials needed in the diagram step 🔒 Secure & Private • No cloud credentials required • Runs entirely on your local machine • No external API calls (except optional AI features) --- Quick Start Option 1 - Docker You can run from within a Docker container. Pull the pre-built image from Docker Hub: Or build it yourself from source: Then use it with any of your terraform files by mounting your local directory to the container: If you pulled from Docker Hub, use as the image name. If you built locally, use (or whatever tag you chose). Depending on your cloud provider, you may need to pass your credentials so that OpenTofu/Terraform can run terraform plan commands For example, for AWS: Option 2 - Local Install Before installing TerraVision, ensure you have: • **Python 3.10+** - Download Python • **Terraform 1.x** - Install Terraform • **Graphviz** - Install Graphviz • **Git** - Install Git • **Ollama** (Optional - for local AI refinement) - Install Ollama Install TerraVision Verify Terraform Setup Before generating diagrams, ensure Terraform is working with and TerraVision needs Terraform to successfully run to parse your infrastructure. Note that whilst cloud credentials are required for TERRAFORM to validate resources and resolve functions, TerraVision itself never accesses your cloud account. Alternatively, use and to provide pre-generated Terraform plan and graph outputs, bypassing Terraform execution entirely. Option 3 - Nix If you have Nix installed with flakes enabled, you can enter a development shell with and all dependencies available: This provides , , , and in your shell. You can also run it directly without cloning: Try It Out! Generate your first diagram using our example Terraform code: **That's it!** Your diagram is saved as and automatically opened. Use Your Own Terraform Code Use Pre-Generated Terraform Plan (No Cloud Credentials Needed) If you already have Terraform plan output (e.g. from a CI pipeline), you can generate diagrams without running Terraform: This is especially useful in CI/CD pipelines where Terraform runs in one step and diagram generation happens in another. See CI/CD Integration for examples. Use TerraVision simply as a drawing engine with a simple JSON dict --- Installation for Developers / Power Users **Detailed installation instructions**: See docs/INSTALLATION.md --- Basic Usage Generate a Diagram Common Options | Option | Description | Example | | ------------- | ----------------------------- | -------------------------- | | | Terraform code location | or Git URL | | | Output format (see Supported Formats) | , , , , etc. | | | Output filename | (default) | | | Terraform workspace | , | | | Variable file | | | | Pre-generated plan JSON file | | | | Pre-generated graph DOT file | | | | Simplified high-level view | (flag) | | | Open diagram after generation | (flag) | | | Enable debug output | (flag) | Supported Output Formats TerraVision supports all output formats provided by Graphviz, plus native draw.io export. Use the option to specify your desired format: | Format | Description | |--------|-------------| | | Portable Network Graphics (default) | | | Scalable Vector Graphics - ideal for web | | | Portable Document Format - ideal for printing | | | **Editable diagram format** - open in draw.io, Lucidchart, or other diagram editors | | / | JPEG image format | | | Graphics Interchange Format | | | Windows Bitmap | | | Encapsulated PostScript | | / | PostScript | | / | Tagged Image File Format | | | WebP image format | | | Graphviz DOT source | | | Graphviz JSON format with layout info (different from output) | | | Extended DOT format with layout information | For the complete list of Graphviz formats, see the Graphviz Output Formats documentation. Editable Diagrams with draw.io Format Generate diagrams you can edit in your favorite dia…