Skip to content

0001. Record architecture decisions

  • Status: accepted
  • Date: 2026-04-15
  • Deciders: lusoris

Context

This repo manages a dual-site Kubernetes cluster plus all its supporting IaC (Terraform, Ansible, Packer) and Cloudflare/Unifi config. Decisions like "which gateway pattern", "single vs dual cloudflared tunnel", "OIDC via Authentik vs static kubeconfig" accumulate silently over time. Without an explicit record, future-us can't recover the reasoning.

Decision

Adopt Architecture Decision Records (ADRs) in docs/adr/ using the MADR template. Number them sequentially (0001-…, 0002-…). Creation via the /add-adr skill.

Scope: architectural choices that constrain future work. Examples:

  • Choice of CNI (Cilium) and kube-proxy-replacement
  • Choice of gateway (Cilium Gateway API vs ingress-nginx)
  • Choice of GitOps engine (ArgoCD vs Flux)
  • Secrets model (sealed-secrets vs external-secrets)
  • Split-horizon DNS design
  • Multi-site routing strategy
  • Breaking-change migrations (e.g., Cilium 1.19 → 1.20)

Not in scope: routine config tweaks, version bumps, operational fixes — those go in STATE.md.

Consequences

Positive:

  • Decisions are searchable and navigable.
  • Newcomers (human or AI) can catch up on the "why" without archaeology.
  • Superseding a decision is explicit rather than silent.

Negative:

  • Small overhead per decision.
  • Risk of over-documenting trivial choices; mitigate by scoping to architectural only.

Alternatives considered

  • No ADRs, rely on commit messages: rejected — commit history is not discoverable for long-running architectural threads.
  • Long design docs in docs/: rejected — tends to stagnate; ADRs' append-only + superseded pattern ages better.