Architecture Decision Records

Numbered, append-only log of non-trivial decisions. Each ADR captures the why behind a choice at the time it was made — the part that's hardest to recover months later from code or git history alone.

When to write one

Write an ADR when a decision:

• Locks in a library, data model shape, or wire format
• Closes off other reasonable alternatives
• Will be expensive to reverse later
• Has reasoning that isn't obvious from the resulting code

Don't write one for trivial choices ("use Tailwind for styling" — already established by the stack), but do write one for anything you'd want to explain to a future contractor in three sentences without them re-reading the codebase.

Conventions

• Numbered sequentially: 0001-…, 0002-…. Never reuse a number.
• Once Accepted, don't edit. Supersede with a new ADR that links back.
• Keep them short. One page is plenty. Long ADRs usually mean two decisions tangled together — split them.
• Use the template.

For the broader convention sheet, see Contributing.

Index

#	Title	Status	Date
0001	Postgres on port 5433 to avoid hummingbot conflict	Accepted	2026-04-26
0002	Build UX is all-slots-at-once (PCPartPicker model), not a step wizard	Accepted	2026-04-26
0003	Anonymous Visitor build persists in cookie + claims to account on sign-in	Accepted	2026-04-26