Aplikasi web interaktif tebak lokasi geografis dari seluruh dunia. Dibangun dengan fokus pada performa dan sinkronisasi real-time menggunakan ekosistem Next.js 15.
- Bermain Solo & Multiplayer: Nikmati tantangan menebak lokasi secara mandiri untuk memecahkan rekor Anda sendiri, atau bersaing secara real-time dengan pemain lain di dalam satu ruang (room).
- AI Multiplayer Bot: Jika tidak ada lawan manusia, Anda dapat menambahkan bot AI canggih ke dalam ruang permainan. Bot ini akan melakukan tebakan secara otomatis berdasarkan analisis visual lokasi (menggunakan integrasi AI Vision).
- Generator Koordinat Dinamis: Mulai permainan dari tingkat kesulitan yang dapat disesuaikan—mulai dari acak secara global, per benua, negara spesifik, hingga ke tingkat presisi wilayah kota.
- Scoring System berbasis Haversine: Perhitungan skor yang presisi menggunakan kurva penyusutan (exponential decay) berdasarkan Formula Haversine. Semakin akurat jarak tebakan dari posisi asli, semakin tinggi poin yang dapat diraih.
- AI-Powered Guide (Opsional): Mendukung integrasi kecerdasan buatan (AI) untuk menyajikan deskripsi atau petunjuk lokasi apabila pemain mengalami kesulitan. Sistem ini fleksibel dan dapat dihubungkan dengan berbagai AI Provider seperti Google (Gemini) maupun OpenAI.
- Global Leaderboard: Sistem kompetisi dengan pencatatan log permainan secara terpusat untuk menentukan jajaran pemain terbaik secara global.
- Validasi Teritorial & Street View Filter: Menggunakan pemeriksaan Geocoder Border Validation serta penyaringan metadata untuk memastikan rute penjelajahan di Street View selalu berada dalam rute eksterior yang valid; mencegah munculnya panorama indoor yang gelap atau malfungsi perbatasan negara.
- Frontend: Next.js 15 (App Router), React, Tailwind CSS, Framer Motion
- Backend & Websocket Subsystem: Node.js, Socket.IO (Arsitektur pesan peristiwa real-time)
- Database: MySQL (Skema relasional dengan optimasi Connection Pooling)
- Autentikasi: JWT (JSON Web Tokens) dengan mekanisme One-way hashing (bcrypt)
- Layanan Pihak Ketiga: Google Maps JavaScript API SDK (Termasuk rendering 360° Street View & kalkulasi rute peta)
| Halaman Autentikasi | Dasbor Permainan |
|---|---|
 |
 |
Panduan bagi pengembang yang berminat untuk meninjau atau menjalankan kode sumber aplikasi ini pada lingkungan lokal:
-
Download & Setup Repository: Unduh kode sumber dari repositori ini ke mesin Anda:
git clone https://github.com/mlintangmz2765/geoguesser.git cd geoguesser -
Database Setup: Siapkan database khusus pada MySQL Anda. Kemudian, impor skema dasar menggunakan berkas SQL yang telah disediakan:
mysql -u nama_pengguna_anda -p nama_database_baru < database/schema.sql -
Environment Configuration (.env): Salin berkas contoh konfigurasi
.env.examplemenjadi.envpada direktori utama:cp .env.example .env
Lengkapi seluruh parameter kredensial dan API Key yang diperlukan:
# Database Creds DB_HOST=127.0.0.1 DB_USER=root DB_PASSWORD=kata_sandi_anda DB_NAME=nama_database_anda # App Secret JWT_SECRET=susun_frasa_rahasia_anda # Google Maps API Key (Required) NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=kunci_api_maps_anda # Socket.io Configuration (Production) # Gunakan domain/IP publik jika dideploy ke VPS NEXT_PUBLIC_SOCKET_URL=http://localhost:3001 # Optional AI Integration AI_PROVIDER=google AI_MODEL=gemini-flash-latest AI_API_KEY=kunci_api_ai_anda
-
Install Dependencies:
npm install
-
Start Development Server: Jalankan perintah berikut untuk mengeksekusi web renderer dan socket server secara bersamaan:
npm run dev:full
Aplikasi dapat diakses melalui browser pada alamat
http://localhost:3000.
Aplikasi ini telah dimodularisasi agar siap untuk dideploy pada Production Environment (seperti Cloud Server atau VPS). Sangat disarankan untuk menggunakan reverse proxy (contoh: Nginx) lengkap dengan sertifikat SSL/HTTPS untuk mengarahkan trafik ke internal port aplikasi (default: 3000).
Metode 1: Menggunakan Node Process Manager (PM2) Opsi stabil untuk menjaga siklus hidup aplikasi Node.js di server:
- Jalankan proses Production Build:
npm run build
- Jalankan aplikasi menggunakan PM2:
pm2 start ecosystem.config.js
Untuk menghindari error Mixed Content saat menggunakan HTTPS, gunakan Nginx sebagai reverse proxy yang menangani SSL untuk kedua port (3000 & 3001):
server {
listen 443 ssl;
server_name domain-anda.com;
# SSL Config (Certbot)
ssl_certificate /path/to/fullchain.pem;
ssl_certificate_key /path/to/privkey.pem;
# Frontend (Next.js)
location / {
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}
# Backend (Socket.io)
location /socket.io/ {
proxy_pass http://localhost:3001;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
proxy_set_header Host $host;
}
}Pastikan variabel .env di server diatur ke domain Anda:
NEXT_PUBLIC_SOCKET_URL=https://domain-anda.com
Metode 2: Menggunakan Docker Compose (Recommended) Menghadirkan isolasi lingkungan yang konsisten untuk menghindari konflik antar dependensi:
- Pastikan file
.envsudah dikonfigurasi untuk lingkungan produksi. - Build dan jalankan kontainer dalam detached mode:
docker-compose up -d --build
Implementasi keamanan pada aplikasi ini mencakup perlindungan terhadap ancaman umum:
- Client Password Hashing: Seluruh kata sandi diproses menggunakan metode one-way salted hash lewat library
bcrypt. - Stateless Authentication: Menggunakan JSON Web Tokens (JWT) dengan masa berlaku (TTL) tertentu untuk menghindari kerentanan pada manajemen sesi tradisional.
- SQL Injection Prevention: Seluruh interaksi database menggunakan parameterized queries untuk mencegah manipulasi data yang tidak sah.
- Server-Side Validation: Logika perhitungan skor, penentuan koordinat, dan validasi tebakan diproses sepenuhnya di sisi peladen (Server-Side Engine) untuk mencegah manipulasi data dari sisi klien.
Dikembangkan secara mandiri oleh @mlintangmz2765.