Live demo

Architecture Decision Records

Why the codebase is shaped the way it is: one short record per load-bearing decision.

Updated 22 records, 1 superseded Edit on GitHub
On this page

Why these exist#

Code preserves the what but rots the why. Each record captures one decision, the context it was made in and the options that were rejected, so a future contributor can ask "why did they do it this way?" and get an answer without archaeology.

How to use them#

  • Read any record whose subject touches the area you are changing before you change it.
  • Write a new record when a decision adds, removes or replaces a major dependency, changes an architectural pattern, or constrains future choices in a non-obvious way.
  • Don't edit a record after it is merged. Write a follow-up that supersedes it and mark the old one Superseded by NNNN.

Records follow the upstream template and stay short: one page is the target, two is the maximum. There is no ADR 0003; that number was reserved for a decision withdrawn before it was written, and numbers are never reused.

Index#

  1. 0001Choose Next.js 15 + React Server Components as the frameworkAccepted
  2. 0002License under MITAccepted
  3. 0004Three-layer architecture (auth → RBAC → business logic)Accepted
  4. 0005Migrations are never auto-applied on app bootSuperseded by 0011
  5. 0006Per-request CSP nonceAccepted
  6. 0007DB-backed sessions over stateless JWTsAccepted
  7. 0008Argon2id for password hashingAccepted
  8. 0009Roll our own auth core on openid-client + argon2, not Auth.jsAccepted
  9. 0010Per-RRset optimistic concurrency for the editorAccepted
  10. 0011Migrations run at app-container bootAccepted, supersedes 0005
  11. 0012First-boot provisioning + OIDC group → role materialisationAccepted
  12. 0013The PDNS client's sanctioned DB bridge (and fixing boundary enforcement)Accepted
  13. 0014Per-zone authority + observed daemon capabilities (retire per-server role)Accepted
  14. 0015Backend health advisories (the notification bell)Accepted
  15. 0016Optional Redis for horizontal scale (replicas > 1)Accepted
  16. 0017Squash the 1.1.0 schema deltas into one migration per dialectAccepted
  17. 0018Multi-provider auth: keep OIDC where it is, layer SAML + LDAP as siblingsAccepted
  18. 0019WebAuthn: both primary credential and second factorAccepted
  19. 0020LDAP authentication architectureAccepted
  20. 0021SAML 2.0 service-provider architectureAccepted
  21. 0022Zone horizons: app-side split-horizon classificationAccepted
  22. 0023Zone authority is a separate permission from zone recordsAccepted