Terravision Cloud Diagrams

TerraVision cloud architecture diagrams

TerraVision renders cloud architecture diagrams using the official AWS, Azure and GCP icon sets, with resources grouped into VPCs, subnets, resource groups, regions and zones the way a cloud architect would draw them. Output is PNG, SVG, PDF, DOT, or an editable draw.io file.

When to use it, and when not

Use it for pictures of AWS, Azure or GCP infrastructure: which services exist, where they sit in the network, and how they connect.

Do not use it for anything else. Sequence diagrams, flowcharts, class or ER diagrams, code or module structure, org charts and on-premises-only networks are better drawn with Mermaid or similar. A request flow through the infrastructure belongs on the TerraVision diagram itself, as numbered steps ("Flows" below).

If the TerraVision MCP tools are available, use them

If you can call diagram_guide and render_graph (the TerraVision MCP server), use them instead of the command line, and skip Install, the validator, and the files under references/ and examples/:

• diagram_guide(provider) returns, in one call, the graph rules, a detailed worked example, the supported node types, a library of patterns and whether Graphviz is installed.
• render_graph(graph, outfile="three_tier", title=...) checks the graph, returns warnings and a preview image, and saves the PNG, SVG, draw.io file and graph. Pass outfile as a name; files always go to the server's output folder.

Everything else here still applies: the rules, "Drawn as written", "Check every render" and "Deliver the result".

Decide which path

Path B needs only Graphviz and Git. Path A also needs Terraform (or OpenTofu) on PATH.

Install (once)

Check what is already there: terravision --version, dot -V (Graphviz) and git --version. All three are needed, even for a JSON graph. Install only what is missing, and ask the user before installing anything system-wide.

TerraVision needs Python 3.11 or newer. Use the first installer that exists on the machine:

If terravision is installed but not found, its folder is not on PATH: run uv tool update-shell or pipx ensurepath and open a new terminal, or call it by its full path.

Graphviz and Git:

After a winget install, dot -V in a terminal still reports not found, because that installer does not add Graphviz to PATH. That is expected: TerraVision 0.48.2 and later find C:\Program Files\Graphviz\bin by themselves. To confirm Graphviz is installed, check that dot.exe exists there instead of running dot -V.

Terraform, for Path A only. A JSON graph never runs Terraform. For Terraform code, check terraform version (must be 1.x); OpenTofu works too (tofu version, then add --engine tofu). To install Terraform:

OpenTofu for other systems: https://opentofu.org/docs/intro/install/

TerraVision runs terraform init and terraform plan on the user's code, so the plan needs whatever the user normally plans with: network access for providers and modules, and often cloud credentials. If that is not possible here, ask the user to run these where their Terraform works, then use Path A with --planfile plan.json --graphfile graph.dot:

terraform init && terraform plan -out=tfplan.bin
terraform show -json tfplan.bin > plan.json
terraform graph > graph.dot

Path A: from Terraform code

terravision draw --source ./path/to/terraform --format svg --outfile architecture

Useful flags: --title "Payments - Production", --varfile prod.tfvars, --workspace staging, --simplified (services only, no networking boxes), --format drawio (editable), --planfile plan.json --graphfile graph.dot (use an existing plan, no cloud credentials needed).

For an interactive page to explore in a browser (click any resource to see its settings, search, zoom): terravision visualise --source ./tf --show.

If the user only wants the structure as data: terravision graphdata --source ./tf --outfile architecture.tvg.json.

Git repositories work as the source too, public or private (with the user's Git access): --source https://github.com/org/repo, or https://github.com/org/repo//examples for a folder inside it. Many repositories hold a reusable module at their root, which plans no resources on its own. If the root fails with "found no resources" or asks for required variables, look in the repository for a folder that uses the module (examples/, environments/prod, anything with a provider block) and draw that with //folder.

Path B: from a JSON graph (no Terraform)

1. Write a JSON object where each key is a node address <terraform_resource_type>.<name> and each value is the list of node addresses it connects to or contains. Read references/graph-format.md for the full rules and references/node-types.md when unsure which type to use.

2. Save it as <name>.tvg.json in the user's current working directory, or a folder they name. The diagram files are the deliverable, so never put them in a temporary folder.

3. Render a PNG to look at and a draw.io file to edit:

   terravision draw --source <name>.tvg.json --format png --outfile <name> --title "Order Platform"
   terravision draw --source <name>.tvg.json --format drawio --outfile <name> --title "Order Platform"

   They are written as <name>.dot.png and <name>.drawio. Add --format svg as well if the user wants to embed it in documentation.

4. Check the PNG ("Check every render" below), then deliver it ("Deliver the result" at the end).

Minimal example:

{
  "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"],
  "aws_group.shared_services": ["aws_cloudwatch_log_group.orders"]
}

Rules that matter most:

• One provider per graph. Type prefixes select the provider and icon: aws_*, azurerm_*, google_*. Mixing them is an error; draw one diagram per provider.
• Pick the specific type. aws_alb or aws_nlb, not aws_lb. aws_ecs_fargate for Fargate, not aws_ecs_service. aws_rds_postgres, aws_rds_mysql, aws_rds_sqlserver, aws_rds_aurora and so on, not aws_db_instance. aws_eks_service for an EKS cluster.
• Containers list their children as targets: aws_vpc, aws_subnet, tv_aws_az, azurerm_resource_group, azurerm_virtual_network, azurerm_subnet, google_compute_network, google_compute_subnetwork, tv_gcp_region, tv_gcp_zone. These are containers too, though they read like services: aws_autoscaling_group, aws_security_group, google_container_cluster, google_container_node_pool, google_compute_instance_group, google_compute_firewall. Anything they list is drawn inside them. The full list is in references/graph-format.md.
• External actors: tv_aws_users.<name>, tv_aws_internet.<name>, tv_aws_mobile_client.<name>, tv_aws_onprem.<name>, tv_azurerm_users.<name>, tv_azurerm_internet.<name>, tv_gcp_users_icon.<name> (plain tv_gcp_users draws a group box, not an icon).
• Numbered copies: aws_subnet.private~1, aws_subnet.private~2. Always point at the copies, never the unnumbered name, or an extra node can appear.
• Names become labels: use lowercase snake_case (orders_table, not Orders-Table).
• Leaf nodes may be omitted as keys.

Drawn as written

TerraVision draws the graph exactly as written; it does not add, move or group nodes for you. These drawing rules explain most surprises:

• Shared services have no arrows. Arrows to or from CloudWatch log groups, ECR, ACM, KMS, SSM parameters, EFS and EIPs (Azure: Key Vault, Monitor, Log Analytics, ACR, storage accounts; GCP: KMS, logging sinks, monitoring, GCR, Secret Manager) are not drawn. On AWS and Azure, list them in aws_group.shared_services or azurerm_group.shared_services so they appear together in a Shared Services box instead of floating.
• Arrows to a container are not drawn. Point at a node inside it instead.
• A node sits in one container. A name is drawn once, so it cannot be listed in two boxes. A resource spanning several subnets or zones needs a numbered copy in each (aws_alb.web~1, aws_alb.web~2). Inside nested boxes, list it only in the innermost (its subnet), not also in the network or resource group around it.
• Network-attached services go in their subnet. A Lambda in a VPC, an Azure Function with VNet integration, a private endpoint: draw each inside the subnet it attaches to.
• Arrows follow the real path. Through a private endpoint, VPC endpoint, NAT gateway, proxy or firewall, draw source → intermediary → destination and no direct arrow.
• Two-way connections draw one arrow. List the main direction of flow only.
• Nesting is literal. Keep CloudFront, Route 53, API Gateway, WAF and external actors at the top level, not inside a VPC or subnet. Empty containers are not drawn.
• Unknown or misspelt types draw a blank icon without an error. Check them against references/node-types.md.

Worked examples in examples/: three-tier web apps for each cloud (three-tier-web.tvg.json for AWS, azure-three-tier.tvg.json, gcp-three-tier.tvg.json), plus aws-event-driven.tvg.json, azure-web-app.tvg.json and gcp-serverless-api.tvg.json. Copy the closest one, keep its level of detail (zones, public and private subnets, the path to the internet, shared services) and edit. For other service mixes, examples/patterns/ holds 26 more (EKS, ECS, API Gateway, Step Functions, SageMaker, Glue, GKE, AKS and others), listed with descriptions in examples/patterns/index.json. They are TerraVision's own output for real Terraform, so following them keeps its level of detail.

Validate before rendering: python scripts/validate_graph.py architecture.tvg.json. It fails on bad addresses or mixed providers, and prints a WARNING for anything in the list above that will not draw the way it reads. Fix the warnings, or accept them if they are intended.

If you have the TerraVision MCP server

Call render_graph with the graph object directly (no file needed), or generate_diagram with a Terraform source. Both take an optional title, optional flows (numbered steps; see "Flows" below) and optional edge_labels (a few words on existing arrows, rule 11 in references/graph-format.md); render_graph also takes attributes, to give networks and subnets realistic CIDR ranges (rule 10). Each call saves a PNG, an SVG, an editable draw.io file and the graph as .tvg.json, and returns their paths under files plus a preview image of the diagram: look at it to check the diagram ("Check every render" below). In apps that support MCP Apps, such as Claude Desktop, VS Code and Cursor, the user also sees the diagram in an interactive view with buttons to open, edit and copy it. Elsewhere, call open_diagram_file with the PNG path to open it for the user, instead of running open or xdg-open yourself. If the result has warnings (an unknown type with suggested replacements, arrows that will not be drawn), fix the graph and render again.