Gifts AF platform (working name)
One app for three products (T19): gift lists (live, formerly the GiftsAF repo), Gift Concierge (being built) and scan-to-gift (later). Gift Concierge is an app that keeps track of friends and family, what they like, and the dates that matter. It picks gifts for those dates and buys them, with as much or as little automation as the user wants and safeguards so nothing gets purchased without time to approve.
Workspace layout
| Folder | Purpose | Status |
|---|
planning/ | Product discovery: PRD (approved 2026-10-17), decisions log, research, platform strategy (roadmap and go-to-market), longer-term ideas | Complete |
design/ | Technical design (approved 2026-10-17), decisions log. Spike write-ups go in design/spikes/, look and feel in design/ui.md (mock-ups in design/mockups/), and ticket specs and build plans in design/plans/ (start from the template). | Complete |
.claude/ | Shared Claude Code settings (turns on the Superpowers plugin; runs the local setup check at session start) | Done |
apps/web/ | The one web app (Next.js). Products live in modules/lists and modules/concierge; see its README | Lists live; concierge from Wave 2 |
apps/extension/ | Chrome capture extension: save what's on screen to a person. How to build and load it is in its README | MVP built (ALL-22), loaded unpacked |
packages/core/ | Pure shared logic (dates, deadlines, budgets) and database types | W1-5 |
supabase/ | Database migrations and local Supabase settings (config.toml) | Lists tables today |
scripts/ | Repo tooling, such as dev-check.mjs (the local setup check) | Done |
spikes/ | Throwaway Wave 1 experiments (Zinc, AI, email) | Reference only |
Getting started
-
Install Claude Code, clone this repo, and open Claude Code in it.
-
Trust the folder when asked, and accept the prompt to install the Superpowers plugin. It's required for all development here (.claude/settings.json turns it on). If no prompt appears, run /plugin install superpowers@claude-plugins-official and restart Claude Code.
-
Set up your machine for local development (next section). Claude Code checks this every time a session starts and walks you through anything missing.
Local development
Check your machine any time with pnpm dev:check. It lists what's missing and how to fix it on Windows, Mac or Linux. Claude Code runs the same check when a session starts (a SessionStart hook in .claude/settings.json) and offers to walk you through any gaps, so after pulling a change that adds a new requirement, your next session will tell you.
| You need | Why | How to get it |
|---|
| Node 22+ | Runs everything | Windows: winget install -e --id OpenJS.NodeJS.LTS · Mac: brew install node@22 |
| pnpm | Package manager for this repo | npm install -g pnpm |
| Dependencies | Includes the Supabase CLI, pinned in package.json, so there's nothing to install globally | pnpm install from the repo root |
| Docker | The Supabase CLI runs a full local Supabase (database, auth, storage) in Docker containers | Windows: wsl --install --no-distribution as admin, restart Windows, then winget install -e --id Docker.DockerDesktop, open Docker Desktop and accept its terms. Mac: in Terminal, brew install --cask docker-desktop (it asks for your Mac password), then open Docker Desktop and accept its terms. |
| Playwright's Chromium and WebKit | Run the browser tests (apps/web/e2e/) as an Android phone (Chromium) and an iPhone (WebKit, Safari's engine) | pnpm --filter @gifts-af/web exec playwright install chromium webkit |
Local database. With Docker Desktop running:
pnpm supabase start # first run downloads images (a few minutes); applies supabase/migrations/
pnpm supabase status # local URLs and keys; Studio (the database UI) is at http://127.0.0.1:54323
pnpm supabase db reset # rebuild the local database from the migrations, e.g. after pulling new ones
pnpm supabase stop # stop the containers; your local data is kept
pnpm db:test # run the database tests in supabase/tests/ (privacy rules, keys, cascades)
pnpm db:types # regenerate packages/core/src/database.types.ts after changing the schema
Write new migrations with pnpm supabase migration new <name> and test them locally before they go to dev or prod. Local settings live in supabase/config.toml. Every new user-owned table needs user_id, its privacy rule and a test in supabase/tests/ (see design/decisions.md T26). CI runs pnpm db:test and fails if the generated types are stale.
Before the first migration push to a hosted project (dev or prod): config.toml only exposes the concierge and lists schemas locally. On each hosted project, add both under Project Settings > Data API > Exposed schemas (admin, as allensforever711), or the app's queries fail with PGRST106. Do it right after pushing the migration that creates the schema, never before. Exposing a schema that doesn't exist yet takes the whole Data API down (every request gets a 503; tested locally on 2026-10-25). That project also needs Postgres 15 or later; the migrations use on delete set null (column).
Browser tests (Playwright): with the local database running, pnpm --filter @gifts-af/web e2e. They sign in as a throwaway local account (created for you, email and password, since local Supabase has no Google) at phone width (375 px). If pnpm dev is already running on port 3100 it's reused; otherwise one is started. CI runs them against a production build (e2e job).
Running the web app: follow apps/web/README.md to link Vercel and pull the environment variables, then pnpm dev. Before a PR, pnpm lint && pnpm typecheck && pnpm test && pnpm build (CI runs the same).
Deploys: Vercel project gift-me (team GiftsAF, slug gift-me3) builds apps/web from this repo. Every push to main deploys to production; every other branch gets a preview URL.
Environments
| Environment | Database | Used by |
|---|
| Local | Supabase in Docker (pnpm supabase start) | Your machine, when you point apps/web at it |
dev | Supabase project gift-me-dev (ref bcemtqvdbrrgiipzggyw) | pnpm dev with pulled Vercel variables, and every PR preview |
prod | Supabase project gift-me (ref pegtrucfuaaufqvsavpb), GiftsAF's original project with real users | Production (main) only, at https://giftsaf.com (www redirects there; the old https://gift-me-beige.vercel.app still works) |
- How Vercel picks the database: the Supabase integration provides
NEXT_PUBLIC_GIFT_SUPABASE_* (prod) to every environment. Development and Preview also have NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY set to dev, and apps/web/lib/supabase/env.ts reads those first. The integration store (Vercel → Storage → gift-me) is connected to Production only, so prod's server-side keys stay off developer machines.
- Migrations go local →
dev → prod. Sign in once with pnpm supabase login (in a real terminal; it opens a browser, sign in as allensforever711). Then pnpm supabase link --project-ref <ref> and pnpm supabase db push --linked. Check what's linked with pnpm supabase migration list --linked before pushing. No database password is needed. Both dev and prod record the four lists migrations as applied (prod's were pasted in by hand and marked applied with migration repair on 2026-10-25).
- Google sign-in is on in
dev and prod (2026-10-25). Since ALL-14 (2026-11-01) the consent screen shows GiftsAF with giftsaf.com as an authorized domain, and prod's Auth Site URL is https://giftsaf.com (redirect URLs: https://giftsaf.com/** plus the old gift-me-beige.vercel.app). One OAuth client, "Supabase (dev + prod)", in the Google Cloud project gift-me (allensforever711), redirects to both projects' /auth/v1/callback. The consent screen is in testing mode, so only listed test users can sign in. Add people under Google Auth Platform → Audience → Test users. The secret lives only in Google Cloud and the Supabase dashboards. Local Docker Supabase stays email-only, so nobody needs the secret; test Google sign-in on dev or a PR preview. dev's redirect URLs allow http://localhost:3000/** and every preview (https://*-gift-me3.vercel.app/**).
- Calling previews from the database: previews sit behind Vercel's login. A Vercel "protection bypass for automation" secret is stored in
dev's Vault as vercel_preview_bypass. Send it as the x-vercel-protection-bypass header, e.g. from pg_net, which was tested on 2026-10-25. It never opens production.
- Keys and secrets live in Vercel's environment variables, nowhere else. Every app key (Resend, Zinc, cron secrets…) is a variable on the project, set per environment (Development, Preview, Production). Anyone signed in as allensforever711 (T25) gets them with (see ), and each one is listed, without its value, in . so works for everyone; normal variables are still encrypted. : nobody can read them back, only the running app uses them, and if one is needed it's reissued from the vendor. Today the pull gives you the dev Supabase URL and key, the AI Gateway token, , (when the logo wears its Christmas hat, T35), the Turnstile bot-check keys and (Cloudflare's always-pass test keys outside production, T43), (the Google client for the Contacts import, T45) and (Zinc's test-mode key in development, live key in production). is the server-only Supabase key that lets server code write tables users can't (action links, notifications, later the round engine): the project's key in Development and Preview, while production uses the integration's . It is never sent to the browser (ALL-23, T38). GitHub secrets are only for CI, since nobody can read them back. when a ticket needs a new vendor, create its dev and prod keys and add them here first, then build against the pulled dev key. Spikes use the same keys; there are no throwaway spike keys (owner, 2026-11-01: we work in a full-trust team, so a key seen in a session isn't rotated). Never commit a key to git.
Where new docs go, how to write them, and when to push straight to main versus open a PR are in CLAUDE.md. Claude reads it automatically, and it's written for people too. Other AI tools read AGENTS.md, which points them to it. The standing rule for everyone: no work without a Linear ticket, and no ticket done without its test evidence posted on it (T44).
Shared material
