patrickchugh/terravision/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, the gallery of designs, a library of patterns and whether Graphviz is installed. diagram_guide(provider, example=<name>) returns one gallery design with its title, CIDR ranges, labels and flows as render_graph arguments.
• 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:

``bash 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.

1. 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_* (with azuread_* for Entra ID), 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). For systems outside AWS: tv_aws_server.<name>, tv_aws_client.<name> (a workstation) and tv_aws_database.<name>.
• Hybrid networks (AWS): draw the data centre as a tv_aws_onprem box, outside the AWS Cloud, holding its servers, workstations and databases and its router as aws_customer_gateway. Direct Connect runs aws_customer_gateway → aws_dx_connection → aws_dx_gateway → aws_ec2_transit_gateway (or a virtual private gateway); a site-to-site VPN runs aws_customer_gateway → aws_vpn_connection → the Transit Gateway. examples/aws-multi-account-network.tvg.json shows both, with central inspection and egress.
• 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: