mirror of
https://github.com/tiennm99/vngeoguessr.git
synced 2026-10-11 12:29:01 +00:00
tiennm99
6d7cb30e5e
There was no app-wide not-found route, so any unmatched path got Next's stock page: unstyled text over the full-bleed background, no footer, and no link back -- its own full-height wrapper pushes the footer off screen. Both 404s now share NotFoundPanel, since they say the same three things and only the wording differs: what is missing, why it probably happened, and the one way out. One action each, deliberately -- a "try again" on a deterministically invalid URL is a button guaranteed to reproduce the same page. The region 404 is a client component for one reason: a thrown notFound() is served from Next's error shell, which carries none of the root layout's pre-paint theme script, so a dark-theme visitor got a white page permanently. Re-applying on mount costs a brief light flash on a rare page and fixes the palette. The app-wide route needs none of this -- an unmatched path prerenders inside the root layout, where the script runs. Both are covered by e2e now, including the theme, since neither failure mode is visible from a status code. Also records the Windows ISR case-collision finding in the debugger's agent memory: a local next start case-folds cache keys on NTFS, so redirect and dynamicParams behaviour cannot be verified from a local production build. The region route no longer redirects, so nothing trips it today, but the verification guidance outlives this change.
VNGeoGuessr
A GeoGuessr clone focused on Vietnamese locations with accurate boundary detection and anti-cheat security. Play geolocation guessing games across a region tree covering the whole country using real street-level imagery.
🎮 Features
- Region Tree: Whole country, 5 provinces, 61 districts — including Da Lat (Lam Dong) and Duc Hoa (Long An)
- 360° Street View: Mapillary panoramic images with PhotoSphere viewer
- Anti-Cheat Security: Server-side session management prevents cheating
- Distance-Based Scoring: 0-5 point system based on accuracy
- Persistent Leaderboards: Redis-powered top 200 player rankings
- Accurate Boundaries: Nominatim API + Turf.js for precise city detection
📚 Documentation
For detailed information about this project, see the documentation in /docs/:
- Project Overview - Project summary and key characteristics
- Features - Complete feature list and game mechanics
- Tech Stack - Technology stack and dependencies
- Development Guidelines - Development setup and coding standards
- Game Flow - Complete gameplay flow documentation
- Project Structure - Codebase organization and architecture
🚀 Getting Started
Prerequisites
- Node.js 24+
- npm 11+
- Redis server (sessions and leaderboards)
- Postgres database (panorama index; Neon in production)
Development
# Install dependencies
npm install
# Start development server
npm run dev
# Build for production
npm run build
# Start production server
npm start
# Run linting
npm run lint
Open http://localhost:3000 to play the game.
🏗️ Built With
- Frontend: Next.js 16 + React 19 + Tailwind CSS 4
- Street View: Mapillary API + PhotoSphere Viewer
- Maps: Leaflet + OpenStreetMap
- Geographic Data: Nominatim API + Turf.js
- Storage: Neon Postgres (panorama index) + Upstash Redis (leaderboards and game sessions)
- UI Components: shadcn/ui
🎯 How to Play
- Enter your username
- Pick a region from the country/province/district tree
- View the 360° street panorama
- Place your guess on the map
- Earn points based on accuracy (closer = more points)
- Compete for the top 200 leaderboard spots!
📋 Development Notes
- JavaScript Only: No TypeScript files
- Individual Parameters: Functions use separate parameters, not object destructuring
- Server-Side Security: Game coordinates never sent to client
- Session Management: Automatic cleanup after 30 minutes
🤝 Contributing
This project follows specific development guidelines. Please read the Development Guidelines before contributing.