vngeoguessr/docs/development.md

Development Guidelines

Development Commands

• npm run dev - Start development server with Turbopack
• npm run dev:clean - Same, after clearing the .next build cache
• npm run build - Build the application for production (writes .next)
• npm run build:check - Same build for local verification, into .next-check
• npm start - Start production server
• npm run lint - Run ESLint
• npm test - Run the test suite against the in-memory Redis and Postgres fakes
• npm run test:watch - Re-run tests on change
• npm run test:integration - Run the same suite against a local Redis
• npm run redis:up / npm run redis:down - Start/stop that local Redis
• npm run test:e2e - Playwright browser smoke tests, fully stubbed, no env needed (first time: npx playwright install chromium)

Important Development Guidelines

JavaScript Only

• This project uses JavaScript exclusively
• Never create or suggest TypeScript files (.ts, .tsx)
• All components and utilities should be .js or .jsx files

Function Parameters

• Library functions, scripts and route helpers use individual parameters instead of object destructuring: function(param1, param2), not function({param1, param2})
• React components are the exception: they take one props object and destructure it, which is what every component here does and what React expects

Conventions the code follows

Each of these is enforced by a test or a lint rule where one exists; the rest are the shape the code has and new code should keep.

• Server-only modules say so in their header comment, and the import-graph test in tests/regions.test.js keeps src/lib/regions.js from reaching pano-index.js, pano-db.js or daily.js. Anything that touches exact panorama coordinates is server-only.
• The route decides what is best-effort; the library never swallows. A library function throws on failure. A route wraps the writes it can afford to lose (recent-location history, distance records, statistics) in a small ...OrIgnore / ...OrNone helper with a comment saying why, and lets the load-bearing write (the session, the score) fail loudly.
• Failure kinds are classes, not message prefixes: DryPoolError and UpstreamError in src/lib/errors.js. A route maps them to statuses (404 for a dry pool, 502 for an upstream failure); nothing string-matches an error message. UpstreamError.code tells a fact about the image ('gone') from a fact about the service ('timeout', 'network', 'http', 'auth'); only the former may change which panorama a daily serves.
• Claim before write. A session is consumed with an atomic DEL before any board is written, and the fan-out after it settles per level rather than all-or-nothing, because nothing after the claim can be retried.
• One module per browser-storage concern, all reading through src/lib/storage.js (never throws, keeps a write the browser refuses in memory for the visit, notifies watchers) and rendered through useStoredValue in src/lib/use-stored-value.js. No component seeds state from storage in an effect; the react-hooks/set-state-in-effect rule is an error.
• Callback props reach imperative handlers through useEffectEvent, not refs written during render; the react-hooks/refs rule is an error. The one data ref written in render (CoverageMap.js) carries an inline disable and its reason.
• Logical Redis keys are unprefixed and the adapter in src/lib/upstash.js applies KEY_PREFIX. A new Redis command means a new adapter function and a matching method on tests/fake-upstash-redis.js.
• Three region levels, fixed: country, province, district. Codes are uppercase inside the app and lowercase in URLs (regionSlug); players see regionName(), the accented form.
• URLSearchParams.get is read with ||, not ??: ?region= yields '', which must mean "absent".
• API responses are { success, ... } on success and { success: false, error, reason? } on failure, with a real HTTP status. /api/guess returns gameResult alone; the e2e stubs in tests/e2e/helpers.js must carry every key a route emits, and tests/e2e-stub-contract.test.js checks that they do.

File Modification Policy

• Only modify source code files, documentation (/docs), and plans (/plans)
• Configuration changes (package.json, next.config.mjs, eslint.config.mjs, components.json, etc.) should be highlighted for manual processing
• Environment files and build settings require manual review

Security Best Practices

• Never expose or commit secret keys and sensitive information
• Server-side session management prevents client-side coordinate access (Redis TTL 30 min)
• All geographic calculations must be performed server-side
• Session cleanup after guess submission for security

Environment Variables

Copy .env.example to .env and fill it in; it lists every variable the app reads, with placeholders only. The sections below explain each one.

Redis (required):

• Either UPSTASH_REDIS_REST_URL + UPSTASH_REDIS_REST_TOKEN (vanilla Upstash)
• Or KV_REST_API_URL + KV_REST_API_TOKEN (Vercel Marketplace)
• Optional: KEY_PREFIX (default: vngeoguessr:) for multi-tenant DB sharing

Postgres (required):

• DATABASE_URL (or the POSTGRES_URL alias) - Neon connection string holding the panorama index. Provision Neon from the Vercel Marketplace and pull the vars with vercel env pull, then seed with npm run data:seed

Mapillary (required):

• MAPILLARY_ACCESS_TOKEN - Mapillary API token for image fetching

Debug API (optional):

• DEBUG_ACCESS_KEY - In production the /api/debug/* routes return 404 unless the request carries this value as the x-debug-key header or the vng_debug cookie. Unset, they are closed in production. Production is VERCEL_ENV=production, or NODE_ENV=production where VERCEL_ENV is absent; development, tests and preview deployments are always open

Link previews (optional):

• NEXT_PUBLIC_SITE_URL - Absolute origin for Open Graph URLs. Defaults to Vercel's production URL, then http://localhost:3000

Map tiles (optional):

• NEXT_PUBLIC_GEOAPIFY_KEY - Geoapify API key. When set (at build time), all Leaflet maps serve tiles from Geoapify, whose free tier permits commercial use; unset, they fall back to the OSM public tile server (fine for dev/e2e, not for a commercial deployment). The key is public by design — restrict it to the production domain in the Geoapify dashboard. Provider choice lives in src/lib/map-tiles.js

For local Redis without an Upstash account, see Running Upstash locally below.

Continuous integration

.github/workflows/ci.yml runs npm run lint, npm test and npm run build:check on every push to main or dev and on every pull request. It needs no secrets: compiling the app opens no connection.

.github/workflows/leaderboard-backup.yml runs npm run leaderboard:export every Monday and on demand, encrypts the JSON and keeps it as a workflow artifact for 90 days. It needs the repository secrets KV_REST_API_URL, KV_REST_API_TOKEN (and KEY_PREFIX if the deployment sets one) and BACKUP_PASSPHRASE; until they are set the job fails harmlessly. The artifact is encrypted because the repository is public, any signed-in GitHub user can download an artifact, and the boards list every player name. What the backup covers, how to decrypt it and how to restore it: Leaderboard Backup and Restore.

Testing & Completion

Tests live in tests/ and cover the logic in src/lib/ (scoring and distance, the Upstash key adapter, game sessions, the region tree, the panorama indexes and the leaderboards), the API routes, the district-assignment and env-loading script helpers, and the e2e stubs' agreement with the routes. Run npm test after changing anything under src/lib/ or src/data/.

The suite runs against two backing stores, from one set of test files:

• npm test uses tests/fake-upstash-redis.js, an in-memory stand-in mocked in at the @upstash/redis boundary, and PGlite for Postgres. No service, no Docker; about 25 seconds for the whole suite, most of it PGlite start-up. This is the default.
• npm run test:integration runs the same files against a real Redis. Two of them skip: one asserts a response shape only an older SDK produces, and one fast-forwards half an hour to watch a session expire.

Running both is what keeps the fake honest. A behaviour the fake gets wrong shows up as a green unit run and a red integration run.

The panorama queries run against PGlite -- real Postgres in-process -- mocked in at the @neondatabase/serverless boundary (tests/mock-neon.js), in both lanes; only Neon's own endpoint speaks the production driver's protocol, so there is no separate integration lane for it. Fixture rows come from tests/pano-fixtures.js. The data-quality invariants that used to run in tests/pano-index.test.js against the committed JSON now run inside scripts/seed-pano-db.mjs, which refuses to upload artifacts that violate them (npm run data:seed -- --check runs just that gate).

The UI has a Playwright smoke lane: npm run test:e2e runs tests/e2e/*.spec.js in Chromium against a dev server it starts (or reuses) itself. Every /api/* call and the panorama image are stubbed at the browser boundary (tests/e2e/helpers.js), so it needs no Redis, Neon, Mapillary, or .env. It covers the region picker, the username modal, one full round to the reveal, and the /game/{slug} routing contract (legacy ?region= redirects, unknown-region 404s). Anything beyond those flows (real panoramas, real scoring round-trips) is still manual: inform the user when work is complete. Do NOT start development servers - user handles manual testing themselves.

When the dev server needs restarting

Almost never. Measured against this project:

Change	Behaviour
Components, pages	Fast Refresh, ~200ms
API routes	Hot reloaded, ~1.6s
Server libs under src/lib/	Hot reloaded, ~1.8s
Index data under src/data/	Hot reloaded, ~1.1s
next.config.mjs	Next restarts itself
.env	Reloaded in place

Do not run npm run build while a dev server is running. Both own the same output directory, so the build replaces manifests the dev server is still reading, and it logs a burst of ENOENT: no such file or directory errors for manifest files under that directory. Measured: 110 such errors from one overlapping build, and none when the two do not overlap. They are noise from the collision, not a fault in the code being edited.

Use npm run build:check instead. It builds into .next-check and leaves the dev server alone. The plain build script is unchanged, because that is what the deployment platform runs and it must keep writing the default directory.

If a change genuinely will not take effect, the build cache is usually inconsistent rather than the code being wrong. That happens after a build is killed part-way or a different Next version writes into .next, and it shows up as the dev server serving 500s for everything. npm run dev:clean clears the cache and starts fresh; a plain restart will not fix it.

Running Upstash locally

Upstash itself is cloud-only, but @upstash/redis speaks HTTP REST, so any server exposing that REST surface is indistinguishable to the app. docker-compose.yml runs the proxy Upstash's own docs recommend, SRH (hiett/serverless-redis-http), in front of a real Redis:

npm run redis:up     # redis + SRH on http://localhost:8079
npm run redis:down   # stop and discard the data

npm run test:integration points at it automatically. To use it for npm run dev as well, set in .env:

UPSTASH_REDIS_REST_URL=http://localhost:8079
UPSTASH_REDIS_REST_TOKEN=vngeoguessr-local-token

SRH accepts commands only as a JSON array POSTed to /, which is what the SDK sends; the path form Upstash also supports (GET /set/key/value) returns 404.

Rebuilding the generated region data

src/data/regions/ and src/data/boundaries/ are generated and committed; the panorama index is generated into data-build/panos/ (gitignored) and served from Postgres. Run the scripts in this order -- each reads what the previous one wrote:

npm run data:boundaries    # OSM/Nominatim -> boundaries + region tree
npm run data:panos         # Mapillary z14 tiles -> per-province pano artifacts
npm run data:districts     # clip + partition panos by district; writes counts.js
npm run data:seed          # validate the artifacts and upload them to Neon

Each underlying script's header comment carries its flags and its cost; read it before running. Two things worth knowing up front:

• npm run data:repartition reruns the boundaries step with --regenerate (rebuilds the provinces, the barrel and the tree from what is already on disk) and then the districts step, with no network calls. Use it after hand-editing a boundary.
• npm run data:panos spends Mapillary tile requests against a 50,000/day cap. npm run data:districts spends none -- it only re-partitions indexes that already exist, and refuses to rewrite counts.js on a partial run.
• npm run data:seed spends none either. The full run stages into panoramas_next, verifies, and renames into place, keeping the previous generation as panoramas_old; -- --province=DN reseeds one province in place; -- --check validates the artifacts without touching the database. Deploy the app and the seed in either order: the schema is unchanged, and running processes keep serving their cached counts until they recycle.

Styling Conventions

One design system for every page, including debug pages. It is Tailwind 4 + shadcn tokens, defined in src/app/globals.css (:root and .dark blocks); the theme toggle works only on pages that stay inside it.

• Page background: flex-1 vn-surface on the page root. layout.js wraps every page in a min-h-dvh flex column whose last row is the credit footer, so a page fills the viewport minus that strip rather than claiming the whole viewport itself.
• Surfaces: shadcn Card with bg-card border-border shadow-sm; nested panels bg-muted/50. Never bg-white/10 glassmorphism or raw hex.
• Text: text-foreground for headings, text-muted-foreground for secondary, text-card-foreground inside cards. Never text-white on a themed surface.
• Accent: the brand token family (text-brand, bg-brand-subtle, text-brand-subtle-foreground) -- see RegionPicker.js for the idiom.
• Result semantics: the success / warning / danger token pairs (each with a -foreground) for good/near/far judgements, and rank-gold / rank-silver / rank-bronze for podium tints -- see RoundResultDialog.js and LeaderboardList.js. Each token carries its own light and dark value in globals.css, so call sites never write a dark: variant.
• Borders/dividers: border-border.
• Components: use the vendored src/components/ui/ primitives; add missing ones with the shadcn CLI rather than hand-rolling.
• Icons: Lucide only; no emoji glyphs in interactive chrome.

Layering

One z-index ladder for the app, in globals.css :root, low to high: --z-backdrop (the key art behind every page) · --z-pane-chrome (controls over a map or panorama) · --z-floating (the phone minimap) · --z-appbar (the game action bar) · --z-fab · --z-overlay (dialog scrim) · --z-modal (dialog content) · --z-popover (a select opened inside a dialog). Use z-(--token); never an arbitrary z-[…].

--z-backdrop is the only negative rung: AppBackground is a fixed child of <body>, so it paints over the canvas and under every page. The ground it shows through is .vn-surface, which is translucent for exactly that reason -- keep it that way, and keep panes that must stay legible (cards, the game header, the panorama surround) opaque.

Third-party ladders are contained rather than out-bid: Leaflet (200-1000) and Photo Sphere Viewer (50-9999) each live inside a pane carrying isolate (GuessMapPanel, its inner map wrapper, and the panorama pane in GameClient.js), so their values never reach the root stacking context and the pane's own chrome can sit on --z-pane-chrome.

Two heights other elements measure against are tokens too: --footer-h (the credit strip) and --action-bar-h (the game's submit bar). Offset against those, not against the pixel value they happen to hold.

Fixed-surface layout

The game screen does not scroll, so its vertical budget is the constraint -- about 271px of content on a 667x375 landscape phone. Chrome that floats over the panorama goes in flow where it can (the how-to-play hint rides PanoramaViewer's topBarSlot, beside the Mapillary credit) and is sized against the viewport where it cannot (the collapsed minimap is min(9rem,30vh)). viewport.viewportFit is cover, so the game header and content box pad themselves with env(safe-area-inset-left/right) and the footer strip owns env(safe-area-inset-bottom).

Third-party map chrome is sized for a full map, so each state gets what fits. On the phone guess map, Leaflet's tile credit and zoom buttons are hidden while the minimap is a collapsed thumbnail (behind a cover that swallows clicks, with the credit wrapping to five lines) and return when it expands, where the zoom control is lifted clear of the two-line credit. The permanent tile attribution lives on /credits, which carries all three credits the Geoapify free plan requires.

Inside these surfaces, size with flex or insets -- never a percentage height. Below layout.js's column every ancestor's height comes from flexing against a min-height, which is indefinite, so h-full and h-[45%] silently collapse to content height. Use flex-1 for a share of the space and absolute inset-0 to fill a positioned box.

Raw palette colors are allowed only where the color must not follow the theme: the bg-neutral-900 surround behind panoramas and full-bleed maps (dark in both themes on purpose), and the Leaflet marker hexes in ResultMap.js (MARKER_COLORS), which render outside the CSS token cascade.

shadcn/ui Configuration

• Style: "new-york"
• Path aliases: Configured for @/components, @/lib, etc.
• Components: Use JavaScript (.js) not TypeScript
• CSS variables: Enabled for theming
• Components location: src/components/ui/

Code Style Standards

• Follow existing code patterns in the codebase
• Use established libraries and utilities already present
• Maintain consistent naming conventions
• Write descriptive comments where the reason for the code is not obvious from the code -- this codebase leans on them heavily to record why a measured approach was chosen over the obvious one
• Prefer editing existing files over creating new ones