patrickchugh/terravision / skills/terravision-cloud-diagrams
terravision-cloud-diagrams
VerifiedDraw cloud architecture diagrams for AWS, Azure or GCP with the official provider icon sets, using TerraVision. Use whenever the user asks to draw, diagram, sketch or visualize a system on AWS, Azure or Google Cloud, or one built from their services (Lambda, DynamoDB, S3, EC2, EKS, RDS, API Gateway, Azure Functions, App Service, AKS, Cosmos DB, Cloud Run, GKE, BigQuery and the like), even if they never say 'cloud', 'diagram' or a tool name; also for a diagram of Terraform code. Prefer it over Mermaid, PlantUML, hand-written SVG or ASCII, which cannot use the official icons or VPC/subnet grouping. Not for diagrams that are not cloud infrastructure: sequence diagrams, flowcharts, class or ER diagrams, code or module structure, org charts, on-premises-only networks; use Mermaid or similar for those. Works with or without Terraform: with Terraform code the diagram comes from terraform plan; without it, write a small JSON graph and render it.
scripts/validate_graph.py
View on GitHub#!/usr/bin/env python3
"""Validate a TerraVision graph JSON file against the TVG 1.0 rules.
Usage: python validate_graph.py architecture.tvg.json
Exits 1 with a list of errors when the graph cannot be drawn. Otherwise
exits 0, first printing warnings for things that will draw differently from
what was probably meant. No dependencies.
"""
import difflib
import json
import re
import sys
from pathlib import Path
# Keep identical to the pattern in references/terravision-graph.schema.json
# and modules/mcp_service.py; a test compares all three.
ADDRESS = re.compile(
r"^(module\.[A-Za-z0-9_-]+(\[[^\]]+\])?\.)*[a-z][a-z0-9_]*\.[A-Za-z0-9_-]+(\[[^\]]+\])*(~[0-9]+)?$"
)
MODULE_PATH = re.compile(r"^(module\.[A-Za-z0-9_-]+(\[[^\]]+\])?\.)+")
# Resource type prefix -> provider. Keep identical to TV_PROVIDER_PREFIXES and
# PROVIDER_PREFIXES in modules/provider_detector.py; a test compares them.
PROVIDER_PREFIXES = {
"tv_aws_": "aws",
"tv_azurerm_": "azure",
"tv_azure_": "azure",
"tv_gcp_": "gcp",
"aws_": "aws",
"azurerm_": "azure",
"azuread_": "azure",
"azurestack_": "azure",
"azapi_": "azure",
"google_": "gcp",
}
RESOURCE_PREFIX = {"aws": "aws_", "azure": "azurerm_", "gcp": "google_"}
# Drawing rules, copied from modules/config/cloud_config_<provider>.py so this
# script runs without TerraVision installed; a test keeps them identical.
# Types drawn as boxes around the nodes they list (<PROVIDER>_GROUP_NODES).
CONTAINER_TYPES = {
"aws_vpc", "aws_az", "tv_aws_az", "aws_group", "aws_account", "aws_appautoscaling_target",
"aws_autoscaling_group", "aws_subnet", "aws_security_group", "tv_aws_onprem",
"tv_aws_region",
"azurerm_resource_group", "azurerm_group", "azurerm_virtual_network",
"azurerm_subnet", "tv_azurerm_zone", "tv_azure_onprem", "tv_azurerm_region",
"tv_azure_entra",
"tv_gcp_account", "google_project", "tv_gcp_users", "tv_gcp_system",
"tv_gcp_infra_system2", "tv_gcp_onprem", "tv_gcp_external_saas",
"tv_gcp_external_data", "tv_gcp_external_3p", "tv_gcp_external_1p",
"tv_gcp_load_balancer", "google_compute_network", "tv_gcp_logical_group",
"tv_gcp_region", "google_container_cluster", "google_compute_subnetwork",
"tv_gcp_zone", "google_compute_firewall", "google_compute_instance_group",
"tv_gcp_replica_pool", "google_container_node_pool", "tv_gcp_k8s_pod",
"tv_gcp_optional",
} # fmt: skip
# Arrows to or from these are not drawn (<PROVIDER>_SHARED_SERVICES) ...
SHARED_SERVICES = {
"aws_acm_certificate", "aws_cloudwatch_log_group", "aws_ecr_repository",
"aws_efs_file_system", "aws_ssm_parameter", "aws_kms_key", "aws_eip",
"aws_secretsmanager",
"azurerm_key_vault", "azurerm_monitor", "azurerm_log_analytics_workspace",
"azurerm_container_registry", "azurerm_storage_account",
"google_kms_key_ring", "google_logging_project_sink",
"google_monitoring_dashboard", "google_container_registry",
"google_secret_manager_secret",
} # fmt: skip
# ... except arrows into them from these (<PROVIDER>_ALWAYS_DRAW_LINE).
ALWAYS_DRAW_LINE = {
"aws_lb", "aws_iam_role", "aws_volume_attachment", "aws_alb", "aws_nlb", "aws_gwlb",
"aws_efs_access_point", "aws_efs_mount_target", "aws_ecs_service",
"aws_rds_aurora", "aws_rds_mysql", "aws_rds_postgres",
"azurerm_load_balancer", "azurerm_application_gateway",
"azurerm_network_interface", "azurerm_virtual_machine_scale_set",
"azurerm_kubernetes_cluster",
"google_compute_forwarding_rule", "google_compute_backend_service",
"google_container_node_pool", "google_compute_instance_group",
} # fmt: skip
# Identities: an arrow from one is a permission, drawn dashed and drawn even
# into a shared service (<PROVIDER>_PERMISSION_SOURCES)
PERMISSION_SOURCES = {
"azurerm_user_assigned_identity", "azuread_group", "azuread_service_principal",
"azuread_user",
} # fmt: skip
# Drawn as a line between two network boxes rather than an icon
# (<PROVIDER>_GROUP_LINKS), with the kind of box each one links. List one in
# its own network, pointing at the network it connects to.
GROUP_LINKS = {
"aws_vpc_peering_connection": "aws_vpc",
"azurerm_virtual_network_peering": "azurerm_virtual_network",
"google_compute_network_peering": "google_compute_network",
}
# Plumbing TerraVision keeps in a graph but never draws (<PROVIDER>_HIDE_NODES):
# route tables, IAM grants, bucket settings and the like. Arrows to and from
# them are not drawn either.
HIDDEN_TYPES = {
"aws_appautoscaling_policy", "aws_db_subnet_group", "aws_default_network_acl",
"aws_default_route_table", "aws_default_security_group",
"aws_ec2_transit_gateway_route", "aws_ec2_transit_gateway_route_table",
"aws_ec2_transit_gateway_route_table_association",
"aws_ec2_transit_gateway_route_table_propagation", "aws_ecr_lifecycle_policy",
"aws_elasticache_subnet_group", "aws_iam_access_key", "aws_iam_account_alias",
"aws_iam_account_password_policy", "aws_iam_group_policy_attachment",
"aws_iam_instance_profile", "aws_iam_user_login_profile", "aws_lambda_permission",
"aws_networkfirewall_firewall_policy", "aws_networkfirewall_rule_group",
"aws_route", "aws_route_table", "aws_s3_bucket_acl",
"aws_s3_bucket_lifecycle_configuration", "aws_s3_bucket_logging",
"aws_s3_bucket_notification", "aws_s3_bucket_policy",
"aws_s3_bucket_public_access_block", "aws_s3_bucket_replication_configuration",
"aws_s3_bucket_server_side_encryption_configuration", "aws_s3_bucket_versioning",
"aws_s3_bucket_website_configuration", "aws_security_group_rule",
"aws_sqs_queue_policy", "aws_vpc_dhcp_options", "aws_vpc_dhcp_options_association",
"aws_vpc_security_group_egress_rule", "aws_vpc_security_group_ingress_rule",
"azuread_access_package_assignment_policy",
"azuread_access_package_catalog_role_assignment",
"azuread_access_package_resource_catalog_association",
"azuread_access_package_resource_package_association",
"azuread_administrative_unit_member", "azuread_administrative_unit_role_member",
"azuread_app_role_assignment", "azuread_application_api_access",
"azuread_application_app_role", "azuread_application_certificate",
"azuread_application_fallback_public_client",
"azuread_application_federated_identity_credential",
"azuread_application_flexible_federated_identity_credential",
"azuread_application_identifier_uri", "azuread_application_known_clients",
"azuread_application_optional_claims", "azuread_application_owner",
"azuread_application_password", "azuread_application_permission_scope",
"azuread_application_pre_authorized", "azuread_application_redirect_uris",
"azuread_authentication_strength_policy_fido2_combination_configuration",
"azuread_authentication_strength_policy_x509_combination_configuration",
"azuread_claims_mapping_policy", "azuread_directory_role_assignment",
"azuread_directory_role_eligibility_schedule_request",
"azuread_directory_role_member", "azuread_group_license", "azuread_group_member",
"azuread_group_role_management_policy", "azuread_named_location",
"azuread_privileged_access_group_assignment_schedule",
"azuread_privileged_access_group_eligibility_schedule",
"azuread_service_principal_certificate",
"azuread_service_principal_claims_mapping_policy_assignment",
"azuread_service_principal_delegated_permission_grant",
"azuread_service_principal_password",
"azuread_service_principal_token_signing_certificate",
"azuread_synchronization_job_provision_on_demand",
"azuread_synchronization_secret", "azuread_user_flow_attribute",
"azuread_user_license", "azurerm_network_interface_security_group_association",
"azurerm_network_security_rule", "azurerm_role_assignment",
"azurerm_role_definition", "azurerm_route",
"azurerm_subnet_network_security_group_association",
"azurerm_virtual_network_peering", "google_cloud_run_service_iam_member",
"local_file", "null_resource", "random_password", "random_string",
"terraform_data", "time_sleep",
} # fmt: skip
SHARED_GROUP = {
"aws": "aws_group.shared_services",
"azure": "azurerm_group.shared_services",
}
NODE_TYPES_FILE = (
Path(__file__).resolve().parent.parent / "references" / "node-types.md"
)
def type_of(node):
return MODULE_PATH.sub("", node).split(".")[0]
def name_of(node):
name = MODULE_PATH.sub("", node).split(".", 1)[1]
return re.sub(r"(\[[^\]]*\])+|~[0-9]+$", "", name)
def base_of(node):
return re.sub(r"(\[[^\]]*\])*(~[0-9]+)?$", "", node)
def provider_of(node):
resource_type = type_of(node)
for prefix, provider in PROVIDER_PREFIXES.items():
if resource_type.startswith(prefix):
return provider
return None
def known_types():
try:
return set(re.findall(r"`([a-z][a-z0-9_]*)`", NODE_TYPES_FILE.read_text()))
except OSError:
return None
def validate(graph):
problems = []
if not isinstance(graph, dict) or not graph:
return ["Top level must be a non-empty JSON object."]
for node, targets in graph.items():
if not ADDRESS.match(node):
problems.append(f"Bad node address: {node!r} (expected '<type>.<name>')")
if not isinstance(targets, list):
problems.append(f"{node!r}: value must be a list of node addresses")
continue
for t in targets:
if not isinstance(t, str) or not ADDRESS.match(t):
problems.append(f"{node!r}: bad target address {t!r}")
if len(set(targets)) != len(targets):
problems.append(f"{node!r}: duplicate targets")
providers = {
provider_of(node)
for node in set(graph)
| {t for v in graph.values() if isinstance(v, list) for t in v}
if isinstance(node, str) and provider_of(node)
}
if len(providers) > 1:
prefixes = [f"{RESOURCE_PREFIX[p]}*" for p in sorted(providers)]
problems.append(
f"Graph mixes {', '.join(prefixes[:-1])} and {prefixes[-1]} "
"resources; use one cloud provider per graph."
)
return problems
def suggestions(resource_type, candidates, limit=3):
"""Closest supported types: those containing every word first, then typos.
``google_sql_instance`` finds ``google_sql_database_instance`` (every
word matches, one is extra); ``aws_lamda_function`` finds
``aws_lambda_function`` by spelling.
"""
words = set(resource_type.split("_"))
containing = sorted((t for t in candidates if words <= set(t.split("_"))), key=len)
similar = difflib.get_close_matches(resource_type, candidates, n=limit)
return list(dict.fromkeys(containing + similar))[:limit]
def warnings(graph):
"""Things that draw, but not the way the author probably meant.
Call only on a graph that validate() accepts.
"""
found = []
# Hidden types are not drawn, nor are their arrows, so they cannot draw
# differently from what was meant. Graphs exported from Terraform keep them.
# Peerings are hidden as icons but drawn as lines, so they are still checked.
hidden = HIDDEN_TYPES - set(GROUP_LINKS)
graph = {
src: [dst for dst in targets if type_of(dst) not in hidden]
for src, targets in graph.items()
if type_of(src) not in hidden
}
nodes = set(graph) | {t for v in graph.values() for t in v}
edges = [
(src, dst)
for src, targets in graph.items()
if type_of(src) not in CONTAINER_TYPES
for dst in targets
]
known = known_types()
if known is not None:
drawn_as_icons = {type_of(n) for n in nodes} - set(GROUP_LINKS)
for resource_type in sorted(drawn_as_icons - known):
provider = provider_of(resource_type + ".x")
if provider:
close = suggestions(
resource_type,
[t for t in known if provider_of(t + ".x") == provider],
)
hint = f" Did you mean {' or '.join(close)}?" if close else ""
found.append(
f"Unknown type {resource_type!r} draws a blank icon.{hint} "
"Use a type from the supported node types list."
)
for src, dst in edges:
if GROUP_LINKS.get(type_of(src)) == type_of(dst):
continue # a peering pointing at the network it connects to
if type_of(dst) in CONTAINER_TYPES:
found.append(
f"Arrow {src} -> {dst} is not drawn: {type_of(dst)} is a "
"container. Point at a node inside it."
)
hidden = {}
for src, dst in edges:
if type_of(src) in PERMISSION_SOURCES:
continue # a permission, drawn into the shared service
if type_of(src) in SHARED_SERVICES:
hidden.setdefault(src, []).append(dst)
elif (
type_of(dst) in SHARED_SERVICES
and type_of(src) not in ALWAYS_DRAW_LINE
and type_of(dst) not in CONTAINER_TYPES
):
hidden.setdefault(dst, []).append(src)
for shared, others in sorted(hidden.items()):
group = SHARED_GROUP.get(provider_of(shared))
if group and shared in graph.get(group, []):
continue # grouped on purpose, so hidden arrows are expected
hint = (
f" List it in {group} to draw it in the Shared Services box."
if group
else ""
)
found.append(
f"Arrows between {shared} and {', '.join(sorted(others))} are not "
f"drawn: {type_of(shared)} is a shared service.{hint}"
)
parents = {}
for src, targets in graph.items():
if type_of(src) in CONTAINER_TYPES:
for t in targets:
parents.setdefault(t, []).append(src)
for node in sorted(n for n in nodes if type_of(n) in GROUP_LINKS):
network = GROUP_LINKS[type_of(node)]
own = [b for b in parents.get(node, []) if type_of(b) == network]
remote = [t for t in graph.get(node, []) if type_of(t) == network]
if not own or not remote or set(own) & set(remote):
found.append(
f"{node} is drawn as a line between two {network} boxes, so "
f"list it in its own {network} and have it list the other: "
f'"{network}.a": [..., "{node}"], "{node}": ["{network}.b"]. '
"Otherwise it is not drawn."
)
def boxes_around(box):
seen, queue = set(), list(parents.get(box, []))
while queue:
outer = queue.pop()
if outer not in seen:
seen.add(outer)
queue.extend(parents.get(outer, []))
return seen
for node, boxes in sorted(parents.items()):
if len(boxes) < 2:
continue
# A box that already holds another of the node's boxes (a resource
# group around its subnet) is the listing to drop, not the inner one.
outer = [b for b in boxes if any(b in boxes_around(o) for o in boxes)]
inner = [b for b in boxes if b not in outer]
if outer and inner:
found.append(
f"{node} is listed in {', '.join(inner)} and also in "
f"{', '.join(outer)}, which already contains "
f"{'it' if len(inner) == 1 else 'them'}. Remove {node} from "
f"{', '.join(outer)} and keep it in {', '.join(inner)}."
)
if len(inner) != 1:
found.append(
f"{node} is listed in {', '.join(inner or boxes)} but is drawn "
"in only one of them; use numbered copies (~1, ~2) for one per "
"container."
)
numbered = {base_of(n) for n in nodes if re.search(r"~[0-9]+$", n)}
for src, dst in edges:
if dst in numbered:
found.append(
f"{src} points at {dst}, which has numbered copies; point at "
f"{dst}~1, {dst}~2 ... or an extra node can appear."
)
for node in sorted(nodes):
if re.search(r"[A-Z-]", name_of(node)):
found.append(
f"{node}: use a lowercase snake_case name; hyphens and capitals "
"are mangled in the label."
)
return found
if __name__ == "__main__":
if len(sys.argv) != 2:
print(__doc__)
sys.exit(2)
with open(sys.argv[1]) as fh:
data = json.load(fh)
issues = validate(data)
if issues:
print("\n".join(issues))
sys.exit(1)
for warning in warnings(data):
print(f"WARNING: {warning}")
nodes = set(data) | {t for v in data.values() for t in v}
print(f"OK: {len(nodes)} nodes, {sum(len(v) for v in data.values())} edges")
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |