# antnygamer/roadconquest-beta architecture

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

- Interactive diagram: https://gitdiagram.com/antnygamer/roadconquest-beta
- Repository: https://github.com/antnygamer/roadconquest-beta

## Overview

Road Conquest is an Android exploration game that records drives, matches them to roads, reveals a fog-covered map, and awards progression for roads and places. The main workflow runs from location tracking through local history and map rendering; foreground place resolution and achievement scoring extend it. Optional accounts and a separate backend support leaderboard visibility and verified competition. The graph follows the README and SOURCE INDEX references; unsampled subsystems are included where documented, but uncertain implementation links are omitted.

Main entry points: [`app/src/main/java/com/roadconquest/app/TrackingService.kt`](https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/TrackingService.kt) (Tracking service), [`app/src/main/java/com/roadconquest/app/MainActivity.kt`](https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/MainActivity.kt) (Map screen), [`server/src/application.mjs`](https://github.com/antnygamer/roadconquest-beta/blob/main/server/src/application.mjs) (Account service), [`app/src/main/java/com/roadconquest/app/data/TrackingRepository.kt`](https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/data/TrackingRepository.kt) (Tracking repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_android["Android app"]
  node_main["Map screen<br/>[MainActivity.kt]"]
  node_settings["Settings"]
end

subgraph group_exploration["Driving and exploration"]
  node_tracker["Tracking service<br/>[TrackingService.kt]"]
  node_location["Location providers"]
  node_matcher["OSRM matching<br/>[OsrmMatcher.kt]"]
  node_history["Tracking repository"]
  node_database[("Local database<br/>[AppDatabase.kt]")]
  node_roadgroups["Road grouping<br/>[RoadGrouping.kt]"]
  node_map["Map renderer<br/>[MapRenderer.kt]"]
  node_fog["Fog rendering"]
end

subgraph group_progression["Progression and exports"]
  node_progression["Progression manager"]
  node_progressrepo["Progression repository"]
  node_achievements["Achievements<br/>[Achievements.kt]"]
  node_shop["Garage and shop<br/>[ShopActivity.kt]"]
  node_export["Data export<br/>[DataExporter.kt]"]
end

subgraph group_accounts["Accounts and competition"]
  node_accountui["Account screens<br/>[AccountActivity.kt]"]
  node_accountclient["Account client<br/>[AccountClient.kt]"]
  node_accountstore["Account store<br/>[AccountStore.kt]"]
  node_leaderboard["Leaderboard screen"]
  node_service["Account service<br/>[application.mjs]"]
  node_security["Auth security<br/>[security.mjs]"]
  node_competition["Competition service<br/>[competition.mjs]"]
  node_integrity["Drive integrity<br/>[integrity.mjs]"]
  node_scoring["Competitive scoring<br/>[scoring.mjs]"]
  node_postgres[("PostgreSQL")]
end

node_driver(("Driver"))
node_osrm{{"OSRM matcher"}}
node_geocoder{{"Android geocoder"}}

node_driver -->|"opens"| node_main
node_main -->|"starts"| node_tracker
node_tracker -->|"requests fixes"| node_location
node_tracker -->|"records drives"| node_history
node_history -->|"persists history"| node_database
node_tracker -->|"matches pending"| node_matcher
node_matcher -.->|"requests matches"| node_osrm
node_matcher -->|"groups roads"| node_roadgroups
node_main -->|"renders map"| node_map
node_map -->|"renders fog"| node_fog
node_main -->|"loads exploration"| node_history
node_tracker -->|"records candidates"| node_progressrepo
node_progressrepo -->|"stores progression"| node_database
node_progression -.->|"resolves places"| node_geocoder
node_progression -->|"updates awards"| node_progressrepo
node_progression -->|"checks milestones"| node_achievements
node_shop -->|"buys cosmetics"| node_progressrepo
node_settings -->|"exports history"| node_export
node_export -->|"reads driving data"| node_history
node_driver -->|"configures app"| node_settings
node_accountui -->|"sends account requests"| node_accountclient
node_accountui -->|"stores session"| node_accountstore
node_accountclient -->|"calls HTTPS API"| node_service
node_leaderboard -.->|"requests rankings"| node_accountclient
node_service -->|"checks credentials"| node_security
node_service -->|"creates competition"| node_competition
node_service -->|"queries database"| node_postgres
node_competition -->|"verifies drives"| node_integrity
node_competition -->|"scores results"| node_scoring
node_integrity -->|"validates scoring"| node_scoring

click node_main "https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/MainActivity.kt"
click node_settings "https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/SettingsActivity.kt"
click node_tracker "https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/TrackingService.kt"
click node_location "https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/util/LocationProviders.kt"
click node_matcher "https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/matching/OsrmMatcher.kt"
click node_history "https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/data/TrackingRepository.kt"
click node_database "https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/data/AppDatabase.kt"
click node_roadgroups "https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/data/RoadGrouping.kt"
click node_map "https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/map/MapRenderer.kt"
click node_fog "https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/map/FogBitmapRenderer.kt"
click node_progression "https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/progression/ProgressionManager.kt"
click node_progressrepo "https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/data/ProgressionRepository.kt"
click node_achievements "https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/achievements/Achievements.kt"
click node_shop "https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/ShopActivity.kt"
click node_export "https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/export/DataExporter.kt"
click node_accountui "https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/AccountActivity.kt"
click node_accountclient "https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/account/AccountClient.kt"
click node_accountstore "https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/account/AccountStore.kt"
click node_leaderboard "https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/LeaderboardActivity.kt"
click node_service "https://github.com/antnygamer/roadconquest-beta/blob/main/server/src/application.mjs"
click node_security "https://github.com/antnygamer/roadconquest-beta/blob/main/server/src/security.mjs"
click node_competition "https://github.com/antnygamer/roadconquest-beta/blob/main/server/src/competition.mjs"
click node_integrity "https://github.com/antnygamer/roadconquest-beta/blob/main/server/src/integrity.mjs"
click node_scoring "https://github.com/antnygamer/roadconquest-beta/blob/main/server/src/scoring.mjs"

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_main,node_settings toneBlue
class node_tracker,node_location,node_matcher,node_history,node_database,node_roadgroups,node_map,node_fog toneAmber
class node_progression,node_progressrepo,node_achievements,node_shop,node_export toneMint
class node_accountui,node_accountclient,node_accountstore,node_leaderboard,node_service,node_security,node_competition,node_integrity,node_scoring,node_postgres toneRose
class node_driver,node_osrm,node_geocoder toneIndigo
```

## Components

### Android app

- [Map screen](https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/MainActivity.kt): `app/src/main/java/com/roadconquest/app/MainActivity.kt`
- [Settings](https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/SettingsActivity.kt): `app/src/main/java/com/roadconquest/app/SettingsActivity.kt`

### Driving and exploration

- [Tracking service](https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/TrackingService.kt): `app/src/main/java/com/roadconquest/app/TrackingService.kt`
- [Location providers](https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/util/LocationProviders.kt): `app/src/main/java/com/roadconquest/app/util/LocationProviders.kt`
- [OSRM matching](https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/matching/OsrmMatcher.kt): `app/src/main/java/com/roadconquest/app/matching/OsrmMatcher.kt`
- [Tracking repository](https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/data/TrackingRepository.kt): `app/src/main/java/com/roadconquest/app/data/TrackingRepository.kt`
- [Local database](https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/data/AppDatabase.kt): `app/src/main/java/com/roadconquest/app/data/AppDatabase.kt`
- [Road grouping](https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/data/RoadGrouping.kt): `app/src/main/java/com/roadconquest/app/data/RoadGrouping.kt`
- [Map renderer](https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/map/MapRenderer.kt): `app/src/main/java/com/roadconquest/app/map/MapRenderer.kt`
- [Fog rendering](https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/map/FogBitmapRenderer.kt): `app/src/main/java/com/roadconquest/app/map/FogBitmapRenderer.kt`

### Progression and exports

- [Progression manager](https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/progression/ProgressionManager.kt): `app/src/main/java/com/roadconquest/app/progression/ProgressionManager.kt`
- [Progression repository](https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/data/ProgressionRepository.kt): `app/src/main/java/com/roadconquest/app/data/ProgressionRepository.kt`
- [Achievements](https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/achievements/Achievements.kt): `app/src/main/java/com/roadconquest/app/achievements/Achievements.kt`
- [Garage and shop](https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/ShopActivity.kt): `app/src/main/java/com/roadconquest/app/ShopActivity.kt`
- [Data export](https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/export/DataExporter.kt): `app/src/main/java/com/roadconquest/app/export/DataExporter.kt`

### Accounts and competition

- [Account screens](https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/AccountActivity.kt): `app/src/main/java/com/roadconquest/app/AccountActivity.kt`
- [Account client](https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/account/AccountClient.kt): `app/src/main/java/com/roadconquest/app/account/AccountClient.kt`
- [Account store](https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/account/AccountStore.kt): `app/src/main/java/com/roadconquest/app/account/AccountStore.kt`
- [Leaderboard screen](https://github.com/antnygamer/roadconquest-beta/blob/main/app/src/main/java/com/roadconquest/app/LeaderboardActivity.kt): `app/src/main/java/com/roadconquest/app/LeaderboardActivity.kt`
- [Account service](https://github.com/antnygamer/roadconquest-beta/blob/main/server/src/application.mjs): `server/src/application.mjs`
- [Auth security](https://github.com/antnygamer/roadconquest-beta/blob/main/server/src/security.mjs): `server/src/security.mjs`
- [Competition service](https://github.com/antnygamer/roadconquest-beta/blob/main/server/src/competition.mjs): `server/src/competition.mjs`
- [Drive integrity](https://github.com/antnygamer/roadconquest-beta/blob/main/server/src/integrity.mjs): `server/src/integrity.mjs`
- [Competitive scoring](https://github.com/antnygamer/roadconquest-beta/blob/main/server/src/scoring.mjs): `server/src/scoring.mjs`
- **PostgreSQL**

### Other components

- **Driver**
- **OSRM matcher**
- **Android geocoder**

## Connections

- Driver → Map screen: opens
- Map screen → Tracking service: starts (evidence: `app/src/main/java/com/roadconquest/app/MainActivity.kt`)
- Tracking service → Location providers: requests fixes (evidence: `app/src/main/java/com/roadconquest/app/TrackingService.kt`)
- Tracking service → Tracking repository: records drives (evidence: `app/src/main/java/com/roadconquest/app/TrackingService.kt`)
- Tracking repository → Local database: persists history (evidence: `app/src/main/java/com/roadconquest/app/data/TrackingRepository.kt`)
- Tracking service → OSRM matching: matches pending (evidence: `app/src/main/java/com/roadconquest/app/TrackingService.kt`)
- OSRM matching → OSRM matcher: requests matches
- OSRM matching → Road grouping: groups roads (evidence: `app/src/main/java/com/roadconquest/app/matching/OsrmMatcher.kt`)
- Map screen → Map renderer: renders map (evidence: `app/src/main/java/com/roadconquest/app/MainActivity.kt`)
- Map renderer → Fog rendering: renders fog (evidence: `app/src/main/java/com/roadconquest/app/map/MapRenderer.kt`)
- Map screen → Tracking repository: loads exploration (evidence: `app/src/main/java/com/roadconquest/app/MainActivity.kt`)
- Tracking service → Progression repository: records candidates (evidence: `app/src/main/java/com/roadconquest/app/TrackingService.kt`)
- Progression repository → Local database: stores progression (evidence: `app/src/main/java/com/roadconquest/app/data/ProgressionRepository.kt`)
- Progression manager → Android geocoder: resolves places
- Progression manager → Progression repository: updates awards (evidence: `app/src/main/java/com/roadconquest/app/progression/ProgressionManager.kt`)
- Progression manager → Achievements: checks milestones (evidence: `app/src/main/java/com/roadconquest/app/progression/ProgressionManager.kt`)
- Garage and shop → Progression repository: buys cosmetics (evidence: `app/src/main/java/com/roadconquest/app/ShopActivity.kt`)
- Settings → Data export: exports history (evidence: `app/src/main/java/com/roadconquest/app/SettingsActivity.kt`)
- Data export → Tracking repository: reads driving data (evidence: `app/src/main/java/com/roadconquest/app/export/DataExporter.kt`)
- Driver → Settings: configures app
- Account screens → Account client: sends account requests (evidence: `app/src/main/java/com/roadconquest/app/AccountActivity.kt`)
- Account screens → Account store: stores session (evidence: `app/src/main/java/com/roadconquest/app/AccountActivity.kt`)
- Account client → Account service: calls HTTPS API
- Leaderboard screen → Account client: requests rankings
- Account service → Auth security: checks credentials (evidence: `server/src/application.mjs`)
- Account service → Competition service: creates competition (evidence: `server/src/application.mjs`)
- Account service → PostgreSQL: queries database (evidence: `server/src/application.mjs`)
- Competition service → Drive integrity: verifies drives (evidence: `server/src/competition.mjs`)
- Competition service → Competitive scoring: scores results (evidence: `server/src/competition.mjs`)
- Drive integrity → Competitive scoring: validates scoring (evidence: `server/src/integrity.mjs`)
