Split out from the original flat learning.md (moved to learning/archive/). See also
learning/backend/03-modules.md Part 10 for the core Games Module (payment gate, viral share
tokens, score calculation, reward distribution) that this file builds on top of, and
learning/09-devops.md Part 55 for the production out-of-memory incident that this AI generation
service caused. For the frontend consumption of this system (word puzzle audits, the True/False
pivot, anonymous play UX, dead code cleanup), see learning/frontend/07-payments-games.md.
This file covers: OpenRouter as a unified AI model gateway (and why it was added alongside
direct Gemini calls), the full anonymous/guest game-play system (Redis-backed guest sessions,
the join/submit/merge endpoint trio, the guest-to-user merge pattern), the word-puzzle
config-shape serialization bug that silently zeroed every score, and the EventPlan null-guard
bug where a free event’s session could be created without payment being properly gated.
Part 48 — OpenRouter: One API for Every AI Model
What OpenRouter Is
OpenRouter is a routing layer that sits in front of dozens of AI model providers (OpenAI, Anthropic, Google, Mistral, Perplexity, Meta, etc.) and exposes them all through a single, unified API. Instead of managing separate API keys and SDKs for each provider, you have one key and one endpoint.
Your app
│
▼
OpenRouter (https://openrouter.ai/api/v1)
│
├── OpenAI (gpt-4o, o3, o1)
├── Anthropic (claude-3.5-sonnet, claude-3-haiku)
├── Google (gemini-2.5-flash, gemini-2.5-pro)
├── Perplexity (sonar-pro, sonar-reasoning)
├── Meta (llama-3.3-70b, llama-4-scout)
├── Mistral (mistral-large, codestral)
└── ...50+ more
Why Use It Instead of Direct Provider APIs
- One key to manage — single
OPENROUTER_API_KEY, not separate keys for OpenAI + Anthropic + Google - Easy model switching — change one string (
"gpt-4o"→"claude-3.5-sonnet") to compare models or fall back if one is down - Fallbacks and load balancing — OpenRouter can automatically fall back to another model if your primary is rate-limited
- Unified billing — one invoice, one dashboard for all usage across providers
- Cost visibility — see exactly what each model costs per token before you commit
The OpenAI SDK as a Universal AI Client
OpenRouter uses the same request/response format as OpenAI’s Chat Completions API. This means you can use the openai npm package to talk to OpenRouter — just change the baseURL and apiKey:
import OpenAI from 'openai';
// OpenAI directly
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
// OpenRouter — same SDK, different URL + key
const openRouter = new OpenAI({
apiKey: process.env.OPENROUTER_API_KEY,
baseURL: 'https://openrouter.ai/api/v1',
defaultHeaders: {
'HTTP-Referer': 'https://yourapp.com', // identifies your app to OpenRouter
'X-Title': 'Your App Name', // shown in OpenRouter dashboard
},
});
// Calling either one is identical
const response = await openRouter.chat.completions.create({
model: 'anthropic/claude-3.5-sonnet',
messages: [{ role: 'user', content: 'Hello' }],
});This is the OpenAI-compatible API pattern — many providers (Mistral, Together AI, Groq, Ollama for local models) expose the same interface. One SDK, many providers.
Web Search in AI: Online Models
Some AI models can search the web in real time before generating a response. This solves the fundamental LLM problem: training data has a cutoff date. A model trained on data from 2024 doesn’t know about an event that happened last week.
For game generation, web search means:
- “Generate trivia about the FIFA 2026 World Cup” → model can search for actual recent results, correct scores, real players
- “Generate questions about [artist]‘s latest album” → model searches for the actual track list instead of hallucinating
- “Create a word puzzle about Nigerian fintech news” → model pulls current companies and events, not outdated training data
Perplexity Sonar is the primary web-search AI provider. Their models always search the web — it’s not optional. perplexity/sonar-pro is their most capable search-augmented model.
The :online suffix — on OpenRouter, any model can have web search added by appending :online:
google/gemini-2.5-flash ← no web search
google/gemini-2.5-flash:online ← web search enabled
openai/gpt-4o:online ← GPT-4o with web search
OpenRouter handles the search plumbing — the model gets web results injected into its context automatically.
Structured JSON Output on OpenRouter
Gemini enforces JSON via a responseSchema object in its generation config. OpenRouter uses the OpenAI standard:
response_format: { type: 'json_object' }This tells the model to always return valid JSON — no markdown fences, no explanation text, just the JSON object. Not all models honour this (especially smaller open-source ones), but all major commercial models do.
For even stricter control, OpenAI-compatible APIs also support JSON Schema via:
response_format: {
type: 'json_schema',
json_schema: { name: 'game_draft', schema: yourSchemaObject }
}The Model ID Format on OpenRouter
{provider}/{model-name}:{variant}
anthropic/claude-3.5-sonnet
google/gemini-2.5-flash
openai/gpt-4o
perplexity/sonar-pro
meta-llama/llama-3.3-70b-instruct
openai/gpt-4o:online ← with web search
google/gemini-2.5-flash:online ← Gemini with web search
Browse available models and their costs at openrouter.ai/models.
In This Codebase
generateGameDraftViaOpenRouter() is the new method. It uses perplexity/sonar-pro for web-grounded game generation. The generateGameDraft() method (Gemini) is kept as-is. To switch which one the games controller calls, change one method name in the game generation controller.
The HTTP-Referer and X-Title headers are required by OpenRouter — they appear in your usage dashboard and help OpenRouter attribute traffic to your app. If omitted, some models may reject the request.
(See learning/09-devops.md Part 55 for the production OOM incident this same AiGeneratorService caused on a 512MB Render instance, and the per-game-type token-cap fix.)
Part 49 — Anonymous Game Play and the Guest-to-User Merge Pattern
Why anonymous play?
Game rounds are shared via a shareToken link. The link is meant to go viral — shared outside the platform to people who don’t have accounts. If login is required to even see the game, virality dies. Anonymous play lets anyone click the link, play immediately, and be nudged to create an account after they see their score.
This is a conversion funnel pattern: friction-free first experience → hook them with a score → offer account creation to persist the score.
The three anonymous endpoints
All three are @Public() — no JwtAuthGuard required:
// 1. Join a game session — creates/retrieves a Redis guest session
POST /v1/games/anonymous/join/:token
Body: { anonymousId?: string } // send existing ID to resume a session; omit to create new
Response: { anonymousId, sessionId, eventId, eventName }
// 2. Submit answers for a round
POST /v1/games/anonymous/rounds/:roundId/submit
Body: { answers: number[], anonymousId: string }
Response: { score: number, correct: number, total: number }
// 3. Merge all anonymous scores into the now-authenticated user's account
POST /v1/games/anonymous/merge
Body: { anonymousId: string, confirmedEventIds: string[] }
Auth: JwtAuthGuard (this one IS protected — user must be logged in to merge)
Response: { merged: number }(See learning/backend/02-auth.md Part 46 for the @Public() guard pattern these first two endpoints rely on.)
Redis as the anonymous session store
Anonymous game data lives in Redis, not PostgreSQL. The Redis key format:
anon:game:<anonymousId>
The value is a JSON object:
interface AnonymousGameData {
anonymousId: string;
sessions: {
sessionId: string;
eventId: string;
eventName: string;
rounds: {
roundId: string;
answers: number[];
score: number;
}[];
}[];
}Why Redis, not PostgreSQL?
- Anonymous data is temporary. If a guest never creates an account, their data shouldn’t clutter the database. Redis keys can have a TTL (e.g., 7 days) so the data auto-expires.
- Speed. Anonymous game submissions need to respond fast. Redis is in-memory and can handle this without a database write on every answer.
- No schema coupling. The anonymous session doesn’t need to satisfy foreign key constraints (e.g.,
GameEntryrequires a realuserId). Storing in Redis sidesteps this entirely.
(See learning/00-sys-design.md for the general Redis-vs-PostgreSQL decision framework this design follows.)
The anonymous ID — security model
const anonymousId = existingAnonId ?? nanoid(21);The anonymous ID is a random nanoid(21) — 21 characters from a URL-safe alphabet, generating ~10 septillion possible values. It’s:
- Non-guessable — brute-forcing another user’s anonymous session is computationally infeasible
- Not tied to identity — it’s just a random token, not linked to an IP or device fingerprint
The ID is generated by the backend on the first join call, or re-used if the frontend passes back its stored ID. This allows a user to re-open the same game (e.g., browser refresh) and continue from their existing anonymous session.
Stored in: localStorage on the client (nv_anon_game key), Redis on the server.
The join endpoint — finding the session by token
async joinSessionAnonymously(token: string, existingAnonId?: string) {
// Find the session by share token
const session = await this.prisma.gameSession.findUnique({
where: { shareToken: token },
include: { event: true },
});
if (!session) throw new NotFoundException('Session not found');
const anonymousId = existingAnonId ?? nanoid(21);
// Load or create the Redis record for this anonymous user
const existing = await this.redis.get(`anon:game:${anonymousId}`);
const data: AnonymousGameData = existing ? JSON.parse(existing) : {
anonymousId,
sessions: [],
};
// Add this session if not already tracked
if (!data.sessions.some(s => s.sessionId === session.id)) {
data.sessions.push({
sessionId: session.id,
eventId: session.eventId,
eventName: session.event.name,
rounds: [],
});
}
await this.redis.setex(
`anon:game:${anonymousId}`,
60 * 60 * 24 * 7, // 7-day TTL — expires if no account is created
JSON.stringify(data)
);
return { anonymousId, sessionId: session.id, eventId: session.eventId, eventName: session.event.name };
}The shareToken field on GameSession is a @unique scalar — Prisma returns it in all findUnique and findMany results by default (no select needed), which is why it appears on the list endpoint response used by the frontend.
The submit endpoint — scoring without a user row
async submitRoundAnonymously(roundId: string, answers: number[], anonymousId: string) {
const round = await this.prisma.gameRound.findUnique({
where: { id: roundId },
include: { session: true },
});
const score = this.calculateScore(round.session.gameType, round.config, { answers });
// Update the Redis record with the submitted round
const raw = await this.redis.get(`anon:game:${anonymousId}`);
if (!raw) throw new BadRequestException('Anonymous session expired or not found');
const data: AnonymousGameData = JSON.parse(raw);
const sessionRecord = data.sessions.find(s => s.sessionId === round.sessionId);
if (!sessionRecord) throw new BadRequestException('Session not found in anonymous record');
// Idempotency: only record once per round
if (!sessionRecord.rounds.some(r => r.roundId === roundId)) {
sessionRecord.rounds.push({ roundId, answers, score });
}
await this.redis.setex(`anon:game:${anonymousId}`, 60 * 60 * 24 * 7, JSON.stringify(data));
return { score };
}Note the idempotency check (!sessionRecord.rounds.some(r => r.roundId === roundId)). The backend never lets an anonymous player submit the same round twice — same as the @@unique([gameRoundId, userId]) constraint for authenticated players.
The merge endpoint — converting guest scores to real scores
When the user logs in after anonymous play, the frontend calls merge with:
anonymousId— from localStorageconfirmedEventIds— which events’ scores to move (chosen by the user in theAnonymousMergeDialog)
async mergeAnonymousSessions(userId: string, anonymousId: string, confirmedEventIds: string[]) {
const raw = await this.redis.get(`anon:game:${anonymousId}`);
if (!raw) return { merged: 0 };
const data: AnonymousGameData = JSON.parse(raw);
// Filter to only the sessions the user confirmed
const sessionsToMerge = data.sessions.filter(s =>
confirmedEventIds.includes(s.eventId)
);
let merged = 0;
for (const session of sessionsToMerge) {
for (const roundRecord of session.rounds) {
// Skip if user already has a real GameEntry for this round
const exists = await this.prisma.gameEntry.findUnique({
where: { gameRoundId_userId: { gameRoundId: roundRecord.roundId, userId } },
});
if (exists) continue;
// Create the real GameEntry with the anonymous score
await this.prisma.gameEntry.create({
data: {
gameRoundId: roundRecord.roundId,
userId,
answers: roundRecord.answers,
score: roundRecord.score,
completedAt: new Date(),
},
});
merged++;
}
// Also ensure the user has a GameSessionEntry (for the overall leaderboard)
await this.prisma.gameSessionEntry.upsert({
where: { gameSessionId_userId: { gameSessionId: session.sessionId, userId } },
create: { gameSessionId: session.sessionId, userId, totalScore: 0 },
update: {},
});
}
// Recalculate totalScore for each merged session
for (const session of sessionsToMerge) {
await this.recalculateSessionScore(session.sessionId, userId);
}
// The Redis key is NOT deleted here — the frontend deletes localStorage
// and never calls merge again, making the Redis key effectively dead (expires via TTL)
return { merged };
}Why not delete the Redis key after merging?
The frontend is responsible for clearing localStorage after merge (via clearAnonGameData() in the finally block). The Redis key will expire via its 7-day TTL. Deleting it from the backend would require a round-trip for no practical benefit — the key is inaccessible once the frontend has cleared the anonymous ID from localStorage.
The AnonymousMergeDialog — multi-event UX
When a guest played rounds across multiple events (e.g., joined two different friends’ events as a guest), the merge dialog asks which events to keep scores for:
<AnonymousMergeDialog
sessions={pendingSessions} // AnonPendingSession[]
isLoading={isMerging}
onConfirm={(ids) => confirmMerge(ids, () => router.replace(destination))}
onSkip={() => skipMerge(() => router.replace(destination))}
/>The dialog shows event names from pendingSessions. The user picks which events’ scores to merge. Unchecked events are simply not sent in confirmedEventIds — their anonymous scores are abandoned.
When there is only a single event, the dialog is skipped and merge happens silently.
(See learning/frontend/07-payments-games.md Part 51 for the full frontend implementation of this dialog, the PUBLIC_PATHS allowlist that prevents a 401 redirect loop on the public game page, and the stale-closure trap in the submit handler.)
Data lifecycle summary
1. User clicks share link → no localStorage data
2. Anonymous join → anonymousId stored in localStorage + Redis
3. Play rounds → Redis updated per round
4. See score screen → login link shown → user clicks "Log in"
5. Login completes → handlePostAuth runs
6. If single event: merge silently → GameEntry rows created in PostgreSQL
7. If multiple events: show dialog → user picks, then merge
8. Finally block runs → clearAnonGameData() wipes localStorage
9. Redirect to destination → user sees real leaderboard with their score
10. Redis key expires in 7 days → anonymous data gone forever
Pattern: best-effort with finally cleanup
The merge uses a try/catch/finally in useAnonMerge:
try {
await mergeSessions({ anonymousId, confirmedEventIds }).unwrap();
} catch {
// don't block the user if merge fails — they can still use the app
} finally {
clearAnonGameData(); // always clears
setShowDialog(false);
}This is the right pattern for “cleanup that must happen regardless of success or failure.” If the merge API call throws (network down, server error), the user isn’t stuck — they land on the app without their anonymous scores being merged, which is better than being stuck on a loading spinner. The anonymous data in localStorage is also cleared so they don’t see stale merge prompts on future logins.
Part 53 — Game Session Config Structure: The Word Puzzle Serialization Bug
The Config Shape the Backend Expects
GameRound.config is a JSON column. The exact shape the backend reads for each game type is hardcoded in games.service.ts → calculateScore. Get this shape wrong and scoring silently returns 0.
WORD_PUZZLE config — the backend reads questions[0].hiddenWords[]:
{
"questions": [
{
"grid": [["C","A","T",...], ...],
"hiddenWords": [
{ "word": "CAT", "startCell": [0,0], "endCell": [0,2], "direction": "HORIZONTAL" },
{ "word": "DOG", "startCell": [1,0], "endCell": [1,2], "direction": "HORIZONTAL" }
],
"points": 20
}
]
}All hidden words live inside a single questions[0] object. questions.length is always 1 for word puzzle.
What the wizard was doing wrong (the bug):
The wizard had been creating one question entry per hidden word:
{
"questions": [
{ "word": "CAT", "startCell": [0,0], "endCell": [0,2], "direction": "HORIZONTAL", "points": 10 },
{ "word": "DOG", "startCell": [1,0], "endCell": [1,2], "direction": "HORIZONTAL", "points": 10 }
]
}The backend’s calculateScore reads config.questions[0].hiddenWords and finds it undefined — scoring returns 0 every time. The game played, players submitted answers, but all scores were 0. No error was thrown.
The fix (in the wizard’s handleComplete):
if (r.gameType === "word-puzzle") {
const grid = r.questions[0]?.wordPuzzleMeta?.grid ?? [];
const totalPoints = r.questions.reduce((sum, q) => sum + (q.points ?? 10), 0);
const hiddenWords = r.questions
.filter((q) => q.wordPuzzleMeta?.word)
.map((q) => ({
word: q.wordPuzzleMeta!.word,
startCell: q.wordPuzzleMeta!.startCell,
endCell: q.wordPuzzleMeta!.endCell,
direction: q.wordPuzzleMeta!.direction,
}));
return {
...roundBase,
config: { questions: [{ grid, hiddenWords, points: totalPoints }] },
};
}The lesson: when a backend service reads structured JSON from a database column, there is only one valid shape. The code that writes that JSON must produce the exact same shape the reader expects. When they’re in different files (wizard vs games.service.ts), drift is easy to miss and silent to fail.
(See learning/frontend/07-payments-games.md Part 57 for the full frontend serialization step in the wizard’s handleComplete, including why the wizard’s internal per-word Question state needed this translation layer at all.)
THIS_OR_THAT Scoring: Changed from Participation to Correct-Answer
The original calculateScore for THIS_OR_THAT gave points to everyone regardless of answer — it was a participation game. After the pivot to True/False (where there is a definitive correct answer), the scoring changed:
// Old — participation:
case 'THIS_OR_THAT':
totalScore += question.points || 5;
break;
// New — correct answer required:
case 'THIS_OR_THAT':
if (Number(userAnswer) === question.correctAnswerIndex) {
totalScore += question.points || 5;
}
break;userAnswer is a string (submitted by the frontend as the option index). Number() converts it to a number before comparing. correctAnswerIndex is 0 for True, 1 for False. The answer stored in the config is correctAnswerIndex, not the option text.
(See learning/frontend/07-payments-games.md Part 56 for the full frontend side of this True/False pivot, including the wizard UI changes and the AI prompt update.)
Part 54 — EventPlan Null Guard: The paymentRequired Disagreement Bug
How EventPlan is Created
EventPlan has exactly one creator in the entire codebase: activatePayment() in organizer-payments.service.ts. It uses eventPlan.upsert(). It is called:
- When an organizer pays for a plan (Ercaspay webhook fires
activatePayment()) - When a coupon covers 100% of the cost (free payment path —
activatePayment()is called immediately) - As a fallback in
verifyPayment()— if the webhook was missed, the frontend can trigger verification which callsactivatePayment()if the payment reference is confirmed
Free events never get an EventPlan. Creating an event is free. Publishing a free event (no tickets, no games, no VibeTags) costs nothing and bypasses the billing flow entirely. A free event’s EventPlan is always null.
The Bug
createSession had this logic:
// Old — broken:
let paymentRequired = false;
if (plan) {
if (plan.gamesUsed >= plan.gamesIncluded) {
paymentRequired = true;
}
}
// If plan is null → paymentRequired stays false
// The session is created with paymentRequired: falseThen if the organizer tried to activate the session (updateStatus to ACTIVE), the service threw:
400 Bad Request: No active event plan found for this event
The createSession response told the organizer “no payment required” but updateStatus refused to activate. Contradiction. The organizer would see a game in PENDING state that appeared free but couldn’t be activated.
The fix:
const paymentRequired = !plan || plan.gamesUsed >= plan.gamesIncluded;Now a null plan correctly signals paymentRequired: true. The organizer is told upfront they need to purchase a plan. The wizard can show a payment flow before creating the session.
The Mental Model
EventPlan is a gate, not a side effect. Before running any game session, the system must confirm:
- A plan exists (organizer has purchased)
- The plan has remaining quota (
gamesUsed < gamesIncluded)
Both conditions must be true. The old code only checked the second condition when the plan existed, treating “no plan” as “no gate.” The new code treats “no plan” as a failed gate.
(See learning/00-sys-design.md Domain 6 — Billing for the EventPlan model’s role in the schema, and learning/backend/03-modules.md Part 10 for the game session status-lifecycle state machine this gate feeds into.)
Don’t ask an LLM for what code can compute (2026-08-21)
Word puzzle rounds were being saved with empty content:
{"questions": [{"grid": [], "points": 50, "hiddenWords": []}]}Reading the row
points: 50 is the diagnostic detail. The wizard computes the round total as
questions.reduce((sum, q) => sum + (q.points ?? 10), 0), so 50 means five
questions existed at submit time. But hiddenWords is built by
questions.filter((q) => q.wordPuzzleMeta?.word) — and it came out empty, so
none of those five carried word-puzzle metadata.
Worth internalising: a surviving derived value can tell you about inputs that
were themselves discarded. The points total was computed from data that never
got persisted, so it’s the only remaining evidence of how many questions there
were. When debugging missing data, look at what was calculated from it.
The words were unrecoverable because the word-puzzle submit branch writes only
wordPuzzleMeta and drops each question’s text/correctAnswer. Nothing to
restore — only regenerate.
The root cause: the prompt asked for the wrong thing
The generator asked the model to return:
"grid": a perfectly symmetrical 10x10 2D array … The hidden words MUST
actually appear in the grid at the specified positions
"hiddenWords": …"startCell":[rowIndex, colIndex],"endCell"…
That’s a constraint-satisfaction problem with exact self-reported
coordinates — close to a worst case for an LLM. It has to place words without
collisions, keep the grid rectangular, fill the remainder, and then report
indices that agree with what it wrote. validateDraft correctly rejected
malformed output and threw, and the organizer proceeded with an empty round.
Meanwhile the frontend already contained a working placement algorithm.
The fix was to move the boundary. Ask the model only for what it’s genuinely
good at — choosing words and writing clues — and do the placement in code:
// prompt now: { words: [{ word, clue }], points }
// then, server-side:
const { grid, hiddenWords } = buildWordGrid(q.words);This is a general division of labour worth applying beyond this feature:
| Give the model | Keep in code |
|---|---|
| open-ended generation, judgement, phrasing | arithmetic, indices, coordinates |
| ”which words suit this topic" | "do these words fit without colliding” |
| natural language | anything with a verifiable correct answer |
Secondary wins: the prompt no longer spends ~1000 tokens illustrating a 10×10
grid, so maxTokens dropped from 8000 to 4000, and generation stopped being the
most failure-prone game type.
Properties the placement code has that a prompt cannot
src/modules/games/word-grid.ts:
- It cannot produce a wrong answer. A word is placed by writing its letters,
and the coordinates are recorded as it writes them. There’s no separate
“report where you put it” step to get wrong. - Longest-word-first. Long words are hardest to place and are placed while
the grid is still empty. Greedy algorithms on packing problems generally want
the awkward items first. - It fails loudly.
tryBuildreturnsnullif any single word won’t fit,
and the caller retries at a larger size before throwing. It never returns a
grid missing a word it claims is hidden — which is exactly the invariant the
old version couldn’t guarantee. - Seeded RNG (
mulberry32). Same seed, same grid. A puzzle that generated
badly can be reproduced exactly, and tests don’t flake.
Verified by reading each word back out of the finished grid along its own
recorded coordinates — the check that would have caught the original bug:
let read = '';
for (let i = 0; i < hw.word.length; i++) read += grid[r1 + dr * i][c1 + dc * i];
if (read !== hw.word) { /* placement disagrees with its own coordinates */ }Validate at the write boundary, not at read time
assertRoundConfigPlayable now rejects a WORD_PUZZLE round with an empty grid
or no hidden words, and is called from all four paths that write a round
config (createSession, createGameFromAi, addRound, updateRound).
Finding every write path matters more than the check itself — a validator wired
into three of four entry points is a validator that eventually gets bypassed.
Note the updateRound guard is conditional on dto.config !== undefined, so a
title-only edit isn’t blocked by a puzzle that was already broken.
The general shape: reject bad data where it enters, not where it’s displayed.
The frontend fallbacks that rebuild a grid from surviving word coordinates are
worth having, but they’re mitigation. The reason bad rows existed at all is that
nothing said no at write time.
Part N — The word puzzle scored 0 no matter how you played (2026-08-22)
Diagnose before you touch the code
The symptom was “scores aren’t recorded, I always get 0”, and the obvious
suspect was calculateScore. It was the wrong suspect, and the only reason we
didn’t spend an hour rewriting correct code is that we looked at real data
first.
git log -L is the tool for “when did this function last change”:
git log --oneline -L 628,690:src/modules/games/games.service.ts-L start,end:file follows a range of lines through history, tracking it
across edits that move it around. It reported that the scoring function hadn’t
changed since the FEEDBACK commit — so whatever broke, this wasn’t it.
Read the evidence the system already recorded
submitRound stores what the client sent:
metadata: { ...(dto.metadata ?? {}), answers: dto.answers ?? [] }That turns “it doesn’t work” into an answerable question. A read-only script
joining GameEntry to its round printed, per submission, the stored hidden
words next to the submitted answers:
hiddenWords[] : ["CONNECTION","DIGITAL","INNOVATION","NIGERIA","FINTECH",...]
answers[] : ["","DIGITAL","","NIGERIA","FINTECH","",""] score=60 ✅
answers[] : ["","","","","","",""] score=0 ❌
The scorer was right. When words arrived it scored them (3 × 20 = 60). The
failing submissions contained nothing — the player found no words at all.
The lesson: a bug report tells you where someone noticed the problem, not
where it is. Store enough of the input to reconstruct a failure and you can
diagnose from data instead of guessing.
The actual defect: an unstated positional contract
// before
userAnswers.forEach((answer: string, i: number) => {
const expected = hiddenWords[i]?.word?.toUpperCase();
if (answer && expected && answer.toUpperCase() === expected) { ... }
});This compares answers[i] to hiddenWords[i]. That silently demands the client
send one slot per hidden word, in the stored order, with blanks for misses —
["", "DIGITAL", "", "NIGERIA"]. The web player happens to build exactly that:
const answers = hiddenWords.map((hw) => (foundWords.has(hw.word) ? hw.word : ""));No other client would guess it. A mobile client sending the obvious thing —
["DIGITAL","NIGERIA"], just the words it found — scores DIGITAL against
hiddenWords[0] (CONNECTION), misses, and returns 0 on a correct submission.
The fix is to stop making array position load-bearing:
const expected = new Set(hiddenWords.map((hw) => normaliseWord(hw?.word)).filter(Boolean));
const credited = new Set<string>();
for (const answer of userAnswers) {
const word = normaliseWord(answer);
if (word && expected.has(word)) credited.add(word); // a Set, so duplicates credit once
}
return credited.size * pointsPerWord;Both shapes now score identically, and order stops mattering.
The general principle: when two systems have to agree, prefer a contract that
can’t be violated by accident. “Send me the words you found” is impossible to
get subtly wrong. “Send me a parallel array in my internal storage order” is
impossible to get right without reading my source.
Why the second Set matters
credited is a Set, not a counter. With a counter, a client that resends its
whole found-list — or just retries — banks the same word repeatedly. Any time
you score user-submitted input, ask what happens when the same valid item
appears twice.
The silent zero in the arithmetic
const pointsPerWord = Math.max(1, Math.floor(totalPoints / hiddenWords.length));Without Math.max(1, …), a puzzle whose author set 5 total points across 8
words gives floor(5/8) = 0 per word: play perfectly, score 0, and nothing in
the data explains why. Integer division that can round to zero is worth a guard
whenever zero means “silently broken” rather than “legitimately none”.
Sharing the normaliser instead of re-typing it
The grid builder stores words through normaliseWord (uppercase, strip
non-letters), so CHIN-CHIN is stored as CHINCHIN. The scorer has to apply
exactly that transform to the player’s answer or the comparison fails on
punctuation. Rather than write .toUpperCase() twice and let the two drift, the
transform was exported from word-grid.ts and imported by the scorer:
export function normaliseWord(word: unknown): string {
return String(word ?? '').toUpperCase().replace(/[^A-Z]/g, '');
}When two places must apply the same rule, share the function, not the rule.
Which AI failures to retry (2026-10-08)
The question: a game generation can fail six ways. For each, retry or not, and if
so, the same request or with feedback?
My answers, as I gave them
| Failure | My answer | |
|---|---|---|
| a | OpenRouter timeout / 502 | Retry, max 3, then tell the organizer the AI provider is down |
| b | 429 too many requests | We wait |
| c | 401 bad API key | Can’t try again |
| d | Reply isn’t valid JSON | Retry |
| e | Valid JSON, “round 2 has no questions” | Regenerate only round 2 |
| f | Word won’t fit the grid | Maybe regenerate just the word |
Sharpened
The sorting rule underneath all six: will trying again plausibly give a different
result?
- Their problem, temporary (a, b): retry the same request, waiting longer
each time (1s, 2s, 4s — called backoff). Cap by total time, not only by
count: the organizer is staring at a spinner, and three retries of a 20-second call
is over a minute. For 429, read theRetry-Afterheader — if the wait is short,
wait; if long, fail fast with a clear message. - Our problem, permanent (c): never retry — the fourth attempt fails exactly
like the first. Log it loudly (it’s a config bug we must fix) and show the
organizer a generic “something went wrong on our side”, not “your key is invalid”. - The model’s mistake (d, e, f): retry with feedback — send the error back
(“Round 2 had no questions”) so the next attempt isn’t the same dice roll.
Two upgrades on my e/f answers:
- Prevent before you retry. Some rules can go in the structured-output schema
so the model can’t break them: “at least 1 question per round” (minItems),
“word at most MAX_SIZE letters” (maxLength). Cheaper than any retry. - Regenerate one round is the right instinct, but it’s feature 4 (regenerate one
question). It needs a prompt that keeps the new round consistent with the others.
First version: retry the whole draft with the error fed back; targeted regen later.
word-grid.ts already retries placement itself (25 random attempts per size, growing
the grid) — so when it still throws, the words are the problem, not bad luck.
That’s a model-mistake failure: feed it back (“use fewer or shorter words”).
Making AI generation solid — the questions and their answers (2026-10-08)
I handed this one over (“just do the work”), so these are written as questions to
quiz myself on. Cover the answer, try it, then check.
Files: backend/src/modules/games/ai-draft.schema.ts, ai-draft.quality.ts,
ai-generator.service.ts, shared/redis/redis.service.ts; frontend
game-creation-wizard.tsx, ai-generation-progress.tsx.
Q1. The reply shape has to be described to the AI and checked afterwards. How do you write it only once?
Answer: describe it once in a schema library (zod), then derive both uses from
it. z.toJSONSchema(schema) produces the JSON Schema sent as response_format;
schema.safeParse(reply) validates the answer. Add a field in one place and both
move together. Before, the shape lived in three places (a JSON example in the
prompt, a bullet list in the prompt, a hand-written validateDraft) — three
things to keep in sync means they eventually won’t be.
The name for this is single source of truth: every fact lives in exactly one
place, and everything else is computed from it.
The wrinkle: providers’ strict modes reject some JSON Schema keywords
(Anthropic: maxLength, minimum, pattern, minItems > 1…). Deleting them
would lose the rules. relaxForProvider() moves them into the field’s
description instead: the model still reads “at least 4 items”, and zod still
enforces it. That’s the same trick Anthropic’s own SDK uses.
Q2. What does structured output fix, and what doesn’t it?
Fixes: “the reply isn’t JSON” and “a field is missing or the wrong type”. The
model is constrained while it writes, so we stop cutting {...} out of prose.
Doesn’t fix: well-formed nonsense. Duplicate questions, a clue that contains
its own answer, a correct option twice as long as the others. A schema checks
each value on its own; these rules compare values with each other. That’s what
ai-draft.quality.ts is for.
Q3. Which failures get retried, and how? (my answers are in the section above)
The rule: will trying again give a different result?
| Failure | Who handles it | How |
|---|---|---|
| Timeout, 5xx, connection error | the OpenAI SDK (maxRetries: 2) | same request, exponential backoff |
| 429 | the SDK | waits for Retry-After, then retries |
| 401 / 402 / 403 / 400 | nobody — never retried | logged at error level; organizer sees a generic message |
| bad JSON / schema / quality / grid won’t fit | our loop (runWithRetries) | send the reply back with the problems listed |
Fact worth knowing: the OpenAI SDK already retries connection errors, 408, 409,
429 and 5xx with backoff by default. Writing our own retry for those would have
doubled it. Our loop only handles bad content, which the SDK can’t judge.
Q4. Why is the retry limit a time budget and not just “3 attempts”?
Because the organizer is staring at a spinner, and the browser gives up at 60s
(timeout: 60000 in endpoints/games.ts). Three attempts of 20s each is
already over that. So: DEADLINE_MS = 50_000 for everything, and a retry only
starts if at least MIN_ATTEMPT_MS remains. Stopping at 50s means the organizer
gets a real error message instead of a browser timeout.
AbortSignal.timeout(remaining) bounds the whole call including the SDK’s own
retries. The SDK’s timeout option alone applies per retry and could overshoot.
Q5. Quality problems: when do we fix it ourselves vs send it back to the model?
Fix ourselves when the fix is mechanical and can’t make things worse:
shuffling options (models put the right answer in slot A far more than 25% of the
time; shuffling makes the position random by construction), trimming extra
questions, uppercasing cow → COW.
Send back when only rewriting fixes it: duplicates, a clue that spells out the
word, every true/false answer being “true”.
Every problem the model can’t make is one fewer retry. That’s why
THIS_OR_THAT now asks the model for isTrue: boolean and the server builds
options: ["True","False"], and why the model writes a flat questions list that
the server wraps into rounds[0].
Q6. Why the one-at-a-time lock, on top of a daily limit?
The daily limit caps the bill. The lock stops a double-click, or a client
retrying after its own timeout, from paying for the same game twice in
parallel. Different problems, so both are needed.
How the lock works: SET key token NX EX 70. NX means “only if it doesn’t
exist”, so whoever sets it holds the lock. The 70s expiry frees it even if the
server crashes mid-generation. Releasing it uses a tiny Lua script that deletes
the key only if it still holds our token. A plain DEL could delete a lock
someone else took after ours expired.
Why the counter uses Lua too: INCR then EXPIRE as two calls has a gap. If
the process dies between them, the counter never expires and that organizer is
rate-limited forever. Lua runs both inside Redis as one atomic step.
The name for “check and act as one step that nothing can interrupt” is
atomicity. The same idea as getdel in the same file.
Q7. Whose fault is a failure, and does it cost the organizer a daily slot?
Provider outage, provider busy, our bad key → refunded (redis.decr). The
organizer did nothing wrong. “The model couldn’t produce a valid game after 3
tries” → counted, because it cost us real money. Rephrasing the topic is the
organizer’s lever.
Q8. Why does the ai_generations cost table have no foreign key to User or Event?
Same reason as Log: deleting an account or an event must not erase what we
spent. It’s a ledger of our costs, and costs don’t un-happen. (This will matter
for the delete-account feature: these rows survive it by design.)
Q9. Why did regenerating one word-puzzle word need a whole new grid?
A word’s startCell/endCell only mean anything inside the grid it was placed
in. The old regenerate asked for a fresh puzzle, took its first word with its
cells, and dropped it into a round whose saved grid came from a different
question. The coordinates pointed at letters that spelled something else, so
players could never find the word. The fix sends the remaining words as
keepWords, builds one new grid holding all of them plus the new word, and
updates every question’s grid and cells.
The general lesson: coordinates are relative to something. Moving data between
two coordinate systems without converting it is a classic silent bug.
Q10. The progress messages are timed, not real. Is that OK?
The backend answers in one response, so there’s no real progress signal without
streaming (SSE). The stages roughly match what the server does, and the elapsed
counter is the honest part: it shows the request is still alive. Real progress
is parked in the backlog. It’s only worth building if the timed stages turn out
to mislead people.
Keeping game answers secret (2026-10-08)
I wasn’t sure about either question below at first. These are the explanations
that made it click.
Q1. Why doesn’t hashing the answer protect a trivia question?
A hash can’t be reversed, but you don’t need to reverse it. A cheater can see
the four options, hashes all four, and sees which one matches the hash the
server sent. Four tries, microseconds. Hashing only protects something when
there are too many possible values to try (a password). Four options, or
True/False, are never protected this way.
Q2. Why must the server treat the first answer as final?
Without it, a player sends “Lyon” → wrong, “Nice” → wrong, “Paris” → right, and
scores on every question while knowing nothing. Recording the first answer
before replying (Redis HSETNX: “set only if not set”, atomic, so two taps at
once can’t both win) turns the check into a real commitment.
And submit must score from those recorded answers, not the submitted list.
Otherwise: answer wrong, get shown the right option, submit the right one.
The rule underneath both
Whatever reaches the player’s device, they can read; any check the device
does, they can skip. The answer, and the decision about whether a tap is
right, have to live on the server.
The word-puzzle twist
The word list is shown to players on purpose (a word bank), so the secret is
where the words are, not what they are. The bigger hole was submit: scoring
“every word in the list I sent” meant sending the word bank back scored full
marks. Now only finds the server confirmed (a drag whose start and end cells
match a word) count.
What’s still open, and why it’s accepted
A second identity (a throwaway guest id) can answer first to learn the right
option. The only full fix is revealing correctness after the round ends, which
kills the instant flash. Knowing which gaps you’ve chosen to leave open, and
writing them down, is part of the job.
Software engineering
Infrastructure & security
Computer science
Hardware & engineering