Card Collection (kids-collection)

A private, kid-safe collectible-card web app. A parent signs in with Google and grants pull tokens as a reward; each child pulls cards from a shared, pre-generated, rarity-tiered, themed pool — with pictures, short educational facts, and holographic/3D card effects. Deployed on Vercel.

Increments 1–22 were built with the AI-DLC v1 workflow; those design and audit artifacts are kept as history in archive/aidlc-v1/. Current product definition lives in Product-Definition/, produced by aidlc-discovery v2 (/aidlc-discovery).

Stack

• Next.js (App Router) + TypeScript + Tailwind
• Postgres (Neon) via Drizzle ORM, migrations with drizzle-kit
• Vercel Blob for card images
• Google OAuth (parent) — added in U2
• Card images generated once (seed-time) via free image providers behind a provider seam (src/shared/pool/providers/) — added in U3

Status (build units)

Frozen since the initial build (archive/aidlc-v1/) — the product has shipped many increments on top of it since (trades, quizzes, easter eggs, sacrifice, admin oversight, …); see the git log and issue tracker for what's landed since U7.

• U1 Foundation & Data — ✅ scaffold, schema, DB client, pure logic, tests
• U2 Auth & Profiles — ✅ Google sign-in (allowlist), child profiles, picker
• U3 Pool & Seeding — ✅ seed pipeline (image providers → Blob → DB), pool reader
• U4 Pull & Rewards — ✅ atomic pull (no double-spend), duplicates, token grants
• U5 Binder — ✅ collection by theme, progress, card detail
• U6 Card UI & Effects — ✅ holographic + 3D tilt cards, rarity styling, pull reveal
• U7 Admin — ✅ parent dashboard, token grants, oversight

Seeding the card pool

To add a whole new theme, hand docs/NEW-THEME-RUNBOOK.md and a theme name to an agent — it authors the 30 cards, generates the art, and stops for your approval before publishing.

pnpm seed --check-urls # schema + every sourceUrl must return 200
pnpm seed --review     # generate preview images for NEW cards to seed-content/review/,
                       #   one per card PER lane (the bake-off)
pnpm seed --supergrok-export
                       # brief for pictures you generate by hand in Grok
pnpm supergrok "<Theme Name>" [--auto | --auto-video]
                       # walk the cards: copy each prompt, file each saved picture into the
                       #   drop folder, then run the two commands below (--auto: the
                       #   signed-in grok CLI draws each card instead; --auto-video:
                       #   animate legendary cards' picked stills, see the runbook)
pnpm seed --review --providers=supergrok-manual
                       # import that drop folder as one more bake-off column
pnpm contact-sheet "<Theme Name>"
                       # subject x provider grid to review, into seed-content/review/
pnpm theme-images "<Theme Name>"
                       # Grok (--auto) + Cloudflare lanes concurrently, then an advisory
                       #   claude-CLI pick per card in a side-by-side review table
pnpm theme-picks "<Theme Name>" [--use "<Card Name>=<provider>"]...
                       # write the judge's picks (plus any overrides) into cards.json
pnpm seed --sync       # publish the picked provider's reviewed bytes (idempotent),
                       #   recording what drew them in seed-content/provenance.json

Getting started

pnpm install

# env: provision Neon + Blob via Vercel Marketplace, then
cp .env.example .env.local   # or: vercel env pull .env.local

# database
pnpm db:migrate           # apply migrations to DATABASE_URL

# dev
pnpm dev                  # http://localhost:3000

# quality
pnpm typecheck
pnpm test                 # unit tests + property-based tests (fast-check)

Project layout

app/                  Next.js routes + layout
src/shared/           shared kernel with no outbound feature deps (modules listed in CONTRIBUTING.md)
src/features/         domain features (binder, pull, trade, admin, quiz, profiles, auth, rewards)
src/auth/             NextAuth config
src/db/               Drizzle schema, client, migrations
src/lib/              env, types, avatars, server-action shape, pure logic
scripts/              seed CLI, contact-sheet, supergrok helper, theme-images, theme-picks, reconcile, backup verify
seed-content/         card/theme source data (cards.json, provenance.json)
docs/                 operational runbooks (new theme, restore, passkey cutover, migration notes)
.claude/              Claude Code config (skills, commands, aidlc-discovery tooling)
tests/                property-based + unit tests, plus tests/contracts/ shared specs
tests-pg/             integration tests against a real dockerized Postgres
tests-live/           opt-in live tests against real external providers
Product-Definition/   current vision, technical environment, open questions
archive/aidlc-v1/     AI-DLC v1 design + audit artifacts (increments 1–22, history)
archive/prototypes/   retired prototype scripts, kept as reproducers (run with tsx)

See CONTRIBUTING.md for which of tests/, tests-pg/, tests-live/ to add a test to.

Data model

• themes 1—* cards (shared pool; rarity ∈ common/rare/epic/legendary)
• children (per-family; pull_tokens >= 0 starts at 3, easter_egg_tickets >= 0)
• collections (childId+card_id PK, count >= 1 for duplicates)
• quiz_completions (one row per quiz attempt), quiz_seen_questions (answered question ids, dedupes the question bank per child/topic)
• collection_rewards (one row per rewarded child/theme/rarity set-completion bonus)
• admin_credentials (parent-gate WebAuthn passkeys)