Architecture

Vercel's git auto-deploy is off. GitHub Actions runs the Vitest suite (with an enforced coverage floor) and the Playwright suite (including a two-browser live room) on every push; main deploys via vercel deploy --prebuilt --prod only when both are green.

Every room key carries a 4-hour Redis TTL, refreshed on writes. There is no cleanup job and no orphaned state — finished or abandoned games simply evaporate.

The Street View key is HTTP-referrer-restricted to the production domain and localhost, limited to the Maps JavaScript API, and served at runtime from GOOGLE_MAPS_KEY via /api/config — rotatable without a rebuild, never committed.

Redis — ephemeral room state

room:CODE	meta JSON: state, mode, rounds, roundIdx, roundStartAt, roundMs, deck, customDeck (random-world panos), hostToken, savedToLb
room:CODE:players	hash playerId → {name, token, score} — per-field writes, no races
room:CODE:g:N	hash playerId → {lat, lon, km, pts, ms} — written once via HSETNX

The SDK serializes JSON itself — values are stored as plain objects (api/_lib/store.js). A file-based store with the same interface stands in locally when Redis env vars are absent.

Neon — durable leaderboard

id	serial PK
room_code	text — 4-letter room
player_name	text
score	int — out of 25,000
rounds	int
played_at	timestamptz, default now()
+ weekly_scores: same shape keyed by ISO week, UNIQUE(week, player_name) — one attempt per name per week

Auto-created with CREATE TABLE IF NOT EXISTS; written exactly once per game, guarded by the savedToLb flag in room meta. /api/leaderboard serves the top 20 by score.

Host creates a room

1. POST /api/create with mode, rounds (1–10), and round seconds (clamped 10–300).
2. Famous decks (World / North America / South America): server samples the chosen pool (shared/decks.js). Random world: the host's browser resolves random panoramas (city-jittered, free metadata lookups) and submits a validated deck; questions carry only the pano id — coordinates appear at reveal.
3. Host screen shows the 4-letter code; players join at the site or via /?join=CODE.

Player guesses

1. Pin click is bounds-checked against the map, then POST /api/guess sends only lat/lon.
2. Server validates token, phase, and clock; scores with haversine; HSETNX blocks double guesses.
3. Points are added to the player's score but hidden from state responses until reveal.

Rounds advance lazily

1. No timers run server-side; every /api/state poll checks the clock.
2. question → reveal fires when all players answered or time (+2 s grace) expired.
3. Concurrent polls racing the transition are benign — both write the same state.

Street View resolution

1. /api/config supplies the referrer-locked Maps key; the Maps script loads once, on demand.
2. Each round asks StreetViewService for the nearest outdoor panorama within 1.5 km.
3. No coverage → the round silently falls back to the embedded photo. Labels, addresses, and dates are hidden.
4. Random world: the resolver jitters around one of 3,057 gazetteer cities and snaps to the nearest pano within 5 km — coverage-biased without any extra data.