The context
Where these decisions come from.
Read the collection at adr.stephens.page.
The curated home for my best Architecture Decision Records, from every system I run in production - private and public - written so the reasoning is visible even where the code cannot be.
Only decisions exercised in production applications or their operating tools belong here. A deployed prototype, an acceptance trial, or a proposed mechanism does not qualify. Each record states where the decision is used, what I chose, what I gave up, and when I would choose differently. Measurements keep their proof boundaries: a dashboard query from 1,441 seconds to 0.196, a six-hour outage behind a validator that printed green, or a session lock whose fix has shipped without a production re-measurement.
Records come from two kinds of source, and each says which it is.
- From a private system: sanitized and written at the architecture level - no hostnames, addresses, credentials, customer data, or colleagues' names. The record here is the only public copy.
- From a public repository: the record carries a Source line. The original lives in that repository beside the code it governs and is the canonical copy; what is here is the generalized write-up, so the pattern can be read without the project's vocabulary.
Where these come from
| System | Who uses it | Main records |
|---|---|---|
| A reservations and operations platform for a group-travel operator: a PHP 8.4 / MySQL 8.4 core modernized in production from PHP 5 / MySQL 5, four portals on one schema. I am its lead engineer. Private. | Office staff daily; tour guides in the field through an offline-capable portal | 0002, 0004, 0006, 0034, 0042-0044, 0058, 0061-0063 |
| The fleet platform around it: guarded deploys, an operator console, secrets, observability across the hosts, and Docker-based Manager Sandboxes where non-technical managers work with an AI assistant on a copy of production data. Private. | Me, the engineers I work with, and the managers who own a sandbox | 0001, 0003, 0005, 0007-0009, 0011, 0018-0022, 0027-0029, 0032, 0033, 0040, 0041, 0057-0060 |
| thirdshift, the current open-source issue-to-pull-request factory, with review and repair sessions around deterministic CI and merge decisions. | Me, on my own repositories and the reservations platform's work tracker | 0053-0056 |
| A project team's planning surfaces: requirements, review previews, generated status pages, and the CI that checks them. Private. | A five-person project team | 0046, 0047, 0065 |
| vaulted-agent: a Rust launcher that resolves per-agent secret manifests into a child process's environment. Public, released. | The fleet above, and anyone who installs it | 0028, 0048 |
| A paid, privacy-sensitive charting app on the web, the App Store, and the Play Store, with end-to-end encrypted sync and subscription billing (architecture slice). | Customers on the web, iOS, and Android | 0049, 0050, 0064 |
| Two copy-deployed sync services, one for a weightlifting tracker and one for a game. | Users of each app, with separate backends | 0012 |
| My own fleet: one VPS serving about 70 hostnames for my products and client sites, with DNS as code across 9 zones (sanitized mirror). | Me and my clients | 0014, 0015, 0017, 0030, 0031 |
| A small multiplayer word game with an LLM grading every attempt live. | A handful of players | 0051 |
Evidence boundary
Production means a running application or an operating tool used for real work. Running a trial on a production host or against a real codebase does not establish that status. Prototypes and unused mechanisms are excluded.
- A Manager Sandbox gives a manager and an AI assistant separate application files and processes over a shared writable dataset, refreshed nightly. Per-manager credentials attribute access; they do not separate the data. Code promotion requires engineering review. A separate SELECT-only path reads production under server-enforced limits.
- thirdshift is used to deliver code. Its records cover the evidence a reviewer supplies, the commit whose checks were watched, and a feature's review boundary. Deployed behavior and measured outcomes remain separate claims; the status line says what the evidence establishes.