TerraVision

TerraVision

TerraVision is an AI-powered CLI tool that converts Terraform code into Professional Cloud Architecture Diagrams and solves the problem of keeping the most important document in cloud projects, the architecture diagram, up to date. With high velocity releases the norm now, code is the new source of truth so machine generated architecture diagrams are more accurate than relying on the freestyle diagram drawn by the cloud architect that probably doesn't match the reality of what is actually deployed in the cloud anymore.

TerraVision securely runs 100% Client Side without any dependency or access to your Cloud environment, dynamically parses your conditionally created resources and variables and generates an automatic visual of your architecture. TerraVision is designed to be a 'Docs as Code' (DaC) tool that can be included in your CI/CD pipeline to update architecture diagrams after your build/test/release pipeline phases and supplement other document generators like readthedocs.io alongside it.

Status

Supported Cloud Providers

• ✅ AWS (Full support with 200+ services)
• 🔄 Google Cloud Platform (Partial Support)
• 🔄 Microsoft Azure (Partial Support)

Turn this...

into this...

⚠️ Alpha Software Notice

This software is still in alpha testing and code is shared on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. Use at your own risk.

Benefits of terravision

1. Cost

• Save Visio/Drawing software licenses - terravision is free and open source
• Doesn't require any cost incurring cloud resources to be spun up, it works instantly from your local machine
• Regularly updating diagrams aligning, connecting dots and laying out icons is not the best use of your architect staff costs

1. Accelerate and Automate

• Use TF variable files as inputs to create multiple variant diagrams from the same TF code
• Doesn't require infrastructure to exist to document it. Terravision works off your terraform plan not your remote statefile
• Automate creation of architecture diagrams by running terravision as part of CI/CD pipelines
• YAML based Diagrams as code allows you to Annotate generated diagrams with additional custom labels and resources e.g. unmanaged resources or external systems not captured in TF code

1. Consistency across organisation

• Auto downloads your organisational / external modules to ensure the latest view of downstream Terraform modules
• Consistent design of architecture diagrams using industry standard icons and AWS/GCP/Azure approved style across teams

1. Accurate Visibility

• Real time state of diagram shows current infrastructure that matches exactly what is deployed in production today
• Helps in third party architecture reviews, auditing, monitoring, reporting and debugging of the stack in a visual way
• Custom Diagram code and output images can be put into source/version control for better maintainability and discoverability

1. Security

• Don't need to give access to your AWS account, credentials or CLI to draw diagram
• Doesn't create intrusive cloud resources e.g. scanning instances or metadata tables which enterprises would need to approve
• All source code stays in your local environment, diagrams are generated on your machines without calling out to external APIs
• Only metatdata is sent to LLM models with only minimal aggregate data saved in external files, not any sensitive code or runtime environment values

CI/CD Pipeline Integration

TerraVision seamlessly integrates into your CI/CD pipeline to automatically keep architecture diagrams synchronized with your infrastructure code:

graph TD

A[Developer Commits Terraform Code] --> B[Git Push] B --> C[CI/CD Pipeline Triggered] C --> D[Build Stage] D --> E[Test Stage] E --> F[Terraform Plan] F --> G[🎨 TerraVision Generate Diagrams] G --> H[Deploy Stage] H --> I[Update Docs] I --> J[Publish to Confluence/ReadTheDocs]

style G fill:#ff9900,stroke:#232f3e,stroke-width:3px,color:#fff style A fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff style J fill:#36b37e,stroke:#1f7a54,stroke-width:2px,color:#fff

Installation and Usage

System Requirements

• Python 3.10+
• Terraform 1.x
• Git
• Graphviz
• Ollama (Optional - only required if using --aibackend ollama)

1. Install External Dependencies

Required Dependencies

1. Graphviz - https://graphviz.org/download/

   # macOS

brew install graphviz

Ubuntu/Debian

sudo apt-get install graphviz

Windows

Download from https://graphviz.org/download/

1. Git - https://git-scm.com/downloads

   # Most systems have git pre-installed

git --version

1. Terraform - https://developer.hashicorp.com/terraform/downloads

   # Verify installation

terraform version

Must be v1.0.0 or higher

2. Install TerraVision

Method 1: Quick Install in MacOS/Linux (For Casual Users - will install packages globally)

# Clone the repository

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

Install Python dependencies

pip install -r requirements.txt

Make script executable in Linux

chmod +x terravision.py

Create symbolic link without extension (Unix/Linux/macOS)

ln -s $(pwd)/terravision.py $(pwd)/terravision

Add to PATH

export PATH=$PATH:$(pwd)

For Windows:

# Clone the repository

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

Install Python dependencies

pip install -r requirements.txt

Create batch file wrapper

echo @python "%~dp0terravision.py" %* > terravision.bat

Add current directory to PATH or copy terravision.bat to a directory in PATH

copy terravision.bat C:\Windows\System32\

Method 2: Poetry Install (Recommended for Developers and Power Users)

# MacOS or Linux users - Install Poetry if not already installed

curl -sSL https://install.python-poetry.org | python3 -

For Windows Users

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

Clone and install with Poetry

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

Activate virtual environment

source $(poetry env info --path)/bin/activate

Create symbolic link without extension

ln -s $(pwd)/terravision.py $(pwd)/terravision

Add current terravision directory to PATH

export PATH=$PATH:$(pwd)

Basic Usage

Generate Architecture Diagram

# Basic usage - analyze current directory

terravision draw

Specify source directory

terravision draw --source ~/src/my-terraform-code

Use specific Terraform workspace

terravision draw --source ~/src/my-terraform-code --workspace production

Use variable files

terravision draw --source ~/src/my-terraform-code --varfile prod.tfvars

Generate different formats

terravision draw --source ~/src/my-terraform-code --format svg terravision draw --source ~/src/my-terraform-code --format pdf

Show diagram after generation

terravision draw --source ~/src/my-terraform-code --show

Use AI backend for diagram refinement (default: bedrock)

terravision draw --source ~/src/my-terraform-code --aibackend bedrock terravision draw --source ~/src/my-terraform-code --aibackend ollama

Remote Git Repository Support

# Analyze Git repository

terravision draw --source https://github.com/your-repo/terraform-examples.git

Analyze specific subfolder in Git repo

terravision draw --source https://github.com/your-repo/terraform-examples.git//aws/vpc

Export Graph Data

# Export resource relationships as JSON

terravision graphdata --source ~/src/my-terraform-code

Show only unique services used

terravision graphdata --source ~/src/my-terraform-code --show_services

Export to custom filename

terravision graphdata --source ~/src/my-terraform-code --outfile my-resources.json

Advanced Features

Use with annotations

# Add your own custom annotations such as labels, resources or new connections

terravision draw --source https://github.com/your-repo/terraform-examples.git --annotate ./custom-annotations.yml

Working with Pre-generated JSON from previous terravision run (faster)

# Export and reuse graph data

terravision graphdata --source ~/src/terraform --outfile graph.json

Use previously exported JSON data (just the graph dict)

terravision draw --source ./graph.json terravision draw --source ./graph.json --format svg

Reprocess and replay from previous debug (for troubleshooting without calling slow terraform init/plan/analayse again)

terravision draw --source /your_source_files --debug # createas a tfdata.json in current folder terravision draw --source tfdata.json

Debug Mode

# Enable debug output for troubleshooting and which will dump all state info into tfdata.json

terravision draw --source ~/src/my-terraform-code --debug

AI-Powered Diagram Refinement

TerraVision can use AI models to automatically refine and improve your architecture diagrams by fixing resource groupings, adding missing connections, and ensuring proper AWS architectural conventions.

Supported AI Backends

AWS Bedrock (Default)

Uses AWS Bedrock API via API Gateway for cloud-based AI refinement.

# Use Bedrock backend (default)

terravision draw --source ~/src/my-terraform-code --aibackend bedrock

Configuration: Edit modules/cloud_config.py to set your Bedrock API endpoint:

BEDROCK_API_ENDPOINT = "https://your-api-id.execute-api.us-east-1.amazonaws.com/prod/chat"

Ollama (Local)

Uses a local Ollama server for privacy-focused, offline AI refinement.

# Use Ollama backend

terravision draw --source ~/src/my-terraform-code --aibackend ollama

Setup:

1. Install Ollama from https://ollama.ai/download
2. Start Ollama server and pull a model:

   # Start Ollama (runs automatically on macOS/Linux after install)

ollama serve

Pull the llama3 model

ollama pull llama3

Set model to stay loaded longer (optional, prevents premature unloading)

Default timeout is 5 minutes, extend to 1 hour:

export OLLAMA_KEEP_ALIVE=1h

3. Edit `modules/cloud_config.py` to set your Ollama server (default is localhost):

   OLLAMA_HOST = "http://localhost:11434"

AI Refinement Prompts

The AI models use specialized prompts defined in modules/cloud_config.py:

• AWS_REFINEMENT_PROMPT: Guides the AI to fix resource groupings, connections, and ensure AWS best practices
• AWS_DOCUMENTATION_PROMPT: Generates architecture summaries and documentation

Setting Up AWS Bedrock Backend

TerraVision includes Terraform code to deploy a serverless AWS Bedrock proxy with API Gateway:

# Navigate to the Terraform directory

cd ai-backend-terraform

Configure your settings

cp terraform.tfvars.example terraform.tfvars

Edit terraform.tfvars with your settings

Deploy the infrastructure

terraform init terraform apply

Get your API endpoint

terraform output api_endpoint

Infrastructure Components:

• API Gateway: REST API with streaming support for real-time responses
• Lambda Function: Node.js 20.x function with response streaming
• DynamoDB: Rate limiting and usage tracking
• CloudWatch: Monitoring, logging, and cost alerts
• IAM Roles: Least-privilege access for Lambda to invoke Bedrock

Terraform Variables:

variable "bedrock_mod