How the product is built and run — one Expo app that plays party games on a single phone or online through the cloud. (A third mode, over a host's phone with no internet, is built and paused for launch.) Start with the big picture, dip into a deep-dive, or check the record of why things are the way they are.
The 5-minute map of the whole product — three play modes, one set of rules, and how the pieces fit. Written for a human, not a compiler.
PrinciplesThe handful of principles the architecture is measured against. When a change conflicts with one, that's the signal to stop and rethink.
TasteHis calls on design, copy, layout and game rules, with the real examples. Read it before proposing anything; add to it when a new call is made.
The repo layout, the conventions that keep every game isolated, and what's off-limits when you're adding one.
FrontendOne Expo codebase → iPhone, Android, and web. Boards draw the game; shells plug that into a mode without changing a line.
Online backendThe generic rooms + engine backend that runs the rules server-side for online play, with zero game-specific code.
Live channelThe small relay beside the game that lets guessers watch a line being drawn. How a phone gets in, what it costs, and how to use it in a new feature.
LAN mode · pausedThe host's phone becomes the game server; friends join from their browser over shared wifi or the host's hotspot. Built and tested, but not offered at launch.
Come-back noteThe two iPhone limits that stopped it, what "hidden" means (one flag), and the checklist for switching it back on.
Come-back noteA finished game taken off the shelf because it needs a bigger table. What one id in one list turns off, and the checklist for putting it back.
A game is a self-contained folder, two registration lines and its catalog entry. Scaffold it, wire it, test it, ship it — nothing else in the codebase changes.
GeneratedThe whole product read aloud on one page — every sentence, grouped by screen and by
game. Generated from the copy files; rebuild it with bun run copy:doc.
Every ship flow start to finish — the site on Cloudflare, the Convex backend, iOS, Android and these docs — and which one you're actually touching.
RunbookSwitching the Apple button on: the Services ID, the key, the signed client secret, and the two values Convex needs. Karim's account, Karim's machine.
Every real fork in the road — the call, the rejected alternative, and what would make us change our minds. Newest first.
LearningsBugs that surprised us — the symptom, the root cause, and the most valuable line of all: why it escaped.
Review · temporaryDesign problems found by questioning whether things are built right at all — what was fixed, and which of the product questions left for you are still open.
Audit · temporaryThe pre-launch audit: what was found, what was fixed, and the handful of items still open. Delete this page once they're closed.
doc.css) and render in any browser.
Historical: first Android release (superseded by the
Releasing runbook). The agent-rules card (CLAUDE.md) stays in the repo as Markdown.