Skip to content

Architecture Decision Records (ADRs)

An ADR captures a significant architectural decision, its context, the options considered, and the rationale for the choice made. ADRs create an auditable history of why the system is built the way it is.

When to Write an ADR

Write an ADR when: - Choosing between multiple technology options (e.g., "why Istio over Linkerd") - Making a decision that will be hard or expensive to reverse - Introducing a new pattern that all engineers should follow - Deciding NOT to do something that might seem obvious

You do not need an ADR for implementation details — only for significant architectural choices.

ADR Status Values

Status Meaning
Proposed Under discussion, not yet accepted
Accepted Approved and current
Deprecated Previously accepted, now superseded
Superseded by ADR-XXX Replaced by a newer decision

Decision Index

ADR Status Title Date
ADR-001 Accepted Use GKE as the container orchestration platform [NEEDS TEAM INPUT]
ADR-002 Accepted Use Istio as the service mesh [NEEDS TEAM INPUT]
ADR-003 Accepted Use ArgoCD for GitOps deployments [NEEDS TEAM INPUT]
ADR-004 Accepted Use Terraform + module pattern for infrastructure-as-code [NEEDS TEAM INPUT]
ADR-005 Accepted Use External Secrets Operator for secret synchronization [NEEDS TEAM INPUT]
ADR-006 Accepted Use database-per-service pattern with shared Cloud SQL instance [NEEDS TEAM INPUT]
ADR-007 Accepted Use Kafka KRaft mode (no ZooKeeper) [NEEDS TEAM INPUT]
ADR-008 Accepted Use Percona PSMDB Operator for MongoDB [NEEDS TEAM INPUT]
ADR-009 Accepted Use KEDA for event-driven autoscaling [NEEDS TEAM INPUT]
ADR-010 Proposed Atlantis for automated Terraform plan/apply 2026-04-02

[NEEDS TEAM INPUT: create individual ADR files for each of the above decisions following the template below. The decisions listed are inferred from the codebase — verify these match actual team decisions and add any missing ones.]

Creating a New ADR

  1. Copy adr-template.md to decisions/adr-{number}-{short-title}.md
  2. Fill in all sections
  3. Open a PR for team review
  4. Merge when there is consensus — the ADR status becomes "Accepted"

See Also