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
deck	text — which location deck the game played
played_at	timestamptz, default now()
detail	jsonb — one entry per round {lat, lon, label, glat, glon, km, pts}, powering the click-through map replay. Null for games recorded before the column existed.
+ 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 a hall of fame: each navigator once, at their personal best, with the deck it was earned on. Round guesses live only in Redis (4 h TTL), so the final write is also the last chance to keep them — ?detail=<id> replays a saved game as one map of every real place and that player's pins.

Host creates a room

1. POST /api/create with mode, rounds (1–10), and round seconds (clamped 10–300).
2. Famous decks (North America / World / South America / USA): 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.

Access control

• A room is a capability: the 4-letter code admits you during the lobby window; a per-player UUID token authorizes every later call.
• The host token is a separate secret — only its holder can start rounds, end them early, or advance the game.
• Session tokens live in per-tab sessionStorage — refresh rejoins, but tabs are independent participants.
• Admin actions (clear / archive the leaderboard) sit behind an ADMIN_TOKEN-gated endpoint; the token compares in constant time (hashed timingSafeEqual).

Cheating & fairness

• All scoring is server-side (haversine + exponential decay); coordinates are validated before scoring.
• State responses omit scores and answers during open questions; random-world rounds send only a pano id, coordinates at reveal.
• The weekly deck is revealed one round per guess — the console can't preview upcoming locations. Designated weeks play Random world instead of famous places: the first player's browser resolves the panoramas and the server stores them first-write-wins for the whole week, sending pano ids only and coordinates at reveal.
• Solo games recorded to the Hall are Random world only: the client resolves and submits the deck (the same trust model as hosting a random room — the submitting browser knows its own deck), and the server validates it, enforces timing and no-rewrites, scores every guess, and writes the row as room_code 'SOLO'. The solo board appears only under the Random world deck filter and scores by average points per counted round, since solo games vary in length (1–10 rounds, best five counted); group games are the default Hall view. Famous-deck solo is casual and never recorded — 50 memorizable places make it a memory test, not a navigation one.
• Round timing is enforced server-side (late guesses score zero, small grace window) and a first guess is final (HSETNX).
• Time spent off the tab mid-round shows as a social 👀 badge — solo reveals and the final table, live-room reveals, weekly boards. Informational, never punitive; values are clamped server-side.

Abuse & input

• Per-IP fixed-window rate limits over Redis on the write endpoints: room create and join, weekly and recorded-solo starts, and admin attempts. Fail-open — a store hiccup never locks players out.
• Names and labels are length-capped and markup-stripped at the API, then HTML-escaped again at render — two independent layers against stored XSS. Duplicate names get numbered.
• E2E test players (E2E-* names) are filtered server-side and never reach a leaderboard.
• Room-code allocation returns 503 if the code space is momentarily exhausted rather than overwriting a live room.

Platform

• Every response carries X-Content-Type-Options: nosniff, X-Frame-Options: DENY, and a strict referrer policy.
• The Maps key is public by design, defended by referrer + API restrictions and a monthly quota cap.
• GitHub Actions is the only path to production, using a dedicated scoped Vercel token — a red test means the deploy never starts.
• Room state expires after 4 hours (Redis TTL); the season archive moves rows in a single atomic statement, so a mid-flight failure can't duplicate or lose them.