Terraform Guide

Terraform documentation generator: the doc AND the diagram, from the same parse

terraform-docs solved one slice of the problem: inputs, outputs, and providers as markdown tables, generated rather than hand-maintained. What it cannot tell a reader is what the repository builds. That takes an architecture doc and a diagram, and both can be generated from the same source files, on the same schedule, so neither drifts.

Try it free
7 min readFor maintainers who already run terraform-docs and still get asked how it all fits together

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

159/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

What terraform-docs covers, and the gap it leaves

terraform-docs reads variables, outputs, and requirements, and renders reference tables. Excellent for consumers of a module. But reference tables answer what can I pass in, not what does this build, why is it split into these modules, or what talks to what. That narrative gap is why the README still opens with a hand-written paragraph that was true two quarters ago.

The generated architecture doc

Datadef parses the full repository, stacks, modules, resources, references, environments, and writes an architecture.md from it: what the platform is, what each stack provisions, how modules wire together, and how environments differ. The claims are grounded in the parse rather than free-written.

The doc ends with a generated module reference table, one row per module with its source, version where declared, and resource count, in the terraform-docs spirit but produced by the sync. It also carries the live diagram embed near the top, so the doc opens with the picture.

## Module reference

| Stack | Module | Source | Resources |
| --- | --- | --- | --- |
| root | databricks | ./modules/databricks | 41 |
| root | key_vault | ./modules/key_vault | 4 |
| root | lakebase | ./modules/lakebase | 8 |

One parse, two artifacts, zero drift between them

Because the doc and the diagram come from the same parsed model, they cannot disagree with each other, and the daily sync keeps both matching the branch. Unchanged commits skip regeneration, so the history stays quiet when the code does.

Keep terraform-docs for per-module input and output tables; add this for the repository-level story. The two compose: reference tables for consumers, architecture doc and diagram for everyone who has to reason about the whole.

FAQ

Is this a replacement for terraform-docs?

No, a complement. terraform-docs generates per-module input and output reference tables. This generates the repository-level architecture doc and diagram. Most repos benefit from both.

Where does the generated doc live?

It is stored with the synced project and readable in Datadef, and it is plain markdown you can copy into the repository. The diagram embed line inside it works anywhere markdown renders images.

How does the doc avoid making things up?

The writing step is grounded in the parsed model of the repository: the stacks, modules, resources, and references extracted from the .tf files. The module reference table is generated directly from the parse without a model in the loop.

How often does it update?

On the daily sync, on demand from the UI, or when triggered through MCP from an agent session. Syncs on an unchanged commit are skipped.