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 |
| 0004 | English-only language scope for M1/M2 — defer Arabic / French / RTL | Accepted | 2026-04-28 |
| 0005 | Casual flow (UC-13) is a parallel track to Builder (UC-9), with Casual as primary landing | Accepted | 2026-04-28 |
| 0006 | Hosting target is Cloudflare Pages + Workers + Neon + Upstash | Accepted | 2026-04-28 |
| 0007 | Background-jobs runtime is pg-boss on the existing Postgres | Accepted | 2026-04-28 |
| 0008 | Search backend is Postgres FTS + pg_trgm + unaccent + curated synonym map | Accepted | 2026-04-28 |
| 0009 | Frontend stack stays Next.js 16 + React 19 + Tailwind 4; add shadcn/ui | Accepted | 2026-04-28 |
| 0010 | Category scope for M1, M2, M3 — Builder 8 in M1, monitors in M2, laptops + prebuilts + peripherals in M3 | Proposed | 2026-04-28 |
| 0011 | Monetisation rates and stream priority (CPS 1.5%, CPC $0.10–0.15, Sponsored $50–200/mo, USD only) | Accepted | 2026-04-28 |
| 0012 | Security controls posture for M1 — Auth.js targeted hardening, interim unsafe-inline style-src, CF WAF rate limiting, indefinite audit-log, security.txt + GPG, Cloudflare Free |
Accepted | 2026-04-28 |
| 0013 | AI discoverability posture — open robots.txt, ship llms.txt, Product+AggregateOffer+Brand+BreadcrumbList M1, prose stat block, sitemap M1 / RSS M2 / no public API | Accepted | 2026-04-28 |
| 0014 | Compliance baseline (M1/M2) — cookie banner deferred, three-line affiliate disclosure, AI-drafted ToS+Privacy with lawyer review, per-flow retention, per-listing liability disclaimer + Arabic translation | Accepted | 2026-04-28 |
| 0015 | Observability stack — Cloudflare-native primary (Workers Observability + Web Analytics + Analytics Engine + Notifications) + Sentry Free + Axiom Free, $0 incremental at M1 | Accepted | 2026-04-28 |
| 0016 | Quarterly stack-bump review cadence — first Monday of each quarter for major bumps; Renovate handles minor + patch | Accepted | 2026-04-28 |