From Terraform to Architecture Diagrams — Without Sharing the Code

Why AWS architecture diagrams usually fail

Most infrastructure diagrams do not fail because they are poorly drawn. They fail because they are manually maintained: created early, updated rarely, and trusted long after they stop being accurate. As infrastructure evolves, the diagrams drift from reality and become decorative artifacts.

In Infrastructure as Code projects, the most accurate description of the system already exists: Terraform.

Diagrams should be generated, not maintained

Terraform encodes system boundaries, environment separation, ownership domains, governance and cost controls, and behavioral differences through variables. An architecture diagram is a projection of that information. The practical problem is therefore how to interpret Terraform as an architectural language.

The constraint: do not share infrastructure code

Real Terraform code is usually not appropriate to share with external tools because of security, compliance, intellectual-property, production-exposure, and audit requirements. The question was whether accurate diagrams could be generated without sharing the code.

Interpret architecture, not code

The experiment separated code from architectural intent. ChatGPT was used to reason about the project structure, generate precise prompts based on organization and intent, and encode architectural rules and constraints explicitly. The actual Terraform files never left the local environment.

An AGENTS.md file described the project structure, architectural rules, and non-negotiables; it guided local Codex work and helped prevent scope creep, speculation, and unsafe changes.

The interpretation pipeline

Once the architecture was internally validated, the diagram prompt included the project description, module boundaries, environment differences, governance and FinOps posture, and user/request flow—but no Terraform code. A diagram renderer was then given that structured description.

1. Terraform encodes the real system locally.
2. AI interprets structure, intent, and constraints.
3. Local agent instructions guide safe repository work.
4. AI produces a conservative architectural description.
5. A diagram tool renders what was already decided.

Terraform remains the source of truth; AI is the interpreter; the diagram tool is the renderer. The diagram is the last step, not the first.

Takeaway

When infrastructure is intentional and well structured, it can yield accurate architecture views without leaking code. That supports better diagrams, reviews, onboarding, and architectural conversations while treating security and compliance as design constraints.