🔮 Andernator

An AI-powered guessing game that reads your mind through strategic deduction.

Think of a character. The AI asks strategic yes/no questions, uses Bayesian probability scoring and information gain optimization to narrow down the possibilities, then makes its guess — with full reasoning transparency showing you exactly how it thinks.

Play Now →

---

Features

• Bayesian Deduction Engine — Probability scoring with information gain optimization picks the most strategic question every turn
• Reasoning Transparency — See exactly why the AI asked each question and how your answers shift probabilities
• Difficulty Selector — Easy (20q) / Medium (15q) / Hard (10q); selection persists across sessions via localStorage
• Category Filters — 8 multi-select chips (Video Games, Movies, Anime, Comics, Books, Cartoons, TV Shows, Pop Culture) narrow the candidate pool; daily challenge always uses the full pool
• Daily Challenge — Everyone thinks of the same character each day; completion state persists across sessions
• Skip Question — Skip a confusing question; the engine selects the next highest-entropy alternative without counting against the budget
• Give Up — Graceful exit after ≥5 questions; shows the character and records as a loss
• Teaching Mode — When the AI guesses wrong, teach it the character; all answered attributes are saved automatically
• User Answer Reveal — On a loss, disclose who you were thinking of; the AI backfills null attributes from your answers and queues correction votes
• Emoji Share Card — Wordle-style 🟩🟥🟨⬜ grid generated from answer history; taps the OS native share sheet on mobile, falls back to clipboard on desktop
• 53K+ Character Database — Server-side engine backed by D1 with 224 enriched attributes per character
• AI-Enhanced Answers — Free-text answer parsing via GPT-4o understands natural language responses
• Statistics Dashboard — Win/loss tracking, question performance metrics, attribute entropy analysis
• Character Comparison — Side-by-side attribute diffs, similarity scoring, discrimination power analysis
• AI Attribute Recommendations — GPT-4o suggests and fills in character attributes with detailed reasoning
• Keyboard Shortcuts — Y / N / M / U answer the current question without lifting your hands off the keyboard
• Touch-Optimized UI — Gradient answer buttons (emerald/rose/amber/slate), spring-physics guess reveal with animated rings, confetti win screen, answer history pills with stagger animation
• Offline Support — PWA with service worker caching for offline gameplay
• Sound Effects — Web Audio API tone synthesis (no audio files needed)
• Describe Yourself — 10 first-person questions map your own traits to the closest matching character in the database

Tech Stack

Layer	Technology
Framework	React 19 · TypeScript (strict) · Vite 8
Styling	Tailwind CSS v4 · shadcn/ui · motion/react
Data	Cloudflare D1 (SQLite) · R2
AI	OpenAI GPT-4o via Cloudflare AI Gateway
Platform	Cloudflare Pages + Workers
Testing	Vitest · Playwright · MSW
Icons	Phosphor Icons · Lucide
Charts	Recharts · D3

Quick Start

# Install dependencies
pnpm install

# Start dev server (http://localhost:5000)
pnpm dev

Commands

Core Daily

Command	Description
pnpm dev	Start Vite dev server
pnpm build	Type-check + production build
pnpm build:fast	Fast build without full workspace type-check
pnpm preview	Preview production build locally
pnpm typecheck	Type-check app + shared packages
pnpm lint	Run ESLint with local cache
pnpm test	Run all Vitest tests

Quality And CI

Command	Description
pnpm validate	Fast local gate (alias of pnpm validate:fast)
pnpm validate:fast	Deterministic local gate: typecheck:all + lint + test + refactor guard
pnpm mobile:guardrails	Enforce native mobile boundaries under apps/mobile (fails on web-only patterns)
pnpm validate:strict	Extended offline gate: fast + app build + worker build + migration/schema checks + coverage
pnpm validate:online	Conditional credentialed checks (runs only when required env vars are present)
pnpm validate:all	Strict + online validation lanes
pnpm typecheck:all	Type-check app, workers, and scripts
pnpm test:coverage	Run tests with coverage report
pnpm test:unit	Unit tests only (excludes components)
pnpm test:components	Component tests only
pnpm test:e2e	Playwright E2E tests (auto-starts preview server; requires a build)
pnpm size	Check named bundle size budgets
pnpm build:worker	Dry-run build check for tail worker

Deploy And Cloudflare

Command	Description
pnpm deploy	Build + deploy to Cloudflare Pages (production)
pnpm deploy:preview	Build + deploy preview branch
pnpm cf:login	Authenticate with Cloudflare
pnpm cf:dev	Local Pages + Functions dev server with bindings
pnpm deploy:tail	Deploy tail worker to production
pnpm deploy:tail:preview	Deploy tail worker to preview

Mobile (Expo iOS)

Command	Description
pnpm mobile:dev	Start Expo dev server for apps/mobile
pnpm mobile:dev:tunnel	Start Expo dev server in tunnel mode for constrained LANs
pnpm mobile:ios	Build and run apps/mobile on iOS simulator/device
pnpm mobile:typecheck	Type-check the mobile app workspace
pnpm mobile:prebuild:ios	Generate native iOS project files under apps/mobile/ios

Data And DB Ops

Command	Description
pnpm migrate:create	Scaffold a new timestamped migration file
pnpm migration:new	Alias of pnpm migrate:create
pnpm migrate:preview	Apply pending D1 migrations to preview
pnpm migrate:prod	Apply pending D1 migrations to production
pnpm db:types	Regenerate D1 row types from migrations
pnpm analytics:readiness:preview	Run guess-readiness calibration queries against preview D1
pnpm analytics:readiness:prod	Run guess-readiness calibration queries against production D1
pnpm ingest	Run data ingestion pipeline

For the complete script catalog (simulation, reconciliation, agreement scoring, and more), see package.json.

Architecture

The app runs as a React SPA on Cloudflare Pages with Workers handling API endpoints, D1 for the character database, KV for game sessions, and R2 for character images.

Client (React SPA)  →  Cloudflare Workers  →  D1 / KV / R2
                              ↓
                        AI Gateway → OpenAI

All gameplay runs through the server-side Bayesian engine, querying D1 (53K+ characters, top 500 per session). The client is a thin UI shell that sends answers and renders server-computed questions, reasoning, and guesses.

See ARCHITECTURE.md for the full system design, game engine internals, API reference, data layer details, and CI/CD pipeline.

For CI logs and downloadable artifact outputs by job, see docs/ci-artifacts.md.

Project Structure

src/
├── components/        # React components (24 feature + shadcn/ui primitives)
├── hooks/             # Custom hooks (game state, KV, server game, sound, etc.)
├── lib/               # Business logic (engine, types, database, LLM, analytics)
└── styles/            # Theme CSS (cosmic purple/indigo, Space Grotesk)
functions/api/         # Cloudflare Workers (v1 KV, v2 D1, LLM, images, admin)
scripts/               # Data ingestion & seed generation tools
migrations/            # D1 schema migrations
e2e/                   # Playwright E2E tests

Deployment

Deployed to Cloudflare Pages via wrangler. See .github/prompts/deploy.prompt.md for deployment guide and the CI pipeline for automated deployments.

pnpm deploy            # Production
pnpm deploy:preview    # Preview branch

Analytics Calibration

Guess timing now records dedicated readiness analytics in game_stats, including trigger type, forced guesses, top-gap, alive suspects, and questions remaining at guess time.

pnpm analytics:readiness:preview
pnpm analytics:readiness:prod

These commands run the query set in docs/guess-readiness-queries.sql against the remote D1 databases so threshold tuning can be based on real outcomes instead of heuristics alone.

Calibration targets and review guidance live in docs/guess-readiness-calibration.md.

D1 Operations

Use these commands for the normal schema workflow:

pnpm migrate:create
pnpm migrate:preview
pnpm migrate:prod
pnpm db:types

Apply the migration to preview first, then production, and regenerate functions/api/_db-types.ts after schema changes land.

License

MIT