# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Dev Setup

```bash
cp .env.example .env.local        # fill in secrets (lives at repo root)
ln -s ../../.env.local apps/web/.env.local   # Next.js reads from apps/web/, not root
docker compose -f compose.yml up -d          # start postgres, redis, minio
pnpm install
pnpm db:generate                  # generate migrations from schema (first time)
pnpm db:migrate                   # apply migrations
pnpm db:seed                      # seed tier definitions
pnpm dev                          # start Next.js on :3000
```

MinIO console: http://localhost:9001 (minioadmin / minioadmin)

## Key Commands

```bash
pnpm dev                   # run web app
pnpm build                 # production build
pnpm lint                  # lint all packages
pnpm typecheck             # type-check all packages

pnpm db:generate           # generate Drizzle migration from schema changes
pnpm db:migrate            # apply migrations
pnpm db:seed               # seed tier definitions
pnpm db:studio             # open Drizzle Studio
```

## Architecture

**Monorepo** (pnpm workspaces):
- `apps/web` — Next.js 15 App Router app (`@epicure/web`)
- `packages/db` — Drizzle ORM schema + client (`@epicure/db`)

**Route groups in `apps/web/app/`**:
- `(auth)/` — login, signup, verify-email (no auth required)
- `(app)/` — main app shell with nav (auth required)
- `admin/` — admin-only, role checked in layout server component
- `api/v1/` — REST API endpoints
- `api/auth/[...all]/` — Better Auth handler

**Auth**: Better Auth with Drizzle adapter. Server: `lib/auth/server.ts`. Client: `lib/auth/client.ts`. Edge-level guard is `proxy.ts` (not `middleware.ts`, which was removed) — it checks for a session cookie and redirects to `/login` for non-public paths, and additionally gates `/admin` paths. Per-route/per-page checks (`auth.api.getSession` in server components, `requireSession`/`requireSessionOrApiKey`/`requireAdmin` in API routes) are still required as defense-in-depth — don't rely on `proxy.ts` alone when adding a page or route under `(app)/` or `admin/`.

**DB**: Drizzle ORM on Postgres. Schema in `packages/db/src/schema/` split by domain: `users`, `recipes`, `social`, `meal-planning`, `tiers`. Import from `@epicure/db`.

**AI** (Phase 3): Vercel AI SDK provider factory in `apps/web/lib/ai/`. All AI outputs use `generateObject` + Zod schemas — no free-text parsing.

**Storage**: S3-compatible via `STORAGE_*` env vars. MinIO locally, any S3-compatible provider in prod.

**Tier limits**: `lib/tiers.ts` exports `checkTierLimit(userId, tier, key)` — call before recipe create and AI calls. Throws `TierLimitError` on breach.

## Adding a shadcn/ui Component

```bash
cd apps/web && pnpm dlx shadcn@latest add <component-name>
```

## Schema Changes

1. Edit `packages/db/src/schema/*.ts`
2. `pnpm db:generate` — creates migration file
3. `pnpm db:migrate` — applies it
4. Update the corresponding inline Zod schemas in the affected `apps/web/app/api/v1/**/route.ts` files (and `apps/web/lib/openapi.ts` if documented there)

## Environment Variables

See `.env.example`. Required for dev: `DATABASE_URL`, `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`. AI keys optional until Phase 3.