WordZoo

Language learning that makes words stick. Every word gets an AI keyword mnemonic — a sound-alike word, a scene, an illustration and a Neural voice clip — and is then drilled (recognition, typing, cloze), practised in a scripted conversation, and scheduled by a spaced-repetition engine so it comes back right before it is forgotten. Indonesian first; Spanish, Portuguese and a Japanese demo.

Live: https://wordzoo.vercel.app · Try it without an account: https://wordzoo.vercel.app/try

Stack

Next.js 16 (App Router, React 19, TypeScript) · Neon Postgres via raw SQL · NextAuth v5 (Google) · Tailwind v4 + shadcn/ui · Gemini 2.5 Flash · Stability AI · Google Cloud TTS · Vercel Blob · Stripe · Vercel.

Run it

cp .env.example .env.local     # fill in DATABASE_URL, AUTH_*, GOOGLE_GEMINI_API_KEY at least
npm install
npm run dev                    # http://localhost:8000  (port 8000, not 3000)

Sign in without Google in development: http://localhost:8000/api/auth/[email protected] (404s on Vercel). Admin pages need the email in ADMIN_EMAILS.

Check it

npm run lint          # ESLint
npx tsc --noEmit      # types
npm test              # Vitest: lib/srs/engine, lib/pedagogy/leitner, lib/pedagogy/normalize
npm run test:e2e      # Playwright smoke of /try and the learn loop (needs `npm run dev` on :8000)

Where things are

Path	What
app/try/	The public demo — three words, no account, static data
app/(app)/learn/[sceneId]/ + components/learn/SceneFlowClient.tsx	A scene: dialogue → phrases → drill → vocabulary → drill → conversation → summary
lib/pedagogy/	Leitner drill queue, exercise pickers, typo tolerance, feature flags
lib/srs/engine.ts	The scheduler (SM-2 derived; only the review queue lengthens intervals)
lib/spend-guard.ts, lib/spend-ledger.ts	Every AI / image / TTS / Blob route claims budget first
lib/services/	Billing, tutor, mnemonics, paths, email
lib/db/	Raw SQL queries, schema, seed scripts, hand-authored content
app/api/cron/	Vercel crons; digests/ is written nightly and read by the Claude triage agent
docs/	Audits, curriculum, product evaluations

CLAUDE.md is the working manual (conventions, cron table, spend guard, access control, the nightly routine). docs/audit-2026-09.md is the latest full audit.

Content pipeline

Scene content is authored in lib/db/content/<lang>/ and seeded with npm run db:seed-expanded. Mnemonics, audio and images are generated by the db:seed-* scripts — read the Gemini quota note in CLAUDE.md first; the free tier is shared with the live tutor.