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, 9 provinces, 75 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.