How luciferakj/geoguesser works
GeoGuesser is a geography guessing game backed by a Spring Boot REST API and PostgreSQL. The main workflow is: a player requests a location, submits map coordinates as a guess, and receives a distance- and time-based score; the game is saved and player statistics updated. The README also documents authentication, daily and multi-round challenges, leaderboards, player stats, and Mapbox imagery. The checked-in frontend is frontend/app.js; the README describes a JavaFX client, so frontend details and some API wiring remain uncertain beyond its documented HTTP integration.
Main entry points: GameService.java Game orchestration · app.js Game interface · PlayerRepository.java Player repository · LocationService.java Location selection
Components 23
Game client
- Game interface
frontend/app.js
Gameplay
- Game endpoints
backend/src/main/java/com/geoguesser/controller/GameController.java - Game orchestration
backend/src/main/java/com/geoguesser/service/GameService.java - Distance and scoring
backend/src/main/java/com/geoguesser/service/ScoringService.java - Guess result
backend/src/main/java/com/geoguesser/dto/GuessResult.java - Location endpoints
backend/src/main/java/com/geoguesser/controller/LocationController.java - Location selection
backend/src/main/java/com/geoguesser/service/LocationService.java
Accounts and security
- Authentication endpoints
backend/src/main/java/com/geoguesser/controller/AuthController.java - JWT utilities
backend/src/main/java/com/geoguesser/config/JwtUtil.java - JWT request filter
backend/src/main/java/com/geoguesser/config/JwtFilter.java - Security configuration
backend/src/main/java/com/geoguesser/config/SecurityConfig.java
Player records
- Player endpoints
backend/src/main/java/com/geoguesser/controller/PlayerController.java - Player statistics
backend/src/main/java/com/geoguesser/service/PlayerService.java
Persistence and setup
- Location records
backend/src/main/java/com/geoguesser/model/Location.java - Location repository
backend/src/main/java/com/geoguesser/repository/LocationRepository.java - Player repository
backend/src/main/java/com/geoguesser/repository/PlayerRepository.java - Game repository
backend/src/main/java/com/geoguesser/repository/GameRepository.java - Game records
backend/src/main/java/com/geoguesser/model/Game.java - Player records
backend/src/main/java/com/geoguesser/model/Player.java - Location seeder
backend/src/main/java/com/geoguesser/config/DataSeeder.java
Other components
- Player
- Mapbox imagery
- PostgreSQL
Connections 29
- Player → Game interface: plays
README.md - Game interface → Game endpoints: submits guesses
README.md - Game interface → Location endpoints: requests locations
README.md - Game interface → Authentication endpoints: authenticates
README.md - Game interface → Player endpoints: views stats
README.md - Game endpoints → Game orchestration: delegates
backend/src/main/java/com/geoguesser/controller/GameController.java - Game orchestration → Distance and scoring: calculates score
backend/src/main/java/com/geoguesser/service/GameService.java - Game orchestration → Location selection: loads target
backend/src/main/java/com/geoguesser/service/GameService.java - Game orchestration → Player repository: loads player
backend/src/main/java/com/geoguesser/service/GameService.java - Game orchestration → Game repository: saves game
backend/src/main/java/com/geoguesser/service/GameService.java - Game orchestration → Player statistics: updates statistics
backend/src/main/java/com/geoguesser/service/GameService.java - Game orchestration → Guess result: builds result
backend/src/main/java/com/geoguesser/service/GameService.java - Location endpoints → Location selection: delegates
backend/src/main/java/com/geoguesser/controller/LocationController.java - Location selection → Location repository: queries and saves
backend/src/main/java/com/geoguesser/service/LocationService.java - Location repository → Location records: loads locations
backend/src/main/java/com/geoguesser/repository/LocationRepository.java - Location selection → Mapbox imagery: builds image URLs
backend/src/main/java/com/geoguesser/service/LocationService.java - Game interface → Mapbox imagery: loads imagery
README.md - Authentication endpoints → Player repository: checks and saves
backend/src/main/java/com/geoguesser/controller/AuthController.java - Authentication endpoints → JWT utilities: creates token
backend/src/main/java/com/geoguesser/controller/AuthController.java - JWT request filter → JWT utilities: validates token
backend/src/main/java/com/geoguesser/config/JwtFilter.java - Security configuration → JWT request filter: registers filter
backend/src/main/java/com/geoguesser/config/SecurityConfig.java - Player endpoints → Player statistics: delegates
backend/src/main/java/com/geoguesser/controller/PlayerController.java - Player statistics → Player repository: queries and updates
backend/src/main/java/com/geoguesser/service/PlayerService.java - Game repository → Game records: persists games
backend/src/main/java/com/geoguesser/repository/GameRepository.java - Player repository → Player records: persists players
backend/src/main/java/com/geoguesser/repository/PlayerRepository.java - Location repository → PostgreSQL: stores locations
README.md - Game repository → PostgreSQL: stores games
README.md - Player repository → PostgreSQL: stores players
README.md - Location seeder → Location repository: seeds locations
backend/src/main/java/com/geoguesser/config/DataSeeder.java