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 test lanes
• docker-compose.yml - Local Redis + SRH for the integration lane
• README.md - Public-facing project readme

Source Code (src/)

App Router (src/app/)

Next.js 15 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
• debug/page.js - Development debugging tools
• 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 - Username input modal
• 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/)

All three 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
• panos/<province>.json - Panorama ids, coordinates, and district assignment, behind a generated panos/index.js barrel. Server-side only - roughly 28MB of exact answers

Utility Libraries (src/lib/)

• utils.js - Utility functions including cn() for class name merging
• regions.js - Client-safe region tree traversal. Imports nothing from data/panos/ or pano-index.js; tests/regions.test.js enforces that
• pano-index.js - Server-side only. Picks a panorama for a region and reports which district it landed in
• region-request.js - Resolves and validates a region code from a request
• game.js - Scoring, distance, formatting, username storage
• 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 a per-province panorama index
• assign-pano-districts.mjs - Clips and partitions panoramas by district
• migrate-leaderboards.mjs - Backfills the two boards whose code changed
• build-check.mjs - Production build into .next-check
• lib/assign-districts.mjs - District assignment shared by the two pano scripts
• lib/leaderboard-migration.mjs - Copy, verify, regression-check and restore

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.

Nothing here exercises the React components: there is no component-test dependency, so GameClient.js, RegionPicker.js, RegionSelect.js and the coverage page are covered by 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