Repository layout

The repository is split between infrastructure code, design history, and the documentation site.

.
|- README.md
|- docs/
|- website/
|- scripts/
|  `- bootstrap-state.sh
|- terraform/
|  |- staging/
|  |- prod/
|  `- modules/
|- openspec/
|  |- specs/
|  `- changes/archive/

Primary directories

Path	Purpose
README.md	Operator-oriented summary and command reference for the current stack
docs/	Official handbook content used by Docusaurus
website/	Docusaurus site application, theme, homepage, and blog
scripts/bootstrap-state.sh	One-time backend bootstrap helper for S3 state and DynamoDB locking
terraform/staging	Current deployed environment root
terraform/prod	Production-shaped root with the same module composition
terraform/modules	Reusable Terraform modules shared by both roots
openspec/specs	Capability-level requirements and technical reference inputs
openspec/changes/archive	Historical proposals, tasks, and design notes used to curate the Decisions section

How to read the codebase

1. Read terraform/staging/main.tf or terraform/prod/main.tf to see how modules are wired together in the current environment graph.
2. Move into terraform/modules to inspect each responsibility boundary: VPC, ALB, ECS services, MSK, RDS, secrets, and sink buckets.
3. Use the OpenSpec archive for context, not as the homepage. The archive records why the stack changed over time, while the handbook distills that material into current guidance.

Documentation source of truth

The handbook content is derived from three sources in priority order:

1. The actual Terraform roots and modules.
2. The operational flow in README.md.
3. OpenSpec documents where they still match the current implementation or explain an important architectural decision.

warning

If Terraform code and older OpenSpec notes disagree, prefer the Terraform code and update the docs accordingly.