```markdown # Shelfie Web app where independent bookshops list used books and customers reserve a copy for in-store pickup by paying a small deposit. Two user types: shop owners (manage inventory) and customers (browse, reserve). Solo project, pre-launch, first shops onboarding after the deposit flow ships. ## Commands | Task | Command | |---|---| | Install | `npm install` | | Dev server | `npm run dev` | | Lint | `npm run lint` | | Build (run before every push) | `npm run build` | | Apply migrations | `npx supabase db push` | | Regenerate DB types (after any migration) | `npx supabase gen types typescript --local > lib/database.types.ts` | | Tests | TODO: no test runner yet | | Deploy | Vercel, automatic on push to main | ## Project map | Path | What lives here | New files of this kind go... | |---|---|---| | `app/` | Routes, layouts, and server actions (`actions.ts` next to the route that uses them) | new page -> `app/<route>/page.tsx`; new mutation -> `actions.ts` in that route folder | | `components/` | Shared UI | `components/<Name>.tsx`, one component per file | | `components/ui/` | shadcn/ui, generated | never edited by hand; add via the shadcn CLI only | | `lib/` | Supabase clients, helpers, `database.types.ts` | helpers -> `lib/<topic>.ts` | | `supabase/migrations/` | SQL migrations, timestamp-prefixed | one new file per schema change | | `public/` | Static assets | | ## Conventions Data - Mutations are server actions in `actions.ts`, marked `"use server"`. Not API routes. - Every server action validates its input with a zod schema defined in the same file before touching Supabase. - Every new table gets `alter table ... enable row level security` and at least one policy in the same migration. - Timestamps are `timestamptz`, written in UTC. Format for display in the component, never in the query. - Use `lib/database.types.ts` types for rows. Regenerate after every migration; do not hand-edit. UI - Tailwind utility classes only. No `.css` files, no `style={}` props. - Build from `components/ui/` primitives before writing a new component. Git - `npm run build` must pass before pushing. Vercel deploys main on push. ## Never - Never edit an existing file in `supabase/migrations/`. Create a new migration. - Never commit `.env.local` or paste its values into code or docs. - Never install a new dependency without asking first. Say what it is for and what it replaces. - Never disable RLS on any table, including "temporarily to debug". - Never use `SUPABASE_SERVICE_ROLE_KEY` in any file that can reach the browser. It is only for server actions and the Stripe webhook route. - Never create `app/api/*` routes, with one exception: `app/api/stripe/webhook/route.ts`, because Stripe needs a POST endpoint. - Never edit files in `components/ui/`. ## Current focus Stripe Checkout for the reservation deposit. - Customer clicks Reserve -> server action creates a Checkout Session with `book_id` and `customer_id` in metadata -> redirect. - `app/api/stripe/webhook/route.ts` verifies the signature and, on `checkout.session.completed`, inserts the `reservations` row. - Done when: a test-mode payment creates exactly one reservation row, a failed or abandoned payment creates none, and the webhook returns 200 within Stripe's timeout. - Update this section when the focus changes. ## Definition of done - [ ] `npm run lint` passes - [ ] `npm run build` passes - [ ] Any new table has RLS enabled and policies in the same migration - [ ] `lib/database.types.ts` regenerated if the schema changed - [ ] Every new form or action input has a zod schema - [ ] No new dependency added without approval - [ ] Tested by hand in the browser at `npm run dev` (no automated tests yet) ## Gotchas - The default instinct is to create an API route for any server work. In this repo that is wrong except for the Stripe webhook. Use a server action. - Creating a table without RLS makes it publicly readable through the anon key. Policies are part of the table, not a follow-up. - Supabase types go stale silently. If a column "does not exist" in TypeScript but does in the database, regenerate types. - Stripe webhooks do not run on `localhost` without the Stripe CLI forwarding. Do not conclude the webhook is broken from a local test alone. - The owner has about six months of experience. Explain what a change does in one or two plain sentences when it touches auth, RLS, or payments. ``` Save this as `CLAUDE.md` in the repo root. It also works unchanged as `AGENTS.md` or `.cursorrules`. Update the Current focus section whenever the task changes, and the Never section whenever Claude breaks something new.