DEV Community: Prateek Mohan

React 19, Zustand, a 5-Provider AI Broker, and P2P Multiplayer — How I Architected My Learning Platform

Prateek Mohan — Tue, 31 Mar 2026 05:44:34 +0000

Posted by Prateek | March 2026

I shipped React 19 in production when it was still RC. Not because I love living dangerously — well, maybe a little — but because I was building PatternMaster from scratch and there was no legacy to protect. When you're starting fresh, you pick the best tools available right now, not the ones that were best two years ago.

This is the architecture post. Blog 1 covered the overall vision, Blog 2 covered the game mechanics. This one is for the people who want to know how it's actually built — the state management, the AI plumbing, the theme system, the database decisions. Grab a coffee.

The Stack (and Why I Made These Choices)

Let me be upfront: I didn't pick these tools to flex. I picked them because each one solved a specific problem I had.

React 19.2.0 + Vite 7.1.9 — React 19 shipped concurrent features that genuinely matter for an app that's doing heavy AI streaming and 3D rendering simultaneously. The server actions model didn't apply here (Express backend), but the use() hook and improved Suspense boundaries cleaned up a lot of ugly loading state code. Vite 7 is just fast. It takes about 300ms to cold-start the dev server. I'll never go back to webpack.

TailwindCSS 4.1.14 — Tailwind v4 rewrote the engine in Rust and dropped the PostCSS dependency. Build times dropped noticeably. But the real win for me was the new CSS variable integration — I'll explain this later when I get to the theme system.

Zustand 5.0.10 — I tried Redux Toolkit first. For about a week. The amount of boilerplate for something as simple as "update a card's review interval" was embarrassing. Zustand lets me write state logic that reads like plain JavaScript. Zustand 5 dropped some legacy API surface and made TypeScript inference significantly better. Zero regrets.

Wouter 3 — React Router is a framework now. I didn't need a framework. I needed a router. Wouter is ~2.1KB, does exactly what I need (hash routing, params, programmatic navigation), and has zero opinions about my data fetching strategy. For a Vite SPA with an Express backend, it's perfect.

Drizzle ORM 0.39.3 + PostgreSQL — I tried Prisma first. Prisma is excellent but the generated client is chunky and the migration story felt heavy for a project that changes schema often. Drizzle is schema-as-code with SQL-first thinking. The drizzle-zod integration means my Zod validation schemas are derived from my database types automatically — no duplication.

Three.js 0.183.0 + React Three Fiber 9.5.0 — The 3D games (zombie FPS, runner, invaders) need actual WebGL. There's no HTML/CSS substitute for a procedural terrain zombie shooter. R3F makes Three.js composable with React's component model, which makes things like "conditionally render rain particles only when the weather system says so" natural.

State Architecture: Zustand + IndexedDB

This is probably the most interesting non-obvious decision in the whole project.

Early versions used localStorage for persistence. This worked fine until users started generating substantial content — 40+ AI-generated units, hundreds of review cards, visualization histories. localStorage is synchronous and has a 5MB cap. Hitting that cap caused silent failures that were a nightmare to debug.

The fix was switching to IndexedDB via idb-keyval, with localStorage as a silent fallback:

// client/src/lib/store/index.ts
import { get as idbGet, set as idbSet, del as idbDel } from 'idb-keyval';

const idbStorage: StateStorage = {
  getItem: async (name) => {
    try {
      return (await idbGet<string>(name)) ?? null;
    } catch {
      // IndexedDB can fail in private browsing on some browsers
      try { return localStorage.getItem(name); } catch { return null; }
    }
  },
  setItem: async (name, value) => {
    try {
      await idbSet(name, value);
    } catch {
      try { localStorage.setItem(name, value); } catch { /* quota exceeded */ }
    }
  },
  // ...
};

The fallback chain is intentional. Safari private browsing blocks IndexedDB. Firefox sometimes blocks it in strict mode. Rather than showing an error, the app silently degrades to localStorage, and if that fails (quota exceeded), it just doesn't persist — the app still works, just without offline state. This is the right tradeoff for a learning tool.

The Partialize Problem

Zustand's persist middleware has a partialize option that lets you control exactly what gets serialized. Without it, you serialize everything — including base64-encoded AI-generated images that are sometimes 500KB each. I learned this the hard way.

partialize: (state) => ({
  units: state.units.map(stripHeavyUnitPayload).slice(-40),
  reviewCards: state.reviewCards,
  reviewCardState: state.reviewCardState,
  // ... other lightweight slices
}),

stripHeavyUnitPayload strips the imageUrl field from unit images before persisting — the URLs are regenerated on demand anyway. The .slice(-40) keeps only the 40 most recent units. This brought storage usage from "frequently hitting quota" to "never hitting quota."

Slice Architecture

The store is split into four slices:

reviewSlice.ts — SM-2 spaced repetition state (card intervals, efactors, phases, due dates)
contentSlice.ts — Units and lesson plans (the AI-generated learning content)
gameSlice.ts — Active card selection, question pools, game preferences
index.ts — Composes the slices, handles migrations, owns the persistence config

The migration system has 16 versions. Every time I change the shape of persisted state, I add a migration step. This means existing users don't lose their data when the schema changes — their stored JSON gets transformed forward. It's tedious but it's the right thing to do.

Server Sync Pattern

The store is the source of truth for the UI, but everything important gets synced to the server. On login:

// Hydrate from server, merge with local state
Promise.allSettled([
  fetchReviewSnapshot(),        // SM-2 states from DB
  fetch("/api/user/content"),   // Units and lesson plans
  fetch("/api/user/settings"),  // Profile, theme, AI settings
]).then(([reviewResult, contentResult, settingsResult]) => {
  // Reconcile: server wins for review states (prevents grade drift)
  // Merge: local wins for content (offline edits preserved)
  // Clean up orphaned cards (units deleted on another device)
});

After hydration, changes write to both Zustand (instant UI update) and the server (debounced, 2 second delay). This means the UI is always snappy and the server always eventually catches up. The debounce prevents a flood of requests when someone is rapidly grading review cards.

The AI Broker: 5 Providers, One Interface

This is the part I'm most proud of architecturally. Every AI call in the app goes through a single endpoint: POST /api/ai/complete. Behind that endpoint is a broker that handles provider selection, fallback, budget enforcement, deduplication, and observability.

The Core Request Flow

// server/ai/broker.ts
export async function handleBrokerComplete(req: BrokerRequest): Promise<BrokerResponse> {
  // 1. Validate request schema (Zod)
  const parseResult = BrokerRequestSchema.safeParse(req);

  // 2. Validate context for subphase
  // (e.g., repair operations need specific context fields)
  const ctxValidation = validateContext(subPhase, context);

  // 3. Deduplication — prevents identical concurrent calls
  const promptHash = createHash(prompt + (imageDataUrl?.slice(0, 100) ?? ""));
  const dedupKey = dedupeKey(mode, phase, subPhase, promptHash, imageHash);

  if (inFlight.has(dedupKey)) {
    console.info(`[broker] Dedup hit for ${dedupKey}`);
    return inFlight.get(dedupKey)!;  // Return the in-flight promise
  }

  // 4. Get ordered provider list based on policy
  const providerPairs = getProviderOrder(phase, subPhase, aiSettings);

  // 5. Build prompt with system template + context
  const systemTemplate = getSystemTemplate(subPhase);
  const builtPrompt = buildPrompt(prompt, context, systemTemplate);

  // 6. Execute with fallback chain
  // 7. Record workflow run for observability
  // 8. Return response
}

The deduplication map (inFlight) is a plain Map<string, Promise<BrokerResponse>>. If the same prompt is requested twice before the first one finishes, the second caller gets the same Promise. This happens more often than you'd think — streaming responses, retries, React StrictMode double-renders.

The Policy Engine

Every AI request has a phase and subPhase. The phase is things like unitGeneration, tutorChat, reviewCardGen. The subPhase is more granular — repair, tool-select, streaming, etc.

// server/ai/policy.ts
export function enforcePolicy(phase: AIPhase, subPhase: AISubPhase): EnforcedPolicy {
  const phaseCfg = PHASE_POLICY[phase];

  // Strict subphases (repair, tool-select) get hard caps
  if (isStrictSubPhase(phase, subPhase)) {
    return {
      maxModels: 1,      // Only one model attempt
      maxProviders: 1,   // Only one provider attempt
      timeoutMs: phaseCfg.timeoutMs,
    };
  }

  return {
    maxModels: phaseCfg.maxModelsPerProvider,
    maxProviders: phaseCfg.maxProviders,
    timeoutMs: phaseCfg.timeoutMs,
    maxOutputTokens: phaseCfg.maxOutputTokens,
  };
}

Why cap repair subphases to 1x1? Because repair operations are idempotent JSON fixes — if the first call returns garbage JSON, retrying with a different provider usually just returns different garbage. Better to fail fast and surface the error than to burn 3 providers in sequence.

Free Tier vs Paid Tier Routing

This was the trickiest part to get right. The app supports two modes:

Free tier: User has no personal API keys. The platform uses its own API keys (stored as DEFAULT_GEMINI_KEY, DEFAULT_GROQ_KEY, etc. in env). Limited to a smaller model (gemini-3.1-flash-lite-preview) with stricter budget caps.
Paid tier: User brings their own API keys via Settings. Gets access to the full fallback chain (Gemini → OpenAI → Groq → Claude) and their preferred primary provider.

export function isFreeTier(aiSettings: AISettings): boolean {
  return !(
    hasKey(aiSettings.geminiKey) ||
    hasKey(aiSettings.openaiKey) ||
    hasKey(aiSettings.claudeKey) ||
    hasKey(aiSettings.groqKey)
  );
}

Free tier users still get a functional app — just with less powerful models and more conservative timeouts. It's the right product decision: let people try it before committing to API key management.

Web Grounding via DuckDuckGo

The tutor chatbot can optionally search the web for context. Rather than paying for a search API, I built a DuckDuckGo scraper:

export async function fetchDuckDuckGoGrounding(query: string): Promise<string> {
  const normalized = query.replace(/\s+/g, " ").trim().slice(0, 240);

  // Try instant answers API first
  const instantEndpoint = `https://api.duckduckgo.com/?q=${encodeURIComponent(normalized)}&format=json&no_html=1`;
  const data = await fetch(instantEndpoint).then(r => r.json());

  if (data?.AbstractText) snippets.push(`- ${data.AbstractText}`);
  // ... collect related topics

  // Fall back to HTML scraping if instant answers are sparse
  if (snippets.length < 3) {
    const htmlRes = await fetch(`https://duckduckgo.com/html/?q=${...}`);
    // Parse result snippets from HTML
  }

  return `Web search context (DuckDuckGo):\n${snippets.join("\n")}`;
}

The results get prepended to the AI prompt as grounding context. It's not perfect — DuckDuckGo's instant answer API is hit-or-miss — but it's free and usually good enough for CS/DSA questions.

Workflow Observability

Every AI call gets logged to the workflow_runs table:

// schema.ts
export const workflowRuns = pgTable("workflow_runs", {
  userId: text("user_id"),
  phase: text("phase").notNull(),
  provider: text("provider").notNull(),
  model: text("model").notNull(),
  inputTokens: integer("input_tokens"),
  outputTokens: integer("output_tokens"),
  latencyMs: integer("latency_ms").notNull(),
  status: text("status").notNull(),  // 'success' | 'error' | 'timeout'
});

The admin panel visualizes this in real time — which providers are being hit, average latency per phase, error rates. When Gemini has an outage, I can see it immediately in the dashboard. When a particular prompt phase is consistently timing out, I know to increase the budget for that phase.

The 17-Variable CSS Theme System

Every color in the entire app flows through 17 CSS custom properties. No hardcoded hex values anywhere. This is a rule I enforced from day one and it paid off enormously.

The Token Set

// client/src/lib/themes.ts
export type ThemeTokenKey =
  | "--color-brand-primary"       // Main accent (cyan, green, gold...)
  | "--color-brand-primary-dark"  // Darker variant for hover states
  | "--color-brand-secondary"     // Secondary accent
  | "--color-brand-background"    // Page background
  | "--color-brand-card"          // Card background
  | "--color-brand-text"          // Primary text
  | "--color-brand-text-light"    // Muted text
  | "--color-surface-1"           // Primary surface (modals, sheets)
  | "--color-surface-2"           // Secondary surface
  | "--color-surface-border"      // Border color
  | "--app-bg-start"              // Gradient background start
  | "--app-bg-mid"                // Gradient background mid
  | "--app-bg-end"                // Gradient background end
  | "--color-surface-code"        // Code block background
  | "--color-surface-code-border" // Code block border
  | "--color-text-code"           // Code text color
  | "--app-glow-1"                // Primary glow (box-shadows, halos)
  | "--app-glow-2"                // Secondary glow
  | "--app-glow-3";               // Tertiary glow

The four built-in themes:

Hyper Dark — Deep space, holographic cyan, mono font. This is the default and the one you see in all the screenshots. hsl(186 100% 56%) is the brand primary — that vivid cyan that feels like a holographic HUD.
Arcade Neon — Electric green on near-black, purple highlights. Feels like a CRT monitor from 1988.
Cyber-Dojo — Gold and crimson, like a dojo with a GPU. The most dramatic one.
Calm Latte — Warm off-whites and browns. For people who want to study without feeling like they're piloting a spacecraft.

AI-Generated Custom Themes

The wild part: users can describe a theme in natural language ("dark purple with gold accents, corporate feel") and the AI generates a complete ThemePreset object — all 17 token values plus the style axes:

interface ThemeStyle {
  borderRadius: "sharp" | "rounded" | "pill";
  fontVibe: "mono" | "tech" | "elegant" | "casual";
  glowIntensity: "none" | "subtle" | "medium" | "intense";
  animationLevel: "none" | "calm" | "lively" | "intense";
  decorativeOverlay: boolean;
}

The style object drives dynamic CSS generation — generateCustomThemeCSS() produces about 500 lines of CSS including keyframe animations (aiThemePulse, aiThemeShimmer), backdrop filters, font family overrides, and responsive border radius remapping. All injected into <head> at runtime.

The injection approach means no flash of unstyled content — the theme is applied synchronously from Zustand state before the first paint.

Cosmo: The Animated Mascot System

Every page in the app has a floating mascot called Cosmo. It's a WebM animation player that reacts to page navigation, user state, and random ambient timers.

// client/src/components/avatar/CosmoFloating.tsx

// Page-specific greeting animations
const PAGE_ANIMATIONS: Record<string, CosmoAnimation> = {
  "/": "wink",
  "/review": "reading",
  "/play": "celebrate",
  "/learn": "hint",
  "/visualize": "explaining",
};

When you navigate to the Review page, Cosmo plays a "reading" animation — bookish, focused. When you navigate to Play, Cosmo does a "celebrate" animation — arms out, excited. It's a small thing but it makes the app feel alive.

Weighted Random Idle Animations

Between events, Cosmo plays ambient animations on a randomized schedule:

const IDLE_VARIETY: CosmoAnimation[] = [
  "idle", "idle", "idle",  // 3x weighted toward plain idle
  "wink", "reading", "think",
  "nod", "wave", "hint",
  "surprise", "confused",
];

The triple-weighting of "idle" means Cosmo spends most of its time in a calm bobbing state. The variety animations fire occasionally — a wink here, a confused look there. It prevents the mascot from feeling like a broken GIF loop without being distracting.

Smart Contextual Suggestions

Cosmo isn't purely decorative. It watches the store:

const suggestions = useMemo(() => {
  const dueCount = reviewCards.filter((c) => {
    const st = reviewCardState[c.id];
    return st && st.phase === "review" && st.dueAt <= Date.now();
  }).length;

  const activeEntry = Object.entries(lessonSessions)
    .find(([, s]) => s && s.step > 0);
  const activeUnit = activeEntry
    ? units.find((u) => u.id === activeEntry[0])
    : null;

  return getCosmoSuggestions({
    currentPath: location,
    dueReviewCount: dueCount,
    activeLesson: activeUnit ? { id: activeUnit.id, title: activeUnit.title } : null,
    totalUnits: units.length,
  });
}, [location, units, reviewCards, reviewCardState, lessonSessions]);

If you have 15 cards due for review and you're on the Play page, Cosmo gently suggests you might want to review first. It's not pushy — just contextually aware.

The mascot system has 17 animations (idle, wink, celebrate, confused, explaining, hint, learning, loading, reading, recursion, thinking, wave, and more), each a ~2MB WebM that gets lazy-loaded on demand.

The Database Schema: 17 Tables

The schema lives in shared/schema.ts (shared between client types and server ORM). Here's what's actually in there:

Table	Purpose
`users`	Auth — username, passwordHash, role
`userProgress`	Completed/unlocked units, Parsons progress
`flashcardStates`	Legacy SM-2 state (pre-migration)
`generatedUnits`	Units with provenance metadata (which provider/model generated them)
`trackedProblems`	In-progress AI generation jobs
`reviewCards`	Card data with full JSONB blob
`reviewCardStates`	SM-2 state per card (JSONB for flexibility)
`userSettings`	Theme, profile, preferences
`userContent`	Units + lesson plans as JSONB blob
`userGameQuestionPrefs`	Selected cards + generated question pools
`visualizations`	Saved AI-generated Remotion scenes
`sharedModels`	3D model blueprints shared across users
`workflowRuns`	AI request audit log
`promptVersions`	Prompt template versioning by SHA-256 hash
`gameResults`	Game session results for progress tracking
`conceptMastery`	Per-concept mastery signals
`weaknessSignals`	Topics the system identifies as weak areas

The mix of JSONB blobs and normalized tables is intentional. userContent and userSettings are pure JSONB — the shape changes frequently as I add features, and I don't want a migration for every new field. reviewCardStates is JSONB for the SM-2 data (it's a known-shape struct, but I want to be able to add fields without migrations). Tables like workflowRuns are fully normalized because I query them with aggregations.

This dual-write pattern is practical, not principled. Pure relational would be more correct. But "more correct" and "ships faster" are often in tension, and for a solo project, shipping faster wins.

What I'd Do Differently

1. Start with the broker design from day one. The first version of the AI integration was direct calls to Gemini from the frontend (yes, with the API key in client code — don't judge me, it was a prototype). Extracting this to a proper server-side broker took two solid days. If I'd designed the broker interface first, those two days would've been building features instead.

2. IndexedDB from the start. Same deal — started with localStorage, hit quota issues, had to migrate. The migration was painful because I had to write a data migration that ran in the browser and moved existing data. It worked, but it was a weekend I didn't enjoy.

3. The Wouter choice holds up. I've seen blog posts arguing you should use React Router for "real" apps. PatternMaster has 30+ routes, lazy loading, auth guards, and nested layouts. Wouter handles all of it. The "real app needs React Router" argument is vibes, not evidence.

4. TypeScript strictness from day 1. I started with strict: false and gradually tightened it. This was wrong. The type errors I found when tightening strictness were real bugs — nullable values being accessed unsafely, union types being narrowed incorrectly. Start strict, stay strict.

5. The theme system architecture is correct. The "17 CSS variables only, never hardcode" rule felt pedantic when I first imposed it. Six months later, with 4 built-in themes and AI-generated custom themes, I'm very glad I enforced it. Every component that uses var(--color-brand-primary) instead of #38bdf8 gets themes for free. Every component that had a hardcoded color was a bug I had to track down manually.

What's Next

The architecture is stable enough to build on. The next big thing is a proper multiplayer layer — players sharing a game session, answering questions in real time, competing for XP. The broker design already accommodates this (requests are user-scoped, not session-scoped). The schema has the concept of sessionId throughout. The pieces are there.

After that, the weak spot is the analytics layer. workflowRuns gives me AI observability, but weaknessSignals and conceptMastery are tables I've built but not yet fully populated. The vision is a recommendation engine that looks at your SM-2 state, your game performance, and your chat history, and tells you exactly what to study next. Right now it's just vibes. Soon it'll be data.

If you're building something similar — AI-powered, state-heavy, multi-provider — I hope the patterns here are useful. The broker pattern especially. The moment you have more than one AI provider, you want a layer of abstraction between your product code and the API calls. The deduplication alone has saved me from some very embarrassing race conditions.

PatternMaster is a personal project I'm building in public. The codebase covers React 19, Three.js FPS games, spaced repetition, multi-provider AI, and a lot of things I'll probably regret later. Posts in this series: [Blog 1 - Overview], [Blog 2 - Games], Blog 3 - Architecture (this one).

Questions, roasts, or architecture suggestions — find me at the usual places.

Tags: #react #zustand #typescript #ai #webdev #architecture #postgresql #threejs

I Turned Flashcards Into a Zombie FPS, a Runner Game, and Tetris — Here's How

Prateek Mohan — Tue, 31 Mar 2026 05:44:26 +0000

Cross-posted from my dev.to series on building PatternMaster, an AI-powered DSA learning platform.

Most "gamified" learning apps use games as a reward. Finish your lesson → get to play a little minigame for 30 seconds. It's basically digital candy. The studying and the game are completely separate things.

I wanted to flip that. What if the game was the studying? What if every zombie you shoot is carrying one of your flashcard questions, and the body part you aim for determines which answer you pick? What if the wrong lane in a runner game costs you health? What if your Tetris pieces are literally labeled with multiple-choice answers?

That's what I built. Three full games — a 3D zombie FPS, a Subway Surfers-style runner, and Tetris — all powered by the same flashcard content you're already studying. The same cards you're reviewing with spaced repetition show up as game questions. Study hard = better at the games. It's a loop that actually closes.

Here's how it works under the hood.

The Core Insight: Your Flashcards ARE the Game Content

Before I get into any specific game, let me explain the architecture decision that makes all of this possible, because it's the thing that took me the longest to figure out.

Early in development, I had two separate systems: a review card system and a game question system. The game questions were AI-generated specifically for gameplay, and they were completely separate from your spaced repetition cards. This meant:

Generating questions twice (once for review, once for games)
Managing two databases
Questions getting out of sync
Extra AI API calls burning through my quota

The fix was obvious in retrospect: review cards ARE game questions. The conversion is trivial:

// client/src/games/questions/provider.ts

/** Convert a review card to a game question — no AI needed */
export function reviewCardToQuestion(card: ReviewCard): ZombieQuestion | null {
  if (card.type !== 'concept') return null;

  const options = card.options ?? [card.back];
  const correctIndex = card.correctIndex ?? 0;

  return {
    id: `rc:${card.id}`,
    source: card.source === 'seed' ? 'review_card' : 'ai_card',
    originCardId: card.id,
    originCardLabel: card.tags?.[0] ?? card.unitId,
    originCardType: 'concept',
    questionText: card.front,   // front of card → question prompt
    answer: card.back,          // back of card → correct answer
    options,
    correctIndex,
    explanation: card.back,
    xpValue: 10,
  };
}

The comment in the file says it best: "Phase 2 simplification: review cards ARE the game questions." No separate generation. Your card front becomes the question. Your card back becomes the answer. Any distractor options the card already has get used; if it doesn't have enough, we pull from other cards' backs to generate them on the fly.

The question pool for all three games is computed reactively via a shared hook:

// client/src/games/shared/useSharedQuestionSetup.ts

export function useSharedQuestionSetup(reviewCards: ReviewCard[]): SharedQuestionSetup {
  const selectedCardIds = useStore((s) => s.activeCardIds);

  // Compute question pool reactively from review cards — no AI, instant
  const questionPool = useMemo(() => {
    const conceptCards = reviewCards.filter(c => c.type === 'concept');
    const raw = buildQuestionPool(conceptCards);
    return ensureDistractors(raw, reviewCards);
  }, [reviewCards]);

  // Filter to only questions matching selected cards
  const filteredPool = useMemo(() => {
    if (selectedCardIds.length === 0 && questionPool.length > 0) return questionPool;
    const selectedSet = new Set(selectedCardIds);
    const matched = questionPool.filter((q) => q.originCardId && selectedSet.has(q.originCardId));
    return matched.length > 0 ? matched : questionPool;
  }, [questionPool, selectedCardIds]);

  return { questionPool, filteredPool, selectedCardIds, ... };
}

Every game calls this same hook. Change your review card selection, and all three games update instantly. No regeneration, no loading spinner, no extra API cost.

The Hyper Zombie FPS

This is the main event. A full 3D first-person zombie shooter built in vanilla Three.js (not React Three Fiber — the engine needed fine-grained control that a declarative wrapper would have made painful).

The pitch: zombies walk toward you. Each zombie has a question. Its five body parts correspond to the five answer options. You shoot the correct body part. Wrong answers cost health. Right answers kill the zombie and give you XP that feeds back into your spaced repetition system.

The 5-Zone Body System

This is the mechanic that makes the whole game idea work. Each zombie's body is divided into five hitboxes:

// client/src/games/hyper/types.ts

export type ZoneKey = "head" | "chest" | "leftArm" | "rightArm" | "legs";

export const ZONE_TO_ANSWER_INDEX: Record<ZoneKey, number> = {
  head: 0,      // Answer A
  chest: 1,     // Answer B
  leftArm: 2,   // Answer C
  rightArm: 4,  // Answer E
  legs: 3,      // Answer D
};

export const ZONE_LABEL: Record<ZoneKey, string> = {
  head: "A",
  chest: "B",
  leftArm: "C",
  rightArm: "E",
  legs: "D",
};

Each zone has a 3D hitbox in the zombie model's local space, with a slight forgiveness multiplier so shots that barely clip the edge still register:

// client/src/games/hyper/engine/constants.ts

export const HITBOX_FORGIVENESS_SCALE = 1.3;
export const ZONE_HITBOXES: Record<ZoneKey, { offset: [number,number,number]; size: [number,number,number] }> = {
  head:     { offset: [0,    0.90, 0],    size: [0.18, 0.18, 0.18] },
  chest:    { offset: [0,    0.65, 0],    size: [0.30, 0.25, 0.20] },
  leftArm:  { offset: [-0.22, 0.62, 0],  size: [0.12, 0.30, 0.12] },
  rightArm: { offset: [ 0.22, 0.62, 0],  size: [0.12, 0.30, 0.12] },
  legs:     { offset: [0,    0.25, 0],    size: [0.25, 0.35, 0.18] },
};

// Each zone gets a color for the floating answer label
export const ZONE_COLOR_MAP: Record<ZoneKey, string> = {
  head: '#ef4444',      // red — Head = A
  chest: '#3b82f6',     // blue — Chest = B
  leftArm: '#22c55e',   // green — Left Arm = C
  rightArm: '#f59e0b',  // amber — Right Arm = E
  legs: '#8b5cf6',      // violet — Legs = D
};

The engine supports two rigging formats. Kenney-style models (the low-poly pack) use node-name-based detection, walking up the parent chain until you hit a recognized name. Mixamo/FBX-style models use bone prefix matching. Both fallback to the same zone system:

// client/src/games/hyper/engine/types.ts

/** Walk up the parent chain of a mesh to find a named body-part node (Kenney rigs) */
export function getZoneFromNodeParentChain(object: THREE.Object3D): ZoneKey | null {
  let current: THREE.Object3D | null = object;
  while (current) {
    const zone = NODE_NAME_TO_ZONE[current.name];
    if (zone) return zone;
    current = current.parent;
  }
  return null;
}

// Bone name prefix → ZoneKey for mixamo rigs
export const BONE_ZONE_PREFIXES: [string, ZoneKey][] = [
  ["mixamorigHead", "head"], ["mixamorigNeck", "head"],
  ["mixamorigSpine", "chest"], ["mixamorigHips", "chest"],
  ["mixamorigLeftArm", "leftArm"], ["mixamorigLeftForeArm", "leftArm"],
  ["mixamorigRightArm", "rightArm"], ["mixamorigRightForeArm", "rightArm"],
  ["mixamorigLeftUpLeg", "legs"], ["mixamorigLeftLeg", "legs"],
  // ...
];

Slow-Motion Focus: The "Matrix" System

When you aim your crosshair at a zombie that has a question loaded, time slows to 12% speed. Enough to read the question floating above the zombie, see which answer maps to which body part, and take your shot. It's a mechanic I'm genuinely proud of — it makes the game feel like a power fantasy AND it actually gives you time to think about the answer.

// client/src/games/hyper/HyperGameEngine.ts (simplified)

// Heavy slow-mo (0.12) when a zombie question is focused — gives time to read & answer
// Both PC and mobile get this effect
const hasQuestion = this.focusedZombieIndex !== -1;
const matrixTarget = hasQuestion && !this.gameState.isShooting
  ? 0.12  // 88% slow — lots of time to read question and pick answer
  : 1;

const blendSpeed =
  matrixTarget < this.simTimeScale
    ? ENGINE_CONFIG.MATRIX.ENTER_SPEED   // snap into slow-mo fast
    : ENGINE_CONFIG.MATRIX.EXIT_SPEED;   // ease out slower

this.simTimeScale = THREE.MathUtils.lerp(
  this.simTimeScale,
  matrixTarget,
  Math.min(1, rawDelta * blendSpeed),
);
delta = rawDelta * this.simTimeScale;

The sim time scale affects everything in the game loop: bullet speed, zombie movement, animation mixers, particle systems. The sky phase manager deliberately uses real time, not sim time — you don't want day/night transitions stuttering during slow-mo.

18 Weapons, 9 Enemy Types

Each of the 18 weapons (blaster-a through blaster-r) has completely differentiated stats — damage, ammo capacity, fire rate, reload time, bullet spread, sound, and even visual properties like bullet tracer color and muzzle flash color:

// client/src/games/hyper/types.ts (excerpt)

export const WEAPON_MODELS: Record<WeaponType, WeaponModelConfig> = {
  "blaster-a": {
    name: "Pulse Pistol",
    damage: 10, maxAmmo: 12, shootCooldown: 0.20, reloadTime: 1.5,
    description: "Reliable starter sidearm",
    bulletColor: "#00ffcc", muzzleColor: "#00ffcc",
    bulletSize: 1.0, recoilKick: 0.15, spread: 1,
    fireSound: "pew"
  },
  "blaster-b": {
    name: "Ion Rifle",
    damage: 7, maxAmmo: 30, shootCooldown: 0.10, reloadTime: 2.2,
    description: "Full-auto assault rifle",
    bulletColor: "#3b82f6", muzzleColor: "#60a5fa",
    bulletSize: 0.8, recoilKick: 0.08, spread: 2,
    fireSound: "burst"
  },
  // ...16 more
};

The enemy types range from easy Zombies to tanky Orcs and Keepers. Each has its own model, scale, speed/health/damage multipliers, and animation clips. The Vampire sprints at 1.5x base speed. The Orc has 2x health but moves at 0.8x speed. The Ghost has half health but moves at 1.8x — fragile but fast.

orc: {
  name: "Orc", scale: 4.6, speed: 0.8, health: 2.0, damage: 2.0,
  difficulty: "hard",
  walkAnim: "walk", hitAnim: "hit-react",
},
vampire: {
  name: "Vampire", scale: 4.0, speed: 1.5, health: 1.2, damage: 1.5,
  walkAnim: "sprint",  // vampires have a sprint animation instead of walk
},

Procedural Worlds with Seeded RNG

Every map is procedurally generated from a seed number. Same seed = same world, every time. The WorldGenerator picks props based on the active theme (graveyard, urban, wasteland, fortress, or random), places them using a weighted probability system, and registers their bounding boxes with the collision system:

// client/src/games/hyper/WorldGenerator.ts

export type WorldTheme = 'graveyard' | 'urban' | 'wasteland' | 'fortress' | 'random';

const GRAVEYARD_PROPS: PropDef[] = [
  { path: 'cross.glb',        weight: 5, baseScale: 3.0 },
  { path: 'coffin.glb',       weight: 2, baseScale: 3.0 },
  { path: 'crypt.glb',        weight: 1, baseScale: 4.5, large: true },
  { path: 'altar-stone.glb',  weight: 2, baseScale: 3.0 },
  { path: 'fence.glb',        weight: 4, baseScale: 3.0 },
  { path: 'fire-basket.glb',  weight: 3, baseScale: 3.0 },
];

const FORTRESS_PROPS: PropDef[] = [
  { path: 'column-large.glb',    weight: 3, baseScale: 4.5, large: true },
  { path: 'fence-fortified.glb', weight: 4, baseScale: 3.5 },
  { path: 'brick-wall.glb',      weight: 3, baseScale: 3.5 },
];

The seeded RNG (mulberry32) ensures reproducibility. If you share a seed with a friend, you both get the exact same map layout. This matters for the multiplayer mode.

Dynamic Day/Night: SkyPhaseManager

The world has five lighting phases — dawn, day, sunset, dusk, night — each with completely different sky gradients, fog density, ambient and directional light colors, and tone mapping exposure. They transition smoothly over time:

// client/src/games/hyper/engine/SkyPhaseManager.ts

export const SKY_PHASES: Record<SkyPhase, SkyPhaseConfig> = {
  dawn: {
    skyTop:      new THREE.Color(0x1a0a2e),  // deep purple
    skyHorizon:  new THREE.Color(0xff7744),  // orange glow
    fogDensity: 0.007,
    ambientColor: new THREE.Color(0xffaa88),
    ambientIntensity: 0.5,
    exposure: 2.2,
  },
  night: {
    skyTop:      new THREE.Color(0x020210),  // near black
    skyHorizon:  new THREE.Color(0x0a0a30),  // dark blue
    fogDensity: 0.010,                       // denser fog at night
    ambientColor: new THREE.Color(0x4466aa),
    ambientIntensity: 0.25,
    exposure: 1.8,
  },
  // dawn, day, sunset, dusk in between
};

Night mode is genuinely spooky. The fog density cranks up and the ambient light drops to barely-visible, which creates this oppressive atmospheric pressure. Perfect for a zombie game.

P2P Multiplayer via Trystero — Zero Server Cost

The multiplayer system uses Trystero, which creates WebRTC connections routed through free public Nostr relays. No dedicated game server. No monthly bill. Just peer-to-peer.

// client/src/games/hyper/MultiplayerClient.ts

/**
 * MultiplayerClient — P2P multiplayer for Hyper Zombie via Trystero (WebRTC).
 * No server required. Players connect directly via free Nostr relays.
 *
 * - Send player position at ~20Hz
 * - Receive + interpolate other players' positions
 * - Render remote players as colored capsules with nametag sprites
 */

import { joinRoom, type Room } from 'trystero/nostr';

const PLAYER_COLORS = [0x3b82f6, 0x22c55e, 0xf59e0b, 0xef4444, 0x8b5cf6, 0x06b6d4];

Each remote player is rendered as a colored capsule mesh with a canvas-generated nametag sprite. Position updates go out at 20Hz, zombie state sync from host to guests at 10Hz. The host owns the zombie simulation; guests just shoot and their hit events get sent back to host for validation.

Is it going to work great with 200ms latency? No. But for 2-4 players on decent connections, it's actually pretty playable. And it cost literally nothing to host.

The Runner Game

Think Subway Surfers but every gate you hit has a multiple-choice question. Run through the correct lane. Three lanes = three answer options. Wrong lane = health damage. Right lane = XP.

The entire game is a pure functional state reducer. No classes, no mutation. Every frame is (state, action) → { state, events }:

// client/src/games/runner/module/engine/reducer.ts

export const engineReducer = (
  state: EngineState,
  action: EngineAction,
  questions: Question[] = []
): { state: EngineState, events: RunnerEvent[] } => {
  const events: RunnerEvent[] = [];
  let newState: EngineState = {
    ...state,
    player: { ...state.player },
    segments: [...state.segments],
    activeEffects: [...state.activeEffects],
  };

  if (action.type === 'START') {
    const seed = action.seed ?? Math.floor(Math.random() * 1000000);
    newState = getInitialState(seed, difficulty);
    newState.status = 'PLAYING';
    events.push({ type: 'GAME_STARTED', payload: { gameId: 'runner' } });
  }
  // ...
};

The slowdown mechanic is the satisfying part. When a question gate is coming up, the game triggers a slow-motion effect:

// client/src/games/runner/module/engine/constants.ts

export const CONSTANTS = {
  BASE_SPEED: 12,
  MAX_SPEED: 22,
  QUESTION_SLOWMO_MS: 2000,
  QUESTION_SLOWMO_SCALE: 0.05,  // 95% slowdown
  GATE_VISIBLE_DIST: 104,        // you can see it coming from 104 units away
  QUESTION_MIN_Z_GAP: 140,       // questions every 140-245 units
  QUESTION_MAX_Z_GAP: 245,
  WRONG_ANSWER_DAMAGE: 5,
  // Power-ups:
  POWERUP_SPAWN_CHANCE: 0.3,
};

Power-ups drop randomly: magnet (pulls coins), shield (one free wrong answer), score multiplier (2x), jetpack (lifts you over obstacles), and superjump. Each has a duration timer. Multiple power-ups can be active simultaneously.

The map system is also interesting. The runner can either procedurally generate segments, or play hand-authored maps defined in a RunnerMapOverlay format with explicit obstacle placements, spawn points, and pickup spots. Both modes feed into the same segment spawner and reducer.

Tetris

Tetris is the most conceptually elegant implementation of the three games. Each tetromino is labeled with an answer option. Multiple-choice question appears at the top. The correct answer piece has special behavior — when it locks, it triggers a bomb explosion that clears surrounding rows.

Wrong answer pieces pile up normally. The pressure is intrinsic: if you keep answering wrong, your board fills up.

// client/src/games/tetris/module/engine/engine.ts

export function createInitialState(seed: number = Date.now()): GameState {
  let s = seed;
  // 7-bag randomizer for fair piece distribution
  const bag = shuffleBag(['I', 'J', 'L', 'O', 'S', 'T', 'Z'], s);

  return {
    phase: 'idle',
    board: Array.from({ length: 20 }, () => Array(10).fill(null)),
    activePiece: null,
    nextPieces,
    bag,
    score: 0,
    level: 1,
    currentQuestionId: null,
    currentQuestionPrompt: null,
    questionChoices: null,
    selectedChoiceId: null,
    lastAnswerCorrect: null,
    // ...
  };
}

The piece assignment is deterministic. Given a question and choice, the piece shape is always the same (via a string hash), so you get predictable "I = correct answer A" associations over time. This might actually help memory formation — the muscle memory of the piece shape reinforces the answer.

function deterministicPiece(choice, questionId, index): string {
  if (choice.pieceId && TETROMINOES[choice.pieceId]) {
    return choice.pieceId;
  }
  const keys = Object.keys(TETROMINOES);
  return keys[hashString(`${questionId}:${choice.id}:${index}`) % keys.length] ?? 'T';
}

The question cycling is worth mentioning. Questions cycle through in shuffled order, reshuffle when exhausted, and track how many full cycles you've done. So if you have 8 review cards loaded, you'll see all 8 before repeating any — the same shuffled-deck principle as Anki.

The Shared Infrastructure

All three games use the same GameSetup component for card selection, the same GameResultsOverlay for post-game stats, and the same event tracking system:

// client/src/games/events/types.ts — events emitted by all games

type GameEvent =
  | { type: 'GAME_STARTED';    payload: { gameId: string } }
  | { type: 'QUESTION_HIT';    payload: { correct: boolean; cardId: string; xp: number } }
  | { type: 'GAME_OVER';       payload: { score: number; xp: number; timeMs: number } }
  | { type: 'POWERUP_COLLECT'; payload: { type: PowerUpType } }

Game results feed directly back to the SM-2 spaced repetition state. Answer a question correctly in the zombie game → that card's efactor improves, interval extends, due date pushed further out. Answer wrong → interval resets, card comes back sooner. The games aren't separate from the review system; they're another input to it.

There's also Cosmo, the mascot. He has 12 animated states (idle, celebrate, confused, thinking, hint, wave, etc.), and shows up in the game setup screens reacting to what you're doing. GameCosmo.tsx maps game phases to animation states. It's a small touch but it makes the whole experience feel more coherent.

Performance on Mobile

All three games have to run on mobile. That's non-negotiable for a learning app — people do their review sessions on the bus, between classes, anywhere. For the 3D game, this meant a lot of work.

The engine detects low-end devices via navigator APIs:

// client/src/games/hyper/engine/constants.ts

RENDERER: {
  PIXEL_RATIO_MAX: 1.5,          // cap pixel ratio even on high-DPI screens
  LOW_DEVICE_MEMORY_GB: 4,       // 4GB or less = low quality mode
  LOW_DEVICE_THREADS: 4,         // 4 hardware threads or less = low quality mode
},

In low quality mode: shadow maps disabled, LOD culling more aggressive, post-processing (bloom, vignette, chromatic aberration) stripped. The same SCALE constant (0.55) shrinks the entire world proportionally — spawn distances, bullet ranges, arena size — so mobile doesn't have to render as far:

const SCALE = 0.55;

export const ENGINE_CONFIG = {
  CAMERA: { FAR: 800 * SCALE },         // only render 440 units instead of 800
  ZOMBIE: { SPAWN_DISTANCE: 20 * SCALE }, // zombies spawn 11 units away, not 20
  BULLET: { MAX_DISTANCE: 200 * SCALE }, // bullets despawn at 110, not 200
};

World LOD culling happens every frame: props beyond a certain distance get visibility toggled off. The PerfLogger module tracks frame time against a budget and emits warnings when we're dropping below 30fps.

Mobile also gets a completely different control scheme — a virtual joystick for movement (left thumb), virtual look input (right thumb), and on-screen shoot/reload/ability buttons. The MobileManager handles touch events separately from InputManager's keyboard/mouse handling.

What I Learned

Browser 3D is genuinely capable now. When I started this project I wasn't sure if a real-time 3D FPS with procedural worlds was feasible in a browser. It is. Three.js with proper instancing, LOD, and texture atlasing gets you pretty far. The renderer caps at 1.5x pixel ratio and it looks fine.

Pure reducer architecture scales. The runner game's state machine started small and grew to handle 10+ action types, multiple effect systems, and complex collision logic. Because it's a pure function — same input always produces same output — it was trivially testable and easy to reason about. I wish I'd applied the same pattern to the Tetris engine from the start.

Seeded RNG solves a lot of problems. Every game uses deterministic seeded random number generation. This means replays are possible, multiplayer maps are synchronized from a single seed, and bugs are reproducible. I used mulberry32 — a simple 32-bit pseudo-RNG that's fast and gives good distribution.

P2P multiplayer is surprisingly accessible. Trystero abstracts away the WebRTC complexity. You call joinRoom(), you get action/state channels, you broadcast. The hard part isn't the networking — it's deciding who owns what state. In my case, the host owns zombie simulation and guests own their own player positions. Conflict resolution is "host wins." Simple.

The games are better than I expected. I thought the zone-based shooting mechanic would feel clunky in practice. It doesn't. Having a visual mapping between body part → answer letter gives your brain a spatial anchor, and the slow-motion focus system gives you time to actually read and think. I've caught myself remembering "B = Chest = Binary Search time complexity is O(log n)" from a session I played three days ago. That's the whole point.

What's Next

The three games are working. The next thing I want to tackle is a proper leaderboard and session history — right now you see your post-game score but there's no persistent record of "you got this question wrong 4 times in the zombie game." Connecting game-specific mistakes back to the review system more explicitly would close the loop even tighter.

I'm also thinking about adding a fourth game: a Space Invaders variant where columns of alien ships are labeled A-E and you shoot the column matching the correct answer. The codebase already has a skeleton implementation (/play/invaders) but it's not hooked into the shared question pool yet.

If you want to poke around the code yourself, the project is on GitHub. The games lab at /games-lab runs in no-auth mode with static demo questions, so you can see the games without needing an account.

Part 3 will cover the AI tutor, the spaced repetition algorithm, and the lesson generation system — the backend of the learning loop that makes the games worth playing.

Part 1: How I Built an AI-Powered DSA Learning Platform

I Built an AI That Teaches You DSA Through Faded Parsons Problems and Spaced Repetition

Prateek Mohan — Tue, 31 Mar 2026 05:44:11 +0000

By Prateek

So I've been deep in this project for a while now and I keep getting asked "what exactly does it do?" by friends, and I keep giving this rambling five-minute answer that never quite lands. So here's the written version. Maybe this one will stick.

The short version: I built a learning platform called PatternMaster that generates DSA lessons on demand, turns them into flashcards, and then makes you actually recall the material through faded Parsons problems, spaced repetition, and games. It also does visualizations. And it has a zombie shooter. I'll explain all of that.

But first — why?

The Problem With How I Was Learning DSA

I spent a lot of time watching NeetCode videos. Great videos. Genuinely. But I started noticing a pattern: I'd watch the explanation, follow along, understand every step perfectly, and then open a blank editor and... nothing. The information was there but it wasn't mine. I hadn't really built anything in my head — I'd just borrowed his mental model for 20 minutes and then returned it.

Reading editorial solutions was even worse. You read it line by line, you go "oh yes that makes sense, very clever," you close the tab, and three days later you couldn't reconstruct it from scratch.

The research calls this the illusion of knowing. You feel like you learned because understanding someone else's solution is easy. The hard part — and the part that actually builds skill — is construction. Building the solution yourself, from parts, under some form of retrieval pressure.

That's what I wanted to force. Not passive reading. Active construction.

The other piece: spacing. I've used Anki and it genuinely works, but it's boring and tedious to build decks for. I wanted the cards to just appear automatically, seeded from whatever I was studying, and for the scheduling to handle itself.

So I started building. Six months later here we are with something I'm actually proud of.

Section 1: The AI Unit Generation Pipeline

When you open the Learn page and type in a topic — "Two Sum", "Dijkstra's algorithm", "sliding window", whatever — the system needs to figure out what kind of content to generate before it even starts writing prompts.

This is handled by guessTopicType(), a function that is honestly kind of funny to look at. It's a 30+ regex monster that tries to figure out if you typed a LeetCode problem, a generic algorithm topic, a system design question, or — and yes, this is real — a history topic.

export function guessTopicType(topic: string): "leetcode" | "algorithm" | "system_design" | "history" | "general" | "coding" {
  const t = topic.toLowerCase().replace(/[^a-z0-9 ]/g, "");
  if (/\bleetcode\b/.test(t) || /\btwo.?sum\b/.test(t) || /\b3.?sum\b/.test(t)) {
    return "leetcode";
  }
  if (
    /\bsystem.?design\b/.test(t) ||
    /\bdesign\s+(a\s+|the\s+)?(twitter|uber|youtube|...|url\s*shortener|rate\s*limiter)\b/.test(t)
  ) {
    return "system_design";
  }
  if (
    /\b(history|historical|biography|ancient|medieval|renaissance|revolution)\b/.test(t) ||
    /\b(tokugawa|sengoku|napoleon|caesar|cleopatra|genghis)\b/.test(t)
  ) {
    return "history";
  }
  const codingPatterns = /\b(bfs|dfs|dijkstra|sort|search|tree|graph|heap|stack|queue|array|linked.?list|hash|dp|dynamic.programming|greedy|backtrack|recursion|trie|sliding.window|two.pointer)\b/;
  if (codingPatterns.test(t)) return "algorithm";
  // ...
  return "general";
}

The history path is not a joke. The "tokugawa" and "sengoku" entries are real, and yes, you can learn about the Tokugawa shogunate in PatternMaster. The non-coding lesson path generates concept slides, factual flashcards, and even logical ordering puzzles instead of code. It was a happy accident — I built the general path mostly as a fallback and it ended up working surprisingly well.

Once the topic type is known, the system dispatches to the right prompt builder, which fires a single unified AI call asking for everything at once:

Metadata: title, description, tags, difficulty
Lesson slides: 5 slides (concept → concept → analogy → concept → code)
Flashcards: 5-8 Q&A pairs
Main problem: LeetCode-style problem statement with constraints
Code: verified Python solution + test cases
Image prompts: 2 prompts for generating visual thumbnails

One call, one JSON blob, everything you need to render a full unit. It sounds like it'd be unreliable — and yeah, sometimes the JSON comes back slightly mangled, which is why jsonrepair from npm is doing a lot of quiet work behind the scenes. More on that later.

The unit detail view shows the slides, the generated code problem, and the exercises (Parsons). Clicking through the slides is actually kind of fun — the analogies the model comes up with are hit or miss but when they hit, they really help.

Section 2: The 5-Provider AI Broker

One thing I didn't want was to be locked to a single AI provider. Different models have different strengths, different pricing, different rate limits. So I built a broker layer.

The broker (server/ai/broker.ts) routes requests to: Gemini, OpenAI (GPT-4/GPT-5), Claude, Groq, and local Ollama. Each "phase" of the app (unit generation, tutor chat, image generation, review card generation) can be configured to use a different provider.

A few things I'm genuinely proud of in this module:

In-flight dedup. Early on I noticed the network tab showing 5 identical POST requests going out simultaneously when someone opened a page. Classic React useEffect + StrictMode double-firing + impatient users = many duplicate requests. The fix was a simple in-flight Map:

const inFlight = new Map<string, Promise<BrokerResponse>>();

// ...inside handleBrokerComplete:
const dedupKey = dedupeKey(mode, phase, subPhase, promptHash, imageHash);

if (inFlight.has(dedupKey)) {
  console.info(`[broker] Dedup hit for ${dedupKey}`);
  return inFlight.get(dedupKey)!;
}

// ...after building the promise:
inFlight.set(dedupKey, responsePromise);
try {
  const response = await responsePromise;
  return response;
} finally {
  inFlight.delete(dedupKey);
}

Identical concurrent requests with the same prompt hash get collapsed into one actual API call. Everyone waiting on that key gets the same response. This cut API costs by something like 30-40% in testing.

Free tier support. No API key? No problem. The server has a fallback:

const FREE_TIER_MODEL = "gemini-3.1-flash-lite-preview";

export function isFreeTier(aiSettings: AISettings): boolean {
  const hasKey = (k: unknown) => typeof k === "string" && k.trim().length > 0;
  return !(
    hasKey(aiSettings.geminiKey) ||
    hasKey(aiSettings.openaiKey) ||
    hasKey(aiSettings.claudeKey) ||
    hasKey(aiSettings.groqKey)
  );
}

Free tier users get routed to gemini-3.1-flash-lite-preview via the server's key. It's slower and less capable but it works. Building for free tier users genuinely changed the architecture — you have to trim prompts, be careful about token limits, and set different timeout expectations. It's a different class of user and they deserve a working experience, not just an error page.

You can configure your own keys for any provider, set which provider handles which phase, and even point it at a local Ollama instance if you're running Llama locally and don't want any API calls leaving your machine.

Section 3: Faded Parsons Problems

This is the feature I'm most proud of and the one that required the most grinding to get right.

A Parsons problem is a code comprehension exercise where you're given the correct lines of code, scrambled, and have to put them back in the right order. The research backing this is solid — constructing a solution from parts engages retrieval in a way that reading doesn't. Faded Parsons takes it further: some blocks have blanks that you have to fill in. You're not just ordering — you're also recalling specific syntax and logic.

Here's the prompt that asks the AI to generate blocks from verified code:

export function buildParsonsPrompt(verifiedCode: string, topic: string): string {
  return `Split this code into Parsons blocks. Topic: "${topic}". Do NOT change logic.

\`\`\`python
${verifiedCode}
\`\`\`

Return ONLY JSON: {"blocks":[...],"solution_order":["p1","p2",...]}
Block shape: {"id":"p1","text":"code line","indent":0,"isBlank":false,"groupTag":"g1"}
Blank blocks add: "placeholder":"hint","answer":"exact code"

Rules: 4-6 groupTags, 2-3 blank blocks, 1 distractor (isDistractor:true, NOT in solution_order). IDs: p1,p2,... Indent must match original.`;
}

The key constraints: indent must be preserved exactly (Python), there must be a distractor block that isn't part of the solution, and 2-3 blocks must be "faded" with a hint placeholder and the exact answer stored separately for verification.

Once you assemble the blocks in the right order and fill in the blanks, the assembled code gets run in Pyodide — a full CPython interpreter compiled to WebAssembly running in your browser. Zero server calls for code execution. It's genuinely magical. It also has about a 4-second startup cost the first time, which I handle by pre-warming it in the background when the page loads. Worth it.

When the AI Parsons generation fails (and it does, sometimes — the JSON comes back malformed or the block count is off), there's a mechanical fallback that generates blocks deterministically from the code:

function pickMechanicalBlankIndexes(lines: string[]): Set<number> {
  const result = new Set<number>();
  const maxBlanks = lines.length >= 6 ? 3 : lines.length >= 3 ? 2 : 1;
  const blocked = /^\s*(def|class|from|import|@)\b/;

  const collect = (matcher: RegExp) => {
    for (let i = 0; i < lines.length && result.size < maxBlanks; i += 1) {
      if (result.has(i)) continue;
      const line = lines[i];
      if (blocked.test(line)) continue;
      if (matcher.test(line)) result.add(i);
    }
  };

  collect(/^\s*return\b/);
  collect(/^\s*(if|elif|for|while)\b.*:\s*$/);
  collect(/^\s*[a-zA-Z_][a-zA-Z0-9_]*\s*=\s*.+/);
  collect(/\S/);

  return result;
}

The priority order: return statements first (high recall value), then control flow, then assignments, then anything. It sounds simple but getting the indent handling right when you're reconstructing Python code from string manipulation was genuinely annoying. Python cares about indentation in a way most languages don't and the mechanical assembler has to get it exactly right or Pyodide will throw a syntax error.

For non-coding topics, the Parsons problem becomes a logical ordering puzzle of factual statements. "Put these events in chronological order" or "arrange these steps of the Krebs cycle" — same UI, different content.

Section 4: SM-2 Spaced Repetition

The review system uses SM-2 — the algorithm behind Anki — via the supermemo npm package.

Cards live in two phases:

Learn phase: You haven't seen it enough yet. The card keeps showing up until you've reviewed it 10 times. During this phase the SM-2 algorithm isn't really active — the card just cycles back immediately regardless of how you graded it. Think of it as the initial memorization pass.

Review phase: After 10 reviews, the card graduates. Now SM-2 takes over. Your grade affects the ease factor and interval:

import { supermemo, type SuperMemoItem, type SuperMemoGrade } from 'supermemo';

function gradeToSuperMemo(grade: ReviewGrade): SuperMemoGrade {
  if (grade === 'again') return 1;
  if (grade === 'hard') return 2;
  if (grade === 'good') return 4;
  return 5; // easy
}

function applySM2(item: SuperMemoItem, grade: SuperMemoGrade): SuperMemoItem {
  const result = supermemo(item, grade);
  const MAX_INTERVAL = 730;
  return {
    ...result,
    interval: Number.isFinite(result.interval) ? Math.min(result.interval, MAX_INTERVAL) : 1,
    efactor: Number.isFinite(result.efactor) ? Math.max(result.efactor, 1.3) : 2.5,
  };
}

// In learn phase:
if (prev.phase === 'learn') {
  const seenCount = prev.seenCount + 1;
  const hasGraduated = seenCount >= 10;
  return {
    reviewCardState: {
      ...state.reviewCardState,
      [cardId]: {
        ...prev,
        phase: hasGraduated ? 'review' : 'learn',
        seenCount,
        dueAt: hasGraduated ? now + 24 * 60 * 60 * 1000 : now,
        interval: hasGraduated ? 1 : 0,
        repetition: hasGraduated ? 1 : 0,
        lastReviewedAt: now,
      }
    }
  };
}

There's a MAX_INTERVAL = 730 cap — two years. Without it, very easy cards would eventually schedule themselves out 5+ years and you'd never see them again. Which sounds fine until you realize you forgot the thing and the next review is in 2031.

The efactor floor of 1.3 prevents cards from becoming so hard they're practically daily — if something is that difficult, the intervals shrink but they don't collapse to zero.

Cards auto-seed from the flashcards generated in each unit. Complete a unit, get flashcards in your review queue, no manual deck building required. They sync bidirectionally to the server so your progress persists across devices.

The card management view lets you see what's in your queue, which phase cards are in, and manually adjust due dates if something is wildly off.

Section 5: Review Generation at 3 Cognitive Depths

When you ask the AI to generate additional review cards beyond the ones seeded from your units, it uses a prompt that explicitly targets three cognitive levels:

CARD QUALITY RULES:
3) Vary cognitive depth across cards:
   - ~40% recall: "What is X?" / "Define Y"
   - ~30% comprehension: "Why does X work?" / "How does X differ from Y?"
   - ~30% application: "When would you use X?" / "What happens if you apply X to Z?"

This maps roughly to the lower three levels of Bloom's taxonomy — remember, understand, apply. The recall cards are fast and easy. The comprehension cards require you to actually understand the mechanism, not just the label. The application cards are the ones that actually prepare you for interviews, because interviews ask "when would you use a min-heap here?" not "define a min-heap."

It sounds like a small prompt tweak but it genuinely changes the character of a generated deck. Without the constraint, the model defaults to 90% "What is X? / Define Y" cards, which are fine but don't build the depth you need.

Section 6: Remotion Visualizations

The visualize page is probably the most visually impressive part of the project and the one that people ask about most.

The idea: type "explain merge sort" and get an animated video showing merge sort running step by step, with elements moving, colors changing, and labels appearing. No video editor. No manual keyframing. Just AI-generated JSON rendered by a React-based animation engine.

The AI generates a RemotionSceneSpec — a JSON object with:

elements[]: up to 13 different element types: box, circle, label, bar, gear, svg-path, ring, hexagon, triangle, diamond, wave, particle-burst, progress-arc
connections[]: arrows between elements (straight or curved, with optional animated flow)
steps[]: discrete steps that specify exactly what changes — moves, color changes, highlights, scale changes, rotations, elements being added or removed

DynamicComposition.tsx renders this spec as a smooth animation, interpolating positions and colors between steps over 18 transition frames. The interpolation is the piece that makes it feel like a real animation rather than a slideshow.

The gallery has both CS/DSA visualizations (BubbleSort, LinkedList, HashTable, QueueViz, BinarySearch) and "real world" ones like CPUPipeline, DNAReplication, SolarSystem, and TrafficLight. The real world ones were built to test the robustness of the schema — can it handle non-CS domains? Mostly yes.

The storyboard view shows each step as a frame, which is useful for debugging when the AI generates a step that moves elements off-screen or produces an animation that makes no visual sense. Which, in my experience, happens maybe 20% of the time. The other 80% is genuinely impressive.

Section 7: What I Actually Learned Building This

JSON repair is a legitimate engineering problem. The jsonrepair package from npm is doing quiet heroic work throughout this codebase. AI models produce almost valid JSON constantly. Trailing commas, unescaped quotes in string values, truncated responses that cut off mid-array — all of it. jsonrepair handles maybe 70% of these cases silently. The remaining 30% require a retry with a stricter prompt. I have a whole retry + repair pipeline that I initially thought was overkill and now think is the bare minimum.

Pyodide is genuinely magical but demanding. Running CPython in the browser via WebAssembly is one of those things that shouldn't work but does. The startup cost (~4 seconds on first load, ~200ms after that) is real but manageable if you pre-warm. The thing that surprised me is how complete it is — you can import collections, itertools, heapq, basically anything from the standard library, and it just works. Made the code verification story actually viable.

The dedup map was added after watching the network tab. I didn't design it upfront. I saw the problem happening in production (5 identical requests going out in 100ms) and fixed it. The lesson: instrument your network calls early. You will be surprised what you find.

Mechanical Parsons was more work than expected. I thought "just split by newline and pick some to blank out" would take an afternoon. Python indentation meant the assembled code had to have exact whitespace or Pyodide would reject it. Then there's the distractor generation — you can't just copy a line and call it a distractor, it has to be plausible but wrong. Eventually I settled for shallow distractors (a close variant of an existing line) rather than trying to generate genuinely misleading ones.

Non-coding topics work better than I expected. The history and general paths were built as fallbacks. I honestly expected them to produce mediocre content. But the pipeline generalizes better than I thought — the flashcard generation is just as good for "explain the Meiji Restoration" as for "explain BFS." The main difference is no code execution, which actually simplifies things.

Free tier users force you to be honest about your product. When you're building with your own API key, you don't feel the token costs or the latency. The moment you have to serve users on a free tier model with smaller prompts and slower responses, you find out which parts of your product are genuinely valuable and which are just impressive demos. It was humbling in a useful way.

What's Next

The games are next. Review cards aren't just for the review page — they feed into three different games:

Zombie FPS (/play/hyper): You're in a 3D graveyard. Questions appear as floating text. Shoot the zombie whose body zone maps to the correct answer (zones A-E). The physics of urgently trying to recall "which one is O(n log n)" while a zombie runs at you works surprisingly well as a recall forcing function.
Endless Runner (/play/runner): Side-scrolling runner where question gates block your path. Answer correctly to pass through, wrong answer costs health.
Tetris (/play/tetris): Pieces are labeled with algorithm names. Clearing lines requires putting the right pieces in the right spots.

Multiplayer review sessions are coming too — race a friend through your shared flashcard deck, see who answers faster. The infrastructure is there (WebSocket room system is already built), I just need to wire the review UI to it.

More visualization types: I want to add network graphs (for system design), timing diagrams (for concurrency), and memory layout visualizations (stack vs heap). The current schema handles most of these but not all.

If you want to try it, you can run it locally — it's a standard React + Express monorepo, npm run dev and you're up. I'll have a hosted version up soon.

The core loop — AI Tutor → Lessons → Review Cards → Games → Progress — actually works. I've been using it myself to fill in gaps in my DSA knowledge and it's genuinely more effective than watching videos. Which is the whole point.

PatternMaster is open source. Check the repo if you want to dig into any of the pieces above in more detail.

Whisper-Groq-Transcriber: Speech-to-Text with Enhanced Features

Prateek Mohan — Mon, 03 Jun 2024 10:06:58 +0000

Whisper-Groq-Transcriber is an innovative speech-to-text application that combines OpenAI's Whisper model with Groq integration to provide advanced transcription capabilities and enhanced functionality. Developed by Prateek Mohan, this cutting-edge project aims to streamline transcription tasks and boost productivity through features like flexible recording options, dynamic hotkeys, and an intuitive Gradio UI.

Key Features of Whisper-Groq-Transcriber

Utilizes OpenAI's Whisper model for accurate speech-to-text transcription directly from your microphone.

Seamlessly integrates Groq to handle JSON data and respond to queries using Groq's API

Supports various recording modes, including voice activity detection, press-to-toggle, and hold-to-record, providing flexibility to suit different preferences.
Allows customization of hotkeys for specific actions, streamlining your workflow and enhancing productivity.
Provides a user-friendly Gradio UI for easy interaction with the application, including tabs for chatting with the bot, managing hotkeys, adding URLs or PDFs, and updating context.

Main Components Overview
The main components of Whisper-Groq-Transcriber include:

transcription.py: Manages audio recording, transcription using local models or the OpenAI API, and post-processing of transcriptions.
json_handler.py: Handles loading, saving, and updating JSON data, including specialized functions for managing resume content.
status_window.py: Provides a status window using Tkinter to display recording and transcription status.
embedding_utils.py: Handles document loading, processing, chunking, and loading into a vector store.
groq_integration.py: Manages Groq API interactions, JSON data handling, and response generation.
main.py: The entry point of the application, setting up configurations, initializing models, and managing the recording and transcription process.
helpers.py: Provides utility functions for managing hotkeys, handling transcription, and interacting with the Gradio UI.

These components work together seamlessly to deliver a powerful and user-friendly speech-to-text experience with advanced features like Groq integration and dynamic hotkeys.

Screenshots and Videos

Gradio Interface showcases the main interface where users can interact with the application, including tabs for managing hotkeys, adding URLs or PDFs, and updating context.

Hotkey Creation demonstrates the process of setting up custom hotkeys for specific actions within the Gradio UI.

Changing Recording Mode displays the interface for modifying the recording mode, such as voice activity detection, press-to-toggle, or hold-to-record.

Hotkey in Action video illustrates the real-time functionality of a custom hotkey, showcasing its seamless integration with the application.

Recording Output video presents the transcribed text being automatically written to the active window, highlighting the accuracy and efficiency of the transcription process.

Use Cases for Whisper-Groq-Transcriber

Streamline meeting transcriptions, making it easier to keep track of discussions and action items.
Enhance accessibility by providing real-time transcriptions for individuals with hearing impairments during live events, meetings, or online content.
Transcribe lectures, seminars, and webinars, ensuring students and professionals don't miss any important information.
Assist content creators in transcribing their spoken content into text for editing and publishing as articles, blogs, or social media posts.
Improve customer support by transcribing customer calls and chats, enabling analysis and maintaining accurate records.
Facilitate legal and medical transcriptions, such as court proceedings and patient consultations.
Simplify research by transcribing interviews and focus group discussions for easier qualitative data analysis.
Integrate with home automation systems or other software to execute commands based on voice inputs, enhancing productivity and convenience.

LLama3 Groq Voice Assistant

Prateek Mohan — Wed, 01 May 2024 23:07:19 +0000

Leveraging Llama3 and Groq in TalkToLLM: A Journey Through AI-Enhanced Conversations

In the realm of AI and machine learning, the integration of powerful language models and efficient processing units can transform how we interact with technology. My recent project, TalkToLLM, serves as a testament to this transformation, leveraging the capabilities of Llama3 and Groq to enhance conversational experiences. This post is not a tutorial but a narrative of my journey and the pivotal role these technologies played.

Introduction to Llama3 and Groq

Before diving into the project, let's briefly understand the technologies at its core.

Llama3 is a state-of-the-art language model known for its ability to understand and generate human-like text. Its versatility and power make it an ideal choice for a wide range of natural language processing tasks.

Groq is a hardware accelerator designed to speed up machine learning workloads. Its unique architecture allows for rapid processing of complex computations, making it a perfect match for deploying large language models like Llama3.

The Genesis of TalkToLLM

TalkToLLM is a voice-enabled AI conversation manager that aims to create a seamless interactive experience by combining speech recognition, a powerful language model, and text-to-speech capabilities. The project was born out of a desire to make AI conversations more dynamic, intelligent, and accessible.

Integrating Llama3 and Groq

The integration of Llama3 and Groq into TalkToLLM was a pivotal moment in the project. Here's how they contributed:

Speech-to-Text and Text-to-Speech

The first step in creating an interactive AI conversation is understanding the user's voice input and responding audibly. For this, I utilized the speech_recognition library for converting voice to text and pyttsx3 for converting text responses back to speech.

Leveraging Llama3 for Intelligent Responses

The core of TalkToLLM lies in generating intelligent responses to user inputs. This is where Llama3 comes into play. By processing the transcribed text through Llama3, the system can generate responses that are not only relevant but also contextually aware.

Accelerating with Groq

To ensure that the interaction feels instantaneous, it was crucial to minimize response times. This is where Groq's hardware accelerator made a significant impact. By deploying Llama3 on Groq, I was able to achieve rapid processing of language model computations, resulting in a smoother and faster conversational experience.

Conclusion

The journey of creating TalkToLLM was both challenging and rewarding. Integrating Llama3 and Groq proved to be a game-changer, enabling me to push the boundaries of what's possible in AI-enhanced conversations. As technology continues to evolve, I'm excited to explore further and refine TalkToLLM, making AI interactions more natural and engaging.