Architecture decision records
Architecture decision records
Architecture decision records
One record per decision that was expensive to make and would be expensive to revisit: what the situation was, what was chosen, and what that costs. They are not updated as the code moves on — a decision that no longer holds gets a new ADR superseding it, so the reasoning at the time stays readable.
Write one when a choice constrains later work (a dependency, a data model, a protocol, a deployment shape), not for every design discussion. Number it after the highest existing ADR and give it the same header block: status, date, and the tracking issue where there is one.
| ADR | Decision | Date |
|---|---|---|
| 0001 | Replace Airtable with a SQL database | 2026-04-16 |
| 0002 | Testing strategy | 2026-04-23 |
| 0003 | Form handling and validation with React Hook Form and Zod | 2026-07-02 |
| 0004 | Dev fake clock for time-traveling event phases | 2026-07-23 |
| 0005 | Dark mode via semantic tokens and a per-device cookie | 2026-08-17 |
| 0006 | Push notifications through an installable web app | 2026-09-05 |
| 0007 | Attendee count storage and in-process reminder dispatch | 2026-08-25 |
| 0008 | Publish the developer docs at developers.schellingboard.org | 2026-09-18 |
| 0009 | Move to a standalone repo in new schellingboard GitHub org | 2026-09-19 |
| 0010 | Domain and contracts as workspace packages | 2026-10-03 |
| 0011 | A change log and one jobs loop | 2026-10-03 |
| 0012 | A versioned HTTP API in the Next process | 2026-10-04 |
| 0013 | The unit of work | 2026-10-06 |
| 0014 | The change feed and the snapshot | 2026-10-07 |
| 0015 | The SPA alongside Next | 2026-10-08 |
| 0016 | The remaining screen families | 2026-10-25 |
| 0017 | Identity and roles | 2026-10-28 |
| 0018 | The API review for 5.0.0 | 2026-11-01 |
| 0019 | Statistics in the admin | 2026-11-07 |
Longer design work that isn’t a single decision lives next door: Architecture and Attendance model.