project-heirloom

DECISIONS.md

A running log of architecture decisions and the reasoning behind them. New entries go at the top. Each entry: what we decided, why, what we considered, what would change our mind.

---

2026-04-29 — Initial stack: Next.js 15 + Supabase + Netlify

Decision: Next.js 15 (App Router) + TypeScript + Tailwind, with Supabase for auth/database/storage and Netlify for hosting.

Why:

• Supabase gives us auth + Postgres + storage + RLS in one box. For a family app where multi-tenant isolation is non-negotiable, RLS at the database level is the right primitive — every query is scoped by family membership without the app having to remember.
• Next.js App Router + Server Components keep secrets server-side by default and let us render protected pages with user context already known.
• Netlify deploys Next.js cleanly and gives us a free preview-per-PR workflow.
• Tailwind lets us carry the Fraunces/Caveat editorial aesthetic from the pitch deck without rebuilding it from scratch.

Alternatives considered:

• Vercel instead of Netlify — Vercel has slightly tighter Next.js integration but Bill prefers Netlify and the gap has narrowed. Move only if we hit a Netlify-specific Next.js issue.
• Firebase — also gives auth + storage + DB but lock-in is worse, and Firestore’s data model is awkward for the relational structure a family app needs (recipes, events, members, permissions).
• Roll our own backend — too much foundation work for too little payoff this early.

What would change our mind: A specific feature requirement Supabase can’t serve (real-time collaboration at scale, complex search, etc.) might push us to add a service alongside Supabase, but won’t replace it.

---

2026-04-29 — Auth providers: Google, Microsoft, Apple, magic link

Decision: Support these four. Skip Facebook, GitHub, Discord, etc.

Why:

• Google + Microsoft cover most family inboxes (Gmail and Outlook/Hotmail dominate at the household level).
• Apple is required for any future native iOS app that offers other social sign-in. Adding it on day one saves a migration later.
• Email magic link is the Grandma path — passwordless, no provider required, works for anyone with an email address. More secure than passwords anyway (no shared-credential reuse risk).
• Skip Facebook — privacy reputation runs against the “presence over performance” thesis. Symbolic but real.
• Skip dev-flavored providers (GitHub, Discord) — wrong audience.

---

2026-04-29 — Multi-tenant model: families as the tenant unit

Decision: A “family” is the tenancy boundary. Every domain table in the future will have family_id and RLS that joins to family_members.

Why:

• A user can be in multiple families (parents post-divorce, blended families, helping aging parents in a separate household, etc.).
• Joining on family_members rather than checking a single family_id on the user lets us model that without contortions.
• The is_family_member(family_id) SQL helper means every future RLS policy is one line, not five.

Roles: owner, adult, child, elder. We’ll figure out what those mean granularly when we hit the first feature that needs role-based permissions.

---

2026-04-29 — getUser() not getSession() in middleware

Decision: Always use supabase.auth.getUser() to validate auth on the server. Never use getSession() for security checks.

Why: getSession() reads the cookie and trusts it. getUser() validates the JWT against Supabase Auth on every call. The latter is slightly slower but is the only one that’s actually secure. The Supabase docs flag this and several teams have shipped vulnerabilities by getting it wrong.

---

2026-04-29 — Working code name “Project Heirloom”

Decision: Use “Project Heirloom” as the GitHub repo name and internal working title. Brand name is unresolved.

Why: Naming is blocked on trademark/domain checks. Building under the working name lets us start engineering without committing to a brand. The real name lands in env vars, deployment URLs, and metadata.title once chosen — minimal refactor cost.

What changes when we name it: Update metadata.title in app/layout.tsx, update the Supabase project display name, update Netlify site name, register the domain, transfer/rename the GitHub repo if desired.