Decision log

ADR-style records. Append-only — never edit a decision, append a new one that supersedes.

ADR-001 — Next.js App Router over Pages Router (2026-03-04)

Context. Greenfield project. Both routers are stable. Decision. App Router. Why. RSC + Cache Components match our data-heavy / read-mostly profile. Server Actions reduce API surface. Vercel ships features here first. Consequence. Learning curve for hires familiar with Pages. Documented in onboarding.

ADR-002 — Supabase over Neon + Clerk (2026-03-04)

Context. Need DB + auth. Decision. Supabase for both. Why. RLS lets auth and authz live next to data. One vendor. Cheaper at our stage. Consequence. Vendor lock-in on auth. Acceptable — we'd rewrite auth before migrating off SB anyway.

ADR-003 — Resend over SendGrid (2026-03-12)

Context. Transactional + marketing email. Decision. Resend. Why. DX, modern API, React Email templates we already use elsewhere. Consequence. Less mature deliverability tooling. Revisit at $5k MRR.

ADR-004 — pgvector over Pinecone (2026-04-02)

Context. Need vector similarity for AI features. Decision. pgvector + HNSW in the existing Supabase Postgres. Why. No extra vendor. JOINs with relational data are free. HNSW is fast enough up to ~10M vectors. Consequence. When we exceed ~10M vectors we'll need to evaluate dedicated vector DB. Not soon.

ADR-005 — Tailwind 4 over CSS Modules (2026-04-08)

Context. Component styling. Decision. Tailwind 4 + a thin design-token layer. Why. Faster iteration, smaller CSS bundle, shadcn/ui parity. Consequence. Class lists get long. Use clsx + extracting to constants when a list exceeds 6 utilities.

ADR-006 — Vercel AI Gateway over direct Anthropic SDK (2026-04-22)

Context. Multiple AI providers for failover. Decision. Route through Vercel AI Gateway. Why. Provider failover, zero data retention, observability built-in. Same vendor as hosting. Consequence. One more hop in the request path. Latency p95 +30ms — acceptable.

ADR-007 — Postgres over DynamoDB (2026-05-08)

Context. Block-level content with complex relationships. Decision. Postgres. Why. Three customer interviews flagged needs that require joins (cross-page analytics, block-level templates, A/B variant aggregation). Cost model showed PG cheaper up to ~50M rows. Consequence. Will feel pain at ~100M rows. Revisit then.