# luciferakj/geoguesser architecture

> Architecture diagram of the GitHub repository luciferakj/geoguesser, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/luciferakj/geoguesser
- Repository: https://github.com/luciferakj/geoguesser

## Overview

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: [`backend/src/main/java/com/geoguesser/service/GameService.java`](https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/service/GameService.java) (Game orchestration), [`frontend/app.js`](https://github.com/luciferakj/geoguesser/blob/main/frontend/app.js) (Game interface), [`backend/src/main/java/com/geoguesser/repository/PlayerRepository.java`](https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/repository/PlayerRepository.java) (Player repository), [`backend/src/main/java/com/geoguesser/service/LocationService.java`](https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/service/LocationService.java) (Location selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Game client"]
  node_client["Game interface<br/>[app.js]"]
end

subgraph group_play["Gameplay"]
  node_game_api["Game endpoints"]
  node_game_service["Game orchestration<br/>[GameService.java]"]
  node_scoring["Distance and scoring"]
  node_guess_result["Guess result<br/>[GuessResult.java]"]
  node_location_api["Location endpoints"]
  node_location_service["Location selection"]
end

subgraph group_accounts["Accounts and security"]
  node_auth_api["Authentication endpoints"]
  node_jwt["JWT utilities<br/>[JwtUtil.java]"]
  node_jwt_filter["JWT request filter<br/>[JwtFilter.java]"]
  node_security["Security configuration"]
end

subgraph group_players["Player records"]
  node_player_api["Player endpoints"]
  node_player_service["Player statistics<br/>[PlayerService.java]"]
end

subgraph group_platform["Persistence and setup"]
  node_location_data[("Location records<br/>[Location.java]")]
  node_location_repo["Location repository"]
  node_player_repo["Player repository"]
  node_game_repo["Game repository"]
  node_game_data[("Game records<br/>[Game.java]")]
  node_player_data[("Player records<br/>[Player.java]")]
  node_seeder["Location seeder<br/>[DataSeeder.java]"]
end

node_player(("Player"))
node_mapbox["Mapbox imagery"]
node_postgres[("PostgreSQL")]

node_player -->|"plays"| node_client
node_client -.->|"submits guesses"| node_game_api
node_client -.->|"requests locations"| node_location_api
node_client -.->|"authenticates"| node_auth_api
node_client -.->|"views stats"| node_player_api
node_game_api -->|"delegates"| node_game_service
node_game_service -->|"calculates score"| node_scoring
node_game_service -->|"loads target"| node_location_service
node_game_service -->|"loads player"| node_player_repo
node_game_service -->|"saves game"| node_game_repo
node_game_service -->|"updates statistics"| node_player_service
node_game_service -->|"builds result"| node_guess_result
node_location_api -->|"delegates"| node_location_service
node_location_service -->|"queries and saves"| node_location_repo
node_location_repo -->|"loads locations"| node_location_data
node_location_service -->|"builds image URLs"| node_mapbox
node_client -.->|"loads imagery"| node_mapbox
node_auth_api -->|"checks and saves"| node_player_repo
node_auth_api -->|"creates token"| node_jwt
node_jwt_filter -->|"validates token"| node_jwt
node_security -->|"registers filter"| node_jwt_filter
node_player_api -->|"delegates"| node_player_service
node_player_service -->|"queries and updates"| node_player_repo
node_game_repo -->|"persists games"| node_game_data
node_player_repo -->|"persists players"| node_player_data
node_location_repo -.->|"stores locations"| node_postgres
node_game_repo -.->|"stores games"| node_postgres
node_player_repo -.->|"stores players"| node_postgres
node_seeder -->|"seeds locations"| node_location_repo

click node_client "https://github.com/luciferakj/geoguesser/blob/main/frontend/app.js"
click node_game_api "https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/controller/GameController.java"
click node_game_service "https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/service/GameService.java"
click node_scoring "https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/service/ScoringService.java"
click node_guess_result "https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/dto/GuessResult.java"
click node_location_api "https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/controller/LocationController.java"
click node_location_service "https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/service/LocationService.java"
click node_location_data "https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/model/Location.java"
click node_location_repo "https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/repository/LocationRepository.java"
click node_auth_api "https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/controller/AuthController.java"
click node_jwt "https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/config/JwtUtil.java"
click node_jwt_filter "https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/config/JwtFilter.java"
click node_security "https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/config/SecurityConfig.java"
click node_player_api "https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/controller/PlayerController.java"
click node_player_service "https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/service/PlayerService.java"
click node_player_repo "https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/repository/PlayerRepository.java"
click node_game_repo "https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/repository/GameRepository.java"
click node_game_data "https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/model/Game.java"
click node_player_data "https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/model/Player.java"
click node_seeder "https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/config/DataSeeder.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client toneBlue
class node_game_api,node_game_service,node_scoring,node_guess_result,node_location_api,node_location_service,node_postgres toneAmber
class node_auth_api,node_jwt,node_jwt_filter,node_security toneMint
class node_player_api,node_player_service toneRose
class node_location_data,node_location_repo,node_player_repo,node_game_repo,node_game_data,node_player_data,node_seeder,node_player,node_mapbox toneIndigo
```

## Components

### Game client

- [Game interface](https://github.com/luciferakj/geoguesser/blob/main/frontend/app.js): `frontend/app.js`

### Gameplay

- [Game endpoints](https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/controller/GameController.java): `backend/src/main/java/com/geoguesser/controller/GameController.java`
- [Game orchestration](https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/service/GameService.java): `backend/src/main/java/com/geoguesser/service/GameService.java`
- [Distance and scoring](https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/service/ScoringService.java): `backend/src/main/java/com/geoguesser/service/ScoringService.java`
- [Guess result](https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/dto/GuessResult.java): `backend/src/main/java/com/geoguesser/dto/GuessResult.java`
- [Location endpoints](https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/controller/LocationController.java): `backend/src/main/java/com/geoguesser/controller/LocationController.java`
- [Location selection](https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/service/LocationService.java): `backend/src/main/java/com/geoguesser/service/LocationService.java`

### Accounts and security

- [Authentication endpoints](https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/controller/AuthController.java): `backend/src/main/java/com/geoguesser/controller/AuthController.java`
- [JWT utilities](https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/config/JwtUtil.java): `backend/src/main/java/com/geoguesser/config/JwtUtil.java`
- [JWT request filter](https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/config/JwtFilter.java): `backend/src/main/java/com/geoguesser/config/JwtFilter.java`
- [Security configuration](https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/config/SecurityConfig.java): `backend/src/main/java/com/geoguesser/config/SecurityConfig.java`

### Player records

- [Player endpoints](https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/controller/PlayerController.java): `backend/src/main/java/com/geoguesser/controller/PlayerController.java`
- [Player statistics](https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/service/PlayerService.java): `backend/src/main/java/com/geoguesser/service/PlayerService.java`

### Persistence and setup

- [Location records](https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/model/Location.java): `backend/src/main/java/com/geoguesser/model/Location.java`
- [Location repository](https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/repository/LocationRepository.java): `backend/src/main/java/com/geoguesser/repository/LocationRepository.java`
- [Player repository](https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/repository/PlayerRepository.java): `backend/src/main/java/com/geoguesser/repository/PlayerRepository.java`
- [Game repository](https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/repository/GameRepository.java): `backend/src/main/java/com/geoguesser/repository/GameRepository.java`
- [Game records](https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/model/Game.java): `backend/src/main/java/com/geoguesser/model/Game.java`
- [Player records](https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/model/Player.java): `backend/src/main/java/com/geoguesser/model/Player.java`
- [Location seeder](https://github.com/luciferakj/geoguesser/blob/main/backend/src/main/java/com/geoguesser/config/DataSeeder.java): `backend/src/main/java/com/geoguesser/config/DataSeeder.java`

### Other components

- **Player**
- **Mapbox imagery**
- **PostgreSQL**

## Connections

- Player → Game interface: plays (evidence: `README.md`)
- Game interface → Game endpoints: submits guesses (evidence: `README.md`)
- Game interface → Location endpoints: requests locations (evidence: `README.md`)
- Game interface → Authentication endpoints: authenticates (evidence: `README.md`)
- Game interface → Player endpoints: views stats (evidence: `README.md`)
- Game endpoints → Game orchestration: delegates (evidence: `backend/src/main/java/com/geoguesser/controller/GameController.java`)
- Game orchestration → Distance and scoring: calculates score (evidence: `backend/src/main/java/com/geoguesser/service/GameService.java`)
- Game orchestration → Location selection: loads target (evidence: `backend/src/main/java/com/geoguesser/service/GameService.java`)
- Game orchestration → Player repository: loads player (evidence: `backend/src/main/java/com/geoguesser/service/GameService.java`)
- Game orchestration → Game repository: saves game (evidence: `backend/src/main/java/com/geoguesser/service/GameService.java`)
- Game orchestration → Player statistics: updates statistics (evidence: `backend/src/main/java/com/geoguesser/service/GameService.java`)
- Game orchestration → Guess result: builds result (evidence: `backend/src/main/java/com/geoguesser/service/GameService.java`)
- Location endpoints → Location selection: delegates (evidence: `backend/src/main/java/com/geoguesser/controller/LocationController.java`)
- Location selection → Location repository: queries and saves (evidence: `backend/src/main/java/com/geoguesser/service/LocationService.java`)
- Location repository → Location records: loads locations (evidence: `backend/src/main/java/com/geoguesser/repository/LocationRepository.java`)
- Location selection → Mapbox imagery: builds image URLs (evidence: `backend/src/main/java/com/geoguesser/service/LocationService.java`)
- Game interface → Mapbox imagery: loads imagery (evidence: `README.md`)
- Authentication endpoints → Player repository: checks and saves (evidence: `backend/src/main/java/com/geoguesser/controller/AuthController.java`)
- Authentication endpoints → JWT utilities: creates token (evidence: `backend/src/main/java/com/geoguesser/controller/AuthController.java`)
- JWT request filter → JWT utilities: validates token (evidence: `backend/src/main/java/com/geoguesser/config/JwtFilter.java`)
- Security configuration → JWT request filter: registers filter (evidence: `backend/src/main/java/com/geoguesser/config/SecurityConfig.java`)
- Player endpoints → Player statistics: delegates (evidence: `backend/src/main/java/com/geoguesser/controller/PlayerController.java`)
- Player statistics → Player repository: queries and updates (evidence: `backend/src/main/java/com/geoguesser/service/PlayerService.java`)
- Game repository → Game records: persists games (evidence: `backend/src/main/java/com/geoguesser/repository/GameRepository.java`)
- Player repository → Player records: persists players (evidence: `backend/src/main/java/com/geoguesser/repository/PlayerRepository.java`)
- Location repository → PostgreSQL: stores locations (evidence: `README.md`)
- Game repository → PostgreSQL: stores games (evidence: `README.md`)
- Player repository → PostgreSQL: stores players (evidence: `README.md`)
- Location seeder → Location repository: seeds locations (evidence: `backend/src/main/java/com/geoguesser/config/DataSeeder.java`)
