ADR-0001: Platform monorepo structured by toolchain, not by cloud
Date: 2026-07-14 Status: accepted
Amended: 2026-08-25. ADR-0012 removes pull-request entry from the generic Terraform Azure OIDC workflow. Other legacy pull-request OIDC paths remain until ADR-0012 Group E removes them.
Context
The previous repo organized everything under clouds and products (IaC/Azure/...,
gitops/, jupyterhub-syft/). It rotted: by mid-2026 every deployment target was dead,
the newest work lived untracked in the working tree, and there was no obvious home for
non-IaC platform work (Backstage, FinOps, dashboards). Rebuilt greenfield at tag
pre-rebuild-2026-07.
Decision
Top level splits by toolchain/lifecycle; cloud modularity exists only inside the layer where clouds actually differ:
| Layer | Applies via | Cloud-shaped? |
|---|---|---|
terraform/ |
terraform | yes — modules/<cloud>, stacks/<cloud> |
kubernetes/ |
Argo CD (pull) | no |
platform/ |
image build + GitOps | no |
observability/ |
GitOps / Grafana provisioning | no |
finops/ |
mixed (policy TF, scripts) | no |
Products are split by lifecycle, not name: e.g. Keycloak's database (changes yearly, Terraform) and Keycloak's helm values (changes weekly, GitOps) live in different layers.
Consequences
- "Where does X go?" is answered by one question — what applies it? — encoded in
CLAUDE.md and the
/whereskill. - The generic Terraform pull-request lane validates source without Azure credentials. No pull request enters the generic Terraform Azure OIDC workflow. Other legacy pull-request OIDC paths remain until Group E.
finops/andobservability/accept mixed toolchains because domain ownership beats tool purity there.