Pokemon Cards Inventory

A personal inventory app for tracking Pokemon TCG cards. Snap a photo, let Claude identify the cards, and track condition, foil, notes, and listed prices against live pokemontcg.io market data.

Stack: Next.js 16 (App Router, Turbopack) · React 19 · TypeScript · Tailwind v4 · HeroUI v3 · Drizzle ORM on Neon (Postgres) · Vercel Blob · Anthropic Claude (Sonnet vision) · Vitest 4. Hosted on Vercel.

• Public catalog at / — unsold copies with live pricing from pokemontcg.io.
• Per-card detail page at /card/[id] — lazy price refresh on open (>24h stale), search/filter/sort on the list.
• Admin shell at /admin behind a single shared password + signed-cookie session.
• Photo upload + identify — mobile capture → Vercel Blob → Claude vision → confirm matches → persist.
• Inventory management — list, edit (condition, foil, notes, listed price), delete.

See ROADMAP.md for the full slice-by-slice plan and current status.

cp .env.example .env.local   # fill in DATABASE_URL, ANTHROPIC_API_KEY, ADMIN_PASSWORD, COOKIE_SECRET, BLOB_READ_WRITE_TOKEN
npm install
npm run db:migrate           # apply Drizzle migrations to the Neon branch
npm run seed                 # optional — seed a couple of sample cards
npm run dev                  # http://localhost:3000

.env.example documents every required and optional variable.

src/app/           App Router routes, layouts, pages, route handlers
src/lib/           Shared modules (Neon client, auth, claude, pokemontcg, ...)
db/                Drizzle schema + generated migrations
public/            Static assets
docs/              Canonical reference docs — schema, services, flows
plans/             Per-slice planning artifacts
DESIGN.md          Design system — tokens, components, do/don't
ROADMAP.md         High-level direction (sliced)
CLAUDE.md          Agent-facing project guide

Long-form docs live under docs/ — schema, migrations workflow, pokemontcg.io contract, and the Claude vision prompt contract.

Single Neon Postgres instance backs every environment. All worktrees currently share the same dev branch, so schema migrations are cross-worktree — coordinate before destructive changes. See docs/database/migrations.md.

Hosted on Vercel. Production deploys run via .github/workflows/deploy.yml on ubuntu-latest. Vercel's own GitHub auto-deploy is intentionally off; deploys are gated on CI success. Environment variables come from the Vercel project settings; .env.example is the contract.

How deploys fire:

• Primary — auto on merge to main. Every push to main runs .github/workflows/ci.yml. When CI passes, deploy.yml triggers via workflow_run and ships. A failing CI run blocks the deploy.
• Manual (escape hatch): GitHub UI → Actions → "Deploy to Vercel (Production)" → Run workflow → ref main. Or gh workflow run deploy.yml --ref main.
• Release-triggered (audit-trail variant): gh release create vX.Y.Z — same workflow, fires on release: published.

The workflow does migrations, build, and the Vercel deploy on Linux, so native NAPI deps (@node-rs/argon2) load correctly. The previous scripts/deploy.sh is removed — there is no local-laptop deploy path; all deploys go through GitHub. See .agents/gotchas/vercel-deploy-paths.md for why.