Architecture Decision Records
An ADR records a decision, the options it was weighed against, and the consequences of picking one — so a future maintainer (including a future version of whoever wrote it) can tell whether the reasoning still holds before reversing it. This section holds ADRs for the handbook platform itself and for the labs in Build; it’s a working example of the format as much as it is a record.
Required structure
Section titled “Required structure”Every ADR carries these sections, in this order. scripts/lint-content-structure.ts fails CI if
one is missing.
- Status — Proposed, Accepted, Deprecated, or Superseded.
- Context — the situation that forced a decision.
- Problem — the specific question being answered.
- Options — what was considered, including the ones rejected.
- Decision — what was chosen.
- Consequences — what that decision costs and what it buys, including what it makes harder.
- References — sources the decision leaned on.
Decisions
Section titled “Decisions”| ADR | Title | Status |
|---|---|---|
| 0001 | Use Astro + Starlight for the documentation platform | Accepted |
| 0002 | Use a pnpm workspace monorepo for site, packages, and labs | Accepted |
| 0003 | Render Mermaid diagrams client-side instead of at build time | Accepted |
| 0004 | Use one permissive Starlight schema plus a separate structural linter | Accepted |
| 0005 | Deploy via Cloudflare Pages git integration instead of GitHub Pages | Superseded by 0007 |
| 0006 | Exclude content/docs MDX files from Prettier | Accepted |
| 0007 | Deploy as a Worker with static assets instead of a Pages project | Accepted |