project-heirloom

Project Heirloom

Working title. The thesis: families are using the wrong tools for human jobs. A quiet place for the people you live with — less logistics, more presence.

This is the engineering scaffold. The product story, pitch, and prototype live elsewhere; this repo is where we actually build it.

Stack

• Next.js 15 (App Router, React Server Components)
• TypeScript (strict)
• Tailwind CSS (with the editorial palette from the pitch — Fraunces serif, cream/forest/tomato)
• Supabase — Postgres + Auth + Storage + RLS
• Netlify — hosting + edge

Quickstart

# 1. Install dependencies
npm install

# 2. Copy the env template and fill in real values
cp .env.local.example .env.local
# Then edit .env.local — see SETUP.md for where to find each value

# 3. Run dev
npm run dev

Open http://localhost:3000 — you should see the landing page. Click “Sign in” to hit the auth flow.

Project structure

src/
├── app/
│   ├── page.tsx                    landing page (redirects to /home if signed in)
│   ├── login/page.tsx              OAuth + magic link sign-in
│   ├── auth/
│   │   ├── callback/route.ts       OAuth code exchange
│   │   └── sign-out/route.ts       sign out
│   └── (protected)/                everything in here requires auth
│       ├── layout.tsx              auth gate
│       └── home/page.tsx           authenticated landing
├── lib/supabase/
│   ├── client.ts                   browser client
│   ├── server.ts                   server client (cookies-aware)
│   └── middleware.ts               session refresh helper
└── styles/globals.css              fonts + base styles

supabase/
└── migrations/
    └── 0001_initial_schema.sql     profiles, families, family_members + RLS

docs/                               progress logs (see below)

Auth providers

• Google
• Microsoft (consumer Outlook/Hotmail + work accounts)
• Apple
• Email magic link (passwordless — the Grandma path)

Configuration is fiddly. See SETUP.md for step-by-step instructions for each provider. That document is the source of truth for OAuth setup — update it whenever you learn something new.

Architecture decisions

See DECISIONS.md for the running log of why things are the way they are.

Progress logs

Major milestones are logged in docs/. Each log captures what we hit, how we got around it, and what to remember next time. Start there when revisiting this project after a break.

Security

• Row Level Security is on for every table.
• The publishable Supabase key is safe to expose to the browser.
• The service_role key is server-only — never commit it, never expose it.
• Session cookies are httpOnly and managed by @supabase/ssr.
• Strict CSP, HSTS, and clickjacking headers are set in next.config.ts.

Status

🚧 Foundation phase. Auth scaffolded; product features deliberately not built yet. Working name “Project Heirloom” is the repo code name only — the brand name is unresolved (see prior conversations re: naming research).