vngeoguessr/docs/project-structure.md

Project Structure

Root Directory

• CLAUDE.md - Project instructions and guidelines for Claude Code
• components.json - shadcn/ui configuration
• package.json - Dependencies and scripts
• next.config.mjs - Next.js configuration
• eslint.config.mjs - ESLint configuration
• postcss.config.mjs - PostCSS configuration
• jsconfig.json - JavaScript project configuration
• vitest.config.mjs / vitest.integration.config.mjs - The two vitest lanes
• playwright.config.mjs - The browser smoke-test lane (tests/e2e/)
• docker-compose.yml - Local Redis + SRH for the integration lane
• data-build/ (gitignored) - Local pipeline artifacts awaiting data:seed
• README.md - Public-facing project readme

Source Code (src/)

App Router (src/app/)

Next.js 16 App Router structure:

Pages

• page.js - Homepage: region picker and leaderboard modal
• layout.js - Root layout component
• globals.css - Global styles
• favicon.ico - Site favicon

Game Pages

• game/page.js - Main game interface
• credits/page.js - Data sources, licenses, and open-source credits
• debug/page.js - Debug hub: lists every debug tool as a peer
• debug/layout.js - Shared shell for all debug pages: app bar, DebugNav, theme
• debug/DebugNav.js - Segmented peer navigation shown on every debug page
• debug/bbox/page.js - Bbox visualization and live Mapillary probing
• debug/coverage/page.js - Panorama coverage map, per region
• debug/coverage/CoverageMap.js - Leaflet layer for that page

API Routes (src/app/api/)

• new-game/route.js - Creates new game sessions with Redis storage
• guess/route.js - Processes guess submissions, scores, and fans out
• leaderboard/route.js - Leaderboard data management with Redis
• skip/route.js - Skip current round functionality
• debug/mapillary/route.js - Mapillary API debugging and testing
• debug/pano/route.js - Resolve one panorama id to an image
• debug/region-coverage/route.js - A region's outline and panorama points

React Components (src/app/components/)

• GameClient.js - Main game client component
• LeafletMap.js - Interactive map for guess placement
• PanoramaViewer.js - 360 degree street view display
• RegionPicker.js - Homepage province accordion, one row per playable region
• RegionSelect.js - Level buttons plus a grouped select, used where a single region has to be chosen from 67
• LeaderboardList.js - Ranked rows for one board
• UsernameModal.js - Set or change the leaderboard name; skip generates a random Player-xxxxxx
• FirstRoundHint.js - One-time how-to-play banner on the game screen
• DonateQRModal.js - Donation QR code modal
• ThemeToggle.js - Light/dark switch

Reusable Components (src/components/)

shadcn/ui Components (src/components/ui/)

Only the primitives the app actually renders are vendored in. Add others with the shadcn CLI when a screen needs them, rather than keeping unused ones around.

• accordion.jsx - Collapsible sections (province expansion)
• alert.jsx - Alert notifications
• badge.jsx - Badge components
• button.jsx - Button variants
• card.jsx - Card layouts
• dialog.jsx - Modal dialogs
• input.jsx - Input fields
• label.jsx - Form labels
• select.jsx - Grouped select (region picker)
• skeleton.jsx - Loading skeletons
• tabs.jsx - Tab navigation

Generated Data (src/data/)

Both directories are build output. Do not hand-edit; see Rebuilding the generated region data in development.md.

• regions/index.js - The 67-node tree: code, name, parent, level, children, center, bbox, and coverage flags
• regions/counts.js - Per-region panorama and cell tallies. The one panorama-derived file a client component may import - it carries counts only, never a coordinate
• boundaries/<province>/*.json - Simplified outlines, one file per region, behind a generated boundaries/index.js barrel

The panorama index itself is not in the repo: the pipeline writes artifacts to data-build/panos/ (gitignored) and scripts/seed-pano-db.mjs uploads them to Neon Postgres, which is what the app queries at runtime.

Utility Libraries (src/lib/)

• utils.js - Utility functions including cn() for class name merging
• regions.js - Client-safe region tree traversal. Imports nothing from pano-index.js or pano-db.js; tests/regions.test.js enforces that
• map-tiles.js - Client-safe tile provider choice: Geoapify when NEXT_PUBLIC_GEOAPIFY_KEY is set at build time, OSM public server otherwise
• pano-index.js - Server-side only. Picks a panorama for a region from Postgres and reports which district it landed in
• pano-db.js - Server-side only. Neon HTTP adapter behind pano-index.js
• region-request.js - Resolves and validates a region code from a request
• game.js - Scoring ladders (base + region-scaled), distance, formatting
• username.js - Player name in localStorage, plus the random-name generator
• last-region.js - Last-played region in localStorage (the home page's "Continue in ..." row)
• leaderboard.js - Leaderboard operations, including the district to province to country fan-out
• mapillary.js - Mapillary lookup by image id
• session.js - Redis-based session management with 30-min expiry
• upstash.js - Upstash Redis REST client adapter with multi-tenant key prefix
• theme.js, use-count-up.js - Theme persistence and a count-up hook

Build Scripts (scripts/)

Each carries a header comment with its flags and its cost.

• build-region-boundaries.mjs - OSM/Nominatim to boundaries and the region tree
• build-pano-index.mjs - Mapillary z14 tiles to per-province panorama artifacts
• assign-pano-districts.mjs - Clips and partitions panoramas by district
• seed-pano-db.mjs - Validates the artifacts and uploads them to Neon
• build-check.mjs - Production build into .next-check
• lib/assign-districts.mjs - District assignment shared by the two pano scripts
• lib/pano-schema.mjs - Panorama table DDL shared by the seed and the tests

Tests (tests/)

Vitest, mostly one file per src/lib/ module, plus a route test for new-game, guess, and debug/region-coverage. The skip, leaderboard, debug/mapillary, and debug/pano routes have no dedicated test file; their underlying src/lib/ logic (leaderboard.js, mapillary.js) is still covered. fake-upstash-redis.js, mock-upstash.js, redis-harness.js and wait-for-srh.js are the shared harness that lets the same files run against either the in-memory fake or a real Redis. fake-neon.js, mock-neon.js and pano-fixtures.js are the equivalent for the panorama store: PGlite behind the Neon SDK boundary, loaded with small synthetic rows.

tests/e2e/ holds the Playwright smoke specs (*.spec.js, so vitest never collects them): the homepage picker, the username modal, and one full round, all against browser-level stubs in tests/e2e/helpers.js with a fixture panorama in tests/e2e/fixtures/. Deeper UI behavior (RegionSelect.js, the coverage page, real panoramas) remains manual testing only.

Documentation (/docs/)

• project-overview.md - Project overview, administrative basis, coverage note
• features.md - Detailed game features documentation
• tech-stack.md - Technology stack and dependencies
• development.md - Development guidelines, commands, and build sequence
• game-flow.md - Complete gameplay flow documentation
• project-structure.md - This file - project organization

Planning (/plans/)

• Project planning documents and implementation plans

Public Assets (public/)

• zlp.jpg - Donation QR code image
• Static assets served directly by Next.js