TFPlanBuilder

Visualize your terraform plan as an animated city skyline — buildings rise with cranes, get renovated with scaffolding, or demolished with wrecking balls.

Built end-to-end with Kiro IDE to show how an AI-powered development environment architects a complete solution: from container packaging and modular Terraform to a zero-dependency CLI tool and CI/CD pipeline.

---

Demo

# Quickest way to try it (from the cli/ directory)cd cli && npx . --file examples/sample-plan.json

Or pipe a real plan:

cd infra
terraform show -json plan.tfplan | npx ../cli

---

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│ AWS Cloud │
│ │
│ ┌──────────── VPC (10.0.0.0/16) ────────────────────────────────┐ │
│ │ │ │
│ │ ┌─── Public Subnets ───┐ ┌─── Private Subnets ───┐ │ │
│ │ │ │ │ │ │ │
│ │ │ ┌──────────────┐ │ │ ┌────────────────┐ │ │ │
│ │ │ │ ALB (managed)│───│────│──▶│ ECS Fargate │ │ │ │
│ │ │ │ HTTPS/TLS │ │ │ │ (Express Mode)│ │ │ │
│ │ │ └──────────────┘ │ │ └────────────────┘ │ │ │
│ │ │ │ │ │ │ │ │
│ │ │ ┌──────────────┐ │ │ ┌──────▼─────────┐ │ │ │
│ │ │ │ NAT Gateway │◀──│────│───│ nginx:8080 │ │ │ │
│ │ │ └──────────────┘ │ │ │ (static app) │ │ │ │
│ │ └──────────────────────┘ │ └────────────────┘ │ │ │
│ │ └────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────┐ ┌──────────────────────────────────────┐ │
│ │ ECR │ │ Managed by ECS Express Mode: │ │
│ │ (images) │ │ • Auto-scaling (request-count based) │ │
│ └─────────────┘ │ • TLS certificates (ACM) │ │
│ │ • Target groups & health checks │ │
│ │ • Canary deployments │ │
│ │ • CloudWatch Logs │ │
│ └──────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘

Project Structure

tfplanbuilder/
├── .kiro/ # Kiro IDE configuration
│ ├── steering/ # Project rules & conventions
│ │ ├── project-conventions.md # Always-on coding standards
│ │ ├── terraform-patterns.md # Active when editing *.tf files
│ │ └── docker-guidelines.md # Active when editing Dockerfiles
│ └── specs/tfplanbuilder/ # Spec-driven development docs
│ ├── requirements.md # Functional & non-functional reqs
│ ├── design.md # Architecture & component design
│ └── tasks.md # 52 implementation tasks
│
├── app/ # Container application
│ ├── Dockerfile # nginx:alpine, non-root, health check
│ ├── nginx.conf # Production static server + /ping
│ ├── index.html # The skyline visualization
│ └── .dockerignore
│
├── cli/ # CLI tool (npx tfplanbuilder)
│ ├── bin/tfplanbuilder.js # Zero-dependency Node.js CLI
│ ├── web/index.html # Same visualization, auto-loads plan
│ ├── examples/sample-plan.json # 12-resource sample plan
│ ├── package.json # npm package config
│ └── README.md
│
├── infra/ # Terraform infrastructure
│ ├── main.tf # Root config — wires modules
│ ├── variables.tf # All inputs with validation
│ ├── outputs.tf # Service URL, ECR URL, cluster
│ ├── versions.tf # Provider constraints + S3 backend
│ ├── terraform.tfvars.example # Copy → terraform.tfvars
│ └── modules/
│ ├── networking/ # VPC, subnets, NAT, route tables
│ ├── ecr/ # Container registry + lifecycle
│ └── ecs-express/ # ECS Express Gateway + IAM roles
│
├── .github/workflows/deploy.yml # CI/CD: build → ECR → plan → apply
├── Makefile # Developer commands
├── .gitignore
└── BLOG.md # Companion blog post

---

Quick Start

Option 1: CLI (local, no infrastructure needed)

# Run with the included sample using npx (from the cli/ directory)cd cli
npx . --file examples/sample-plan.json
# Or run directly with node
node cli/bin/tfplanbuilder.js --file cli/examples/sample-plan.json

Pipe a real terraform plan:

cd infra
terraform plan -out=plan.tfplan
terraform show -json plan.tfplan | npx ../cli

Install globally (so tfplanbuilder works anywhere):

cd cli
npm link

Then use it directly:

terraform show -json plan.tfplan | tfplanbuilder
tfplanbuilder --file plan.json

Browser opens at http://127.0.0.1:3333 with the visualization auto-playing.

Option 2: Docker (local container)

make run
# → http://localhost:8080 — paste any plan text or JSON

Option 3: Deploy to AWS (hosted version)

cd infra
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars
terraform init
terraform apply
# Push the app imagecd .. && make push IMAGE_TAG=v1.0.0
# Deploy with the new imagecd infra && terraform apply -var="container_image_tag=v1.0.0"# Get the URL
terraform output service_endpoint

---

CLI Reference

tfplanbuilder — Visualize terraform plans as an animated city skyline
USAGE:
terraform show -json plan.tfplan | tfplanbuilder
tfplanbuilder --file plan.json
OPTIONS:
--file <path> Read plan JSON from a file instead of stdin
--port <num> Port for the local server (default: 3333)
--no-open Don't auto-open the browser
-h, --help Show this help

Aliases:tfplanbuilder, tfpb

---

How the Visualization Works

Action	Animation	Color
Create	Crane lifts a new building	Green
Update	Scaffolding wraps the building	Amber
Replace	Demolished then rebuilt	Amber
Destroy	Wrecking ball, dust, rubble	Red

Provider colors: AWS (orange), Azure (blue), GCP (green), Other (gray)

Click any building to open the inspector panel showing:

• Resource address, type, provider, module path
• Attribute diff (old → new values) when using JSON plan input

---

Infrastructure (ECS Express Mode)

This project uses ECS Express Mode (launched Nov 2025) — you provide a container image and two IAM roles, and Express Mode handles everything else:

• Application Load Balancer with HTTPS/TLS
• Auto-scaling (request-count, CPU, or memory based)
• Security groups and target groups
• Canary deployments
• CloudWatch Logs

The Terraform is modular:

• modules/networking — VPC with public/private subnets across 2 AZs
• modules/ecr — Container registry with lifecycle policies and scan-on-push
• modules/ecs-express — ECS cluster, IAM roles, Express Gateway Service

---

CI/CD

The GitHub Actions workflow (.github/workflows/deploy.yml) runs on push to main:

1. Build — Docker image from app/
2. Push — To ECR with sha-<commit> tag
3. Plan — terraform plan with the new image tag
4. Apply — Deploys to ECS Express (main branch only)

On PRs, it runs plan-only so reviewers can see infrastructure changes.

Required secret:AWS_DEPLOY_ROLE_ARN (GitHub OIDC federation — no long-lived credentials)

---

Make Commands

make help# Show all commands
make build # Build Docker image locally
make run # Run on localhost:8080
make plan # Terraform plan
make apply # Terraform apply
make push # Build + push to ECR
make destroy # Tear down infrastructure
make fmt # Format Terraform files
make lint # Validate Terraform
make clean # Remove local artifacts

---

Cost Estimate

Resource	Monthly Cost
ECS Fargate (512 CPU / 1GB, 1 task)	~$15
NAT Gateway	~$32 + data
ALB (shared, managed by Express Mode)	~$0 incremental
ECR	< $1

Set enable_nat_gateway = false for demos to save ~$32/month.

---

Built with Kiro IDE

This entire project — architecture, infrastructure, application, CLI tool, and CI/CD — was designed and implemented in a single Kiro session. Read the companion blog post for the full story.

---

Teardown

make destroy
# orcd infra && terraform destroy