Cloud Topology Toolkit, spec-driven infrastructure visualization

Role creator · Where: Metafora / CarrierDirect · Built: June–July 2026 Stack: Python · Cytoscape.js SPA · Terraform / Helm / Kubernetes / Steampipe producers · Docker (GHCR) · GitHub Actions

Terraform-first, multi-cloud, intermediate-representation-based infrastructure visualization. One IR in the middle; many producers feeding it and many renderers reading it: SVG, PNG, Mermaid architecture-beta, draw.io XML, Structurizr DSL, D2, PDF, and an interactive SPA.

It started as a logistics client's tf-topology spike: a single-purpose terraform graph post-processor shipped in a container for GitHub Actions. This repo is the deliberate successor, the IR + multi-view + multi-renderer architecture the spike grew out of.

How it was built, the AI angle

Cloud Topology Toolkit is the clearest example here of agents working the issue queue rather than sitting in an editor.

117 commits authored directly by GitHub Copilot's coding agent (copilot-swe-agent[bot] and Copilot): real issues, assigned to an agent, that came back as reviewable PRs.
Spec-driven, with a constitution. Numbered issues drive numbered features (#323 producer protocol, #328/#335 Kubernetes & Helm, #342/#359 Steampipe live state, #350 multi-source correlation). Constitution Principle IV, absence of correlation is observable, never faked, is the kind of rule that keeps a generative pipeline honest: when two planes don't correlate, both uncorrelated sides get named in metadata.notes rather than being quietly merged.
Golden tests as the guardrail. The snapshot → IR mapping is pure and content-hash golden-tested offline. A hardened CI matrix runs producers, CLI, and golden tests separately after a gap let producer-layer regressions land green, the sort of failure you only find by looking for it.
The AI advisor is opt-in and offline by default. advise / /api/advise turns structural findings into remediation, BYO-key, behind an extra. AI in the product, not just in the building of it, but never silently phoning home.

Measured 630 commits across all branches in ~3.5 weeks, 538 of them (85%) AI-attributed, carrying an AI co-author trailer or authored by an agent outright.

The screens

All screenshots render bundled synthetic fixtures (medium_composition, large_composition, plan_diff_pair), no customer infrastructure.

Network view, topology as network gear

Cloud Topology Toolkit network view: a resource-group container holding compute racks, a VNet of 1U subnet switch faceplates with RJ45 port banks and a directional flow rail, NSG appliance racks, and edge-kinded patch cables

Toggle Network and containment boxes become a directional traffic canvas. Each resource group is a container holding its compute racks (a VM shows its OS + data disks and one RJ45 port per NIC), its VNet of thin 1U subnet switch faceplates with vertical port banks and a flow rail threading traffic through the NSG → NAT → route policy chain, its edge resources outside the VNet frame, and its service racks.

The detail that matters is what it does with uncertainty. Hops Azure performs but never declares (platform SNAT, an AKS-managed load balancer, private DNS) are inferred and drawn as dashed "not in plan" appliances. The picture tells you what Terraform said and what Azure will actually do.

Containment + info cards

The SPA containment view: Resource Group inside VNet inside Subnet, Container-App Environment, and Key Vault with its secrets, each rendered as a titled box with icon-name-type leaf cards

Each container (Resource Group › VNet › Subnet, Container-App Environment, Key Vault › secrets) renders as a box with a corner title card; leaf resources are icon · name · type cards inside. Filter chips dim non-matching leaves while container boxes stay as scaffolding, and the active filter is URL-shareable.

Plan diff, base → head

Plan-diff view showing added, removed, and changed resources with colored borders plus a before/after attribute panel

Added / removed / changed borders, plus a before/after attribute panel. This is the view that turns a 4,000-line terraform plan into something a reviewer can actually approve.

Multi-source correlation

Correlation view: a Terraform-declared AKS cluster matched by name to its live Kubernetes cluster, with live namespaces and workloads nested underneath

v0.6 added a producer seam so the same IR can be fed from Terraform plans, Helm charts, live Kubernetes, and live cloud state. Correlation stitches a Terraform-declared AKS/EKS/GKE cluster to the live workloads running inside it, by name, and nests the live namespaces under the Terraform resource group. No match, and the planes sit side by side with both uncorrelated sides named, never faked into agreement.

Traffic overlay

Topology view with a traffic overlay coloring resources and edges by flow

Static exports carry the same semantics as the SPA: a post-grouping classifier types every edge network / data / iam / dependency, and each renderer styles them consistently.

Why it matters

Architecture diagrams rot the day after the review. This one is generated from the plan, the chart, or the live cluster, and when it can't verify a relationship it says so instead of drawing a confident line.