vngeoguessr/docs/tech-stack.md

Tech Stack

Frontend Framework

• Next.js 16: React-based full-stack framework with App Router
• React 19.2: Component architecture
• Tailwind CSS 4: Utility-first CSS framework for styling

Street View & Mapping

• Mapillary vector tiles: the z14 image layer is the index source. Read offline by scripts/build-pano-index.mjs with @mapbox/vector-tile + pbf, against a 50,000 requests/day cap
• Mapillary Graph API: one call per round -- lookup by image id, ~230ms. Its /images?bbox= search is deliberately off the game path: it returns HTTP 500 in every dense district, because it counts images inside the box before applying the limit. See the header of src/lib/mapillary.js. api/debug/mapillary/route.js keeps the search as a diagnostic, and will reproduce those 500s
• Leaflet: Interactive mapping library for guess placement
• Map tiles: src/lib/map-tiles.js picks the provider at build time — Geoapify (NEXT_PUBLIC_GEOAPIFY_KEY set; free tier permits commercial use) or the OSM public server as the keyless fallback for dev, e2e, and forks
• OpenStreetMap: Map data (© OpenStreetMap contributors, ODbL); Nominatim supplies the administrative boundaries via scripts/build-region-boundaries.mjs
• @photo-sphere-viewer/core: 360° panorama viewer

Geographic Processing

• @turf/turf: distance, point-in-polygon, union, simplify, and point-to-line distance -- used both at runtime and by the offline builds
• Generated region tree: src/data/regions/ holds the nodes and src/data/boundaries/<province>/ the simplified outlines. The per-province panorama indexes live in Postgres (see below), seeded from local pipeline artifacts in data-build/panos/ (gitignored)
• Client/server split: src/lib/regions.js is the client-safe view and imports nothing from src/lib/pano-index.js or src/lib/pano-db.js. That boundary is enforced by an import-graph walk in tests/regions.test.js -- the panorama rows are exact answers
• Server-side Calculations: All geographic processing on backend

Data Storage & Session Management

• Neon Postgres (HTTP): The panorama index -- 424k rows of id, province, district, lat, lng -- read via @neondatabase/serverless (DATABASE_URL or POSTGRES_URL). One random-draw query per round, count queries cached per process. Seeded by scripts/seed-pano-db.mjs, which stages into panoramas_next, verifies, then renames into place, keeping the previous generation as panoramas_old
• Upstash Redis (REST): Session and leaderboard storage via @upstash/redis SDK (REST client, no sockets)
• Credential Flexibility: Accepts UPSTASH_REDIS_REST_URL+UPSTASH_REDIS_REST_TOKEN (vanilla Upstash) or KV_REST_API_URL+KV_REST_API_TOKEN (Vercel Marketplace aliases)
• Multi-tenant Key Prefix: All physical keys carry KEY_PREFIX (default vngeoguessr:) to safely share Upstash DB with other Vercel projects. Prefix applied centrally in src/lib/upstash.js; callers use logical keys only.
• Key Namespaces: session:{id} (30-min TTL), leaderboard:{scope}, distance:{scope} (no expiry). {scope} is vietnam for the country and city:{regionCode} for every province and district -- the city: segment is kept so existing scores stay addressable
• Sorted Sets: Leaderboard ranking with automatic trimming (top 200)
• UUID v4: Session identifier generation via built-in crypto.randomUUID()
• 30-minute Session Expiry: Automatic TTL-based cleanup

UI Components & Styling

• shadcn/ui: Complete component library with "new-york" style
• Radix UI: Headless component primitives -- dialog, label, slot, tabs, plus accordion (province expansion) and select (region picker)
• Lucide React: Icon library
• class-variance-authority: Component variant management
• tailwind-merge + clsx: Dynamic class name handling

Testing

• Vitest: Test runner for the logic in src/lib/, the API routes, the generated region data, and the leaderboard migration
• In-memory Upstash fake: Default Redis backing store, no service required
• PGlite: In-process Postgres (WASM) mocked in at the @neondatabase/serverless boundary, so the panorama queries run against real Postgres semantics with no service
• SRH + Redis (Docker): Optional lane running the same tests against real Redis
• Playwright: Chromium smoke tests for the UI (tests/e2e/), with every API call and the panorama image stubbed at the browser boundary -- no services, no env vars

Development & Analytics

• ESLint: Code linting with Next.js configuration
• Turbopack: Development server bundler
• @vercel/analytics: User analytics tracking
• @vercel/speed-insights: Performance monitoring

Key Dependencies

• @upstash/redis: REST-based Upstash client; no socket pooling, works in edge compute and serverless
• JavaScript Only: No TypeScript - pure JavaScript implementation
• Individual Parameters: Functions use separate parameters instead of object destructuring
• Note: redis (node-redis) package not used (replaced by Upstash REST SDK)