Overview
An auto-generated, interactive map of the Playroll AWS infrastructure. Every
diagram in this section is Mermaid (pan/zoom, theme-aware) and is produced
directly from the Terraform in
playroll-infra, so it
stays faithful to what is actually declared as code.
Two different graphs
The most important thing to understand before reading the diagrams: this section contains two graphs over the same Terraform, and their arrows mean opposite things.
| Page | Arrow A → B means | Source |
|---|---|---|
| Runtime event flow | "this event causes that to run" | .tf text: notifications, permissions, integrations, IAM |
| Dependency map | "A must exist before B" (build order) | terraform graph |
There is a neat inversion between them. The repetitive plumbing resources —
aws_lambda_permission, aws_s3_bucket_notification,
aws_api_gateway_integration — are collapsed out of the dependency map as
noise, because they add edges without adding comprehension. Yet those exact
resources are the entire signal of the runtime map: aws_lambda_permission
literally encodes principal + source_arn → "X may invoke Y".
Scope
Playroll runs ~150 AWS resources in a single account (us-east-1), split
prod / dev by Terraform workspace (separate S3 remote-state backends).
There is also a second, separate Terraform root for the automations department — its own state key, its own CI lane, its own tags. It is documented on its own page: Automations.
How it is generated
terraform graph -type=plan # read-only DOT: types + reference edges only
│ # NO AWS API calls, NO state refresh,
▼ # NO plan vars, NO secret VALUES
generate_infra_map.py # → grouped DEPENDENCY flowcharts
# (arrow = "A must exist before B")
*.tf (plain text)
│
▼
generate_event_flow.py # → RUNTIME EVENT-FLOW flowchart
# (arrow = "this event causes that to run")
Both generators live in playroll-infra/tools/infra-map/. To refresh after an
infrastructure change:
pwsh tools/infra-map/update-infra-map.ps1
then review the diff and commit here. Cloudflare Pages deploys on push to
main. The generator is idempotent — re-running with no infra change produces a
byte-identical page, so there is no diff churn.
terraform graph emits resource types and reference edges only — never
attribute values. The event-flow generator reads .tf text for a small,
fixed set of structural attributes (principal, events, http_method,
path_part). Neither reads Terraform state, and neither calls the AWS API. A
terraform show -json of live state would have dumped Secrets Manager and
KMS values, which is exactly why it is not used.
Why not AWS Config, Neptune, or Workload Discovery?
All three were evaluated before choosing this approach.
- AWS Config is a resource-inventory and relationship data source, not a visualizer. Its console shows a per-resource "related resources" list, not a map. Rendering an actual diagram requires bolting a graph store and a JS app on top — which is precisely what AWS's own reference architecture does.
- Amazon Neptune is a managed graph database positioned for "billions of
relationships in highly connected datasets." Our
150 resources imply hundreds of edges — roughly six orders of magnitude below that. It is also an always-on provisioned cluster ($200/month before storage and I/O). - Workload Discovery on AWS (formerly AWS Perspective) is the one AWS-native tool that genuinely is an interactive visual map. But it is itself built on Config + Neptune + OpenSearch + Fargate (~$425/month), and it retires on 14 August 2026. It is not a viable foundation for a new system.
Mermaid-from-Terraform costs nothing, adds no infrastructure, versions with the code, and renders in a docs site the team already reads.
For ad-hoc exploration beyond these published diagrams,
Rover serves a richer node-level explorer
at http://localhost:9000 from a Terraform plan. It is a local server, so it
cannot be hosted on Cloudflare Pages — hence Mermaid here. Instructions are in
playroll-infra/tools/infra-map/README.md.