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

1. Enter your username
2. Pick a region from the country/province/district tree
3. View the 360° street panorama
4. Place your guess on the map
5. Earn points based on accuracy (closer = more points)
6. 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.