Skip to content

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 /where skill.
  • 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/ and observability/ accept mixed toolchains because domain ownership beats tool purity there.