# yacine204/geoguessr_assistant architecture

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

- Interactive diagram: https://gitdiagram.com/yacine204/geoguessr_assistant
- Repository: https://github.com/yacine204/geoguessr_assistant

## Overview

GeoGuessr Location Assistant is a street-image location inference product with a React chatbot interface, FastAPI backend, and computer-vision/geographic analysis pipeline. The principal workflow submits an image, detects road-sign conventions, extracts text and language, narrows likely countries, searches for candidate places, and validates candidates against OpenStreetMap data. The backend also supports accounts and saved image/reply conversations. Pipeline stages are visible in `assistant_logic/main.py`; several UI and helper implementations were not sampled, so uncertain connections are omitted or marked unverified.

Main entry points: [`assistant_logic/main.py`](https://github.com/yacine204/geoguessr_assistant/blob/main/assistant_logic/main.py) (Prediction orchestrator), [`backend/service/conversation.py`](https://github.com/yacine204/geoguessr_assistant/blob/main/backend/service/conversation.py) (Conversation service), [`backend/main.py`](https://github.com/yacine204/geoguessr_assistant/blob/main/backend/main.py) (FastAPI app), [`backend/routes/auth.py`](https://github.com/yacine204/geoguessr_assistant/blob/main/backend/routes/auth.py) (Authentication routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_webapp["React app<br/>[App.jsx]"]
  node_globe["Globe and chat UI<br/>[globe.jsx]"]
  node_api_client["API client<br/>[apiClient.js]"]
end

subgraph group_api["Backend API"]
  node_api_server["FastAPI app<br/>[main.py]"]
  node_guess_route["Image guess route<br/>[guess.py]"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_conversation_routes["Conversation routes<br/>[conversation.py]"]
end

subgraph group_analysis["Location analysis"]
  node_sign_detect["Sign detection<br/>[file_parsing.py]"]
  node_ocr["OCR and text<br/>[ocr.py]"]
  node_language["Language filtering"]
  node_country_filter["Country filtering"]
  node_country_rules["Convention and country rules"]
  node_country_distribution["Country distribution"]
  node_pipeline["Prediction orchestrator<br/>[main.py]"]
end

subgraph group_state["Accounts and history"]
  node_db[("PostgreSQL database<br/>[db.py]")]
  node_security["Token security<br/>[security.py]"]
  node_user_model["User records<br/>[user.py]"]
  node_conversation_model["Conversation records<br/>[conversation.py]"]
  node_image_model["Image records<br/>[image.py]"]
  node_reply_model["Reply records<br/>[reply.py]"]
  node_conversation_service["Conversation service<br/>[conversation.py]"]
  node_cloudinary["Image hosting<br/>[cloudinary.py]"]
end

subgraph group_geo["Geographic services"]
  node_nominatim["Place search<br/>[nominatim.py]"]
  node_clustering["Location clustering"]
  node_overpass["OSM validation<br/>[over_pass_query.py]"]
end

node_player(("GeoGuessr player"))
node_osm(("OpenStreetMap services"))

node_player -->|"uses"| node_webapp
node_webapp -->|"renders"| node_globe
node_globe -.->|"requests analysis"| node_api_client
node_api_client -.->|"HTTP requests"| node_api_server
node_api_server -->|"registers route"| node_guess_route
node_guess_route -->|"runs prediction"| node_pipeline
node_pipeline -->|"detects signs"| node_sign_detect
node_pipeline -->|"extracts text"| node_ocr
node_pipeline -->|"detects language"| node_language
node_pipeline -->|"filters countries"| node_country_filter
node_country_filter -->|"uses convention data"| node_country_rules
node_country_filter -->|"uses language clues"| node_language
node_country_filter -->|"ranks countries"| node_country_distribution
node_pipeline -->|"searches candidates"| node_nominatim
node_pipeline -->|"clusters locations"| node_clustering
node_pipeline -->|"validates candidates"| node_overpass
node_overpass -->|"queries features"| node_osm
node_nominatim -.->|"searches places"| node_osm
node_api_server -->|"registers route"| node_auth_routes
node_api_server -->|"registers route"| node_conversation_routes
node_auth_routes -->|"queries users"| node_db
node_auth_routes -->|"checks credentials"| node_security
node_auth_routes -->|"creates users"| node_user_model
node_conversation_routes -->|"manages history"| node_conversation_service
node_conversation_service -->|"persists records"| node_db
node_conversation_service -->|"creates and loads"| node_conversation_model
node_conversation_service -->|"creates images"| node_image_model
node_conversation_service -->|"stores replies"| node_reply_model
node_conversation_service -->|"uploads images"| node_cloudinary
node_cloudinary -.->|"hosts images"| node_osm
node_conversation_model -->|"belongs to user"| node_user_model
node_conversation_model -->|"has images"| node_image_model
node_image_model -->|"has reply"| node_reply_model

click node_webapp "https://github.com/yacine204/geoguessr_assistant/blob/main/frontend/client/src/App.jsx"
click node_globe "https://github.com/yacine204/geoguessr_assistant/blob/main/frontend/client/src/components/globe/globe.jsx"
click node_api_client "https://github.com/yacine204/geoguessr_assistant/blob/main/frontend/client/src/services/apiClient.js"
click node_api_server "https://github.com/yacine204/geoguessr_assistant/blob/main/backend/main.py"
click node_guess_route "https://github.com/yacine204/geoguessr_assistant/blob/main/backend/routes/guess.py"
click node_auth_routes "https://github.com/yacine204/geoguessr_assistant/blob/main/backend/routes/auth.py"
click node_conversation_routes "https://github.com/yacine204/geoguessr_assistant/blob/main/backend/routes/conversation.py"
click node_sign_detect "https://github.com/yacine204/geoguessr_assistant/blob/main/assistant_logic/helpers/file_parsing.py"
click node_ocr "https://github.com/yacine204/geoguessr_assistant/blob/main/assistant_logic/helpers/ocr.py"
click node_language "https://github.com/yacine204/geoguessr_assistant/blob/main/assistant_logic/helpers/language_filtering.py"
click node_country_filter "https://github.com/yacine204/geoguessr_assistant/blob/main/assistant_logic/helpers/country_filtering.py"
click node_country_rules "https://github.com/yacine204/geoguessr_assistant/blob/main/assistant_logic/rules/convention/country_distribution.py"
click node_country_distribution "https://github.com/yacine204/geoguessr_assistant/blob/main/assistant_logic/rules/distribution/geoguessr_country_distribution.py"
click node_pipeline "https://github.com/yacine204/geoguessr_assistant/blob/main/assistant_logic/main.py"
click node_nominatim "https://github.com/yacine204/geoguessr_assistant/blob/main/assistant_logic/helpers/nominatim.py"
click node_clustering "https://github.com/yacine204/geoguessr_assistant/blob/main/assistant_logic/helpers/location_clustering.py"
click node_overpass "https://github.com/yacine204/geoguessr_assistant/blob/main/assistant_logic/helpers/over_pass_query.py"
click node_db "https://github.com/yacine204/geoguessr_assistant/blob/main/backend/database/db.py"
click node_security "https://github.com/yacine204/geoguessr_assistant/blob/main/backend/core/security.py"
click node_user_model "https://github.com/yacine204/geoguessr_assistant/blob/main/backend/models/user.py"
click node_conversation_model "https://github.com/yacine204/geoguessr_assistant/blob/main/backend/models/conversation.py"
click node_image_model "https://github.com/yacine204/geoguessr_assistant/blob/main/backend/models/image.py"
click node_reply_model "https://github.com/yacine204/geoguessr_assistant/blob/main/backend/models/reply.py"
click node_conversation_service "https://github.com/yacine204/geoguessr_assistant/blob/main/backend/service/conversation.py"
click node_cloudinary "https://github.com/yacine204/geoguessr_assistant/blob/main/backend/service/cloudinary.py"

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_webapp,node_globe,node_api_client toneBlue
class node_api_server,node_guess_route,node_auth_routes,node_conversation_routes toneAmber
class node_sign_detect,node_ocr,node_language,node_country_filter,node_country_rules,node_country_distribution,node_pipeline toneMint
class node_db,node_security,node_user_model,node_conversation_model,node_image_model,node_reply_model,node_conversation_service,node_cloudinary toneRose
class node_nominatim,node_clustering,node_overpass,node_player,node_osm toneIndigo
```

## Components

### Client experience

- [React app](https://github.com/yacine204/geoguessr_assistant/blob/main/frontend/client/src/App.jsx): `frontend/client/src/App.jsx`
- [Globe and chat UI](https://github.com/yacine204/geoguessr_assistant/blob/main/frontend/client/src/components/globe/globe.jsx): `frontend/client/src/components/globe/globe.jsx`
- [API client](https://github.com/yacine204/geoguessr_assistant/blob/main/frontend/client/src/services/apiClient.js): `frontend/client/src/services/apiClient.js`

### Backend API

- [FastAPI app](https://github.com/yacine204/geoguessr_assistant/blob/main/backend/main.py): `backend/main.py`
- [Image guess route](https://github.com/yacine204/geoguessr_assistant/blob/main/backend/routes/guess.py): `backend/routes/guess.py`
- [Authentication routes](https://github.com/yacine204/geoguessr_assistant/blob/main/backend/routes/auth.py): `backend/routes/auth.py`
- [Conversation routes](https://github.com/yacine204/geoguessr_assistant/blob/main/backend/routes/conversation.py): `backend/routes/conversation.py`

### Location analysis

- [Sign detection](https://github.com/yacine204/geoguessr_assistant/blob/main/assistant_logic/helpers/file_parsing.py): `assistant_logic/helpers/file_parsing.py`
- [OCR and text](https://github.com/yacine204/geoguessr_assistant/blob/main/assistant_logic/helpers/ocr.py): `assistant_logic/helpers/ocr.py`
- [Language filtering](https://github.com/yacine204/geoguessr_assistant/blob/main/assistant_logic/helpers/language_filtering.py): `assistant_logic/helpers/language_filtering.py`
- [Country filtering](https://github.com/yacine204/geoguessr_assistant/blob/main/assistant_logic/helpers/country_filtering.py): `assistant_logic/helpers/country_filtering.py`
- [Convention and country rules](https://github.com/yacine204/geoguessr_assistant/blob/main/assistant_logic/rules/convention/country_distribution.py): `assistant_logic/rules/convention/country_distribution.py`
- [Country distribution](https://github.com/yacine204/geoguessr_assistant/blob/main/assistant_logic/rules/distribution/geoguessr_country_distribution.py): `assistant_logic/rules/distribution/geoguessr_country_distribution.py`
- [Prediction orchestrator](https://github.com/yacine204/geoguessr_assistant/blob/main/assistant_logic/main.py): `assistant_logic/main.py`

### Accounts and history

- [PostgreSQL database](https://github.com/yacine204/geoguessr_assistant/blob/main/backend/database/db.py): `backend/database/db.py`
- [Token security](https://github.com/yacine204/geoguessr_assistant/blob/main/backend/core/security.py): `backend/core/security.py`
- [User records](https://github.com/yacine204/geoguessr_assistant/blob/main/backend/models/user.py): `backend/models/user.py`
- [Conversation records](https://github.com/yacine204/geoguessr_assistant/blob/main/backend/models/conversation.py): `backend/models/conversation.py`
- [Image records](https://github.com/yacine204/geoguessr_assistant/blob/main/backend/models/image.py): `backend/models/image.py`
- [Reply records](https://github.com/yacine204/geoguessr_assistant/blob/main/backend/models/reply.py): `backend/models/reply.py`
- [Conversation service](https://github.com/yacine204/geoguessr_assistant/blob/main/backend/service/conversation.py): `backend/service/conversation.py`
- [Image hosting](https://github.com/yacine204/geoguessr_assistant/blob/main/backend/service/cloudinary.py): `backend/service/cloudinary.py`

### Geographic services

- [Place search](https://github.com/yacine204/geoguessr_assistant/blob/main/assistant_logic/helpers/nominatim.py): `assistant_logic/helpers/nominatim.py`
- [Location clustering](https://github.com/yacine204/geoguessr_assistant/blob/main/assistant_logic/helpers/location_clustering.py): `assistant_logic/helpers/location_clustering.py`
- [OSM validation](https://github.com/yacine204/geoguessr_assistant/blob/main/assistant_logic/helpers/over_pass_query.py): `assistant_logic/helpers/over_pass_query.py`

### Other components

- **GeoGuessr player**
- **OpenStreetMap services**

## Connections

- GeoGuessr player → React app: uses (evidence: `README.md`)
- React app → Globe and chat UI: renders (evidence: `frontend/client/src/App.jsx`)
- Globe and chat UI → API client: requests analysis
- API client → FastAPI app: HTTP requests
- FastAPI app → Image guess route: registers route (evidence: `backend/main.py`)
- Image guess route → Prediction orchestrator: runs prediction (evidence: `backend/routes/guess.py`)
- Prediction orchestrator → Sign detection: detects signs (evidence: `assistant_logic/main.py`)
- Prediction orchestrator → OCR and text: extracts text (evidence: `assistant_logic/main.py`)
- Prediction orchestrator → Language filtering: detects language (evidence: `assistant_logic/main.py`)
- Prediction orchestrator → Country filtering: filters countries (evidence: `assistant_logic/main.py`)
- Country filtering → Convention and country rules: uses convention data (evidence: `assistant_logic/helpers/country_filtering.py`)
- Country filtering → Language filtering: uses language clues (evidence: `assistant_logic/helpers/country_filtering.py`)
- Country filtering → Country distribution: ranks countries
- Prediction orchestrator → Place search: searches candidates (evidence: `assistant_logic/main.py`)
- Prediction orchestrator → Location clustering: clusters locations (evidence: `assistant_logic/main.py`)
- Prediction orchestrator → OSM validation: validates candidates (evidence: `assistant_logic/main.py`)
- OSM validation → OpenStreetMap services: queries features (evidence: `assistant_logic/helpers/over_pass_query.py`)
- Place search → OpenStreetMap services: searches places
- FastAPI app → Authentication routes: registers route (evidence: `backend/main.py`)
- FastAPI app → Conversation routes: registers route (evidence: `backend/main.py`)
- Authentication routes → PostgreSQL database: queries users (evidence: `backend/routes/auth.py`)
- Authentication routes → Token security: checks credentials (evidence: `backend/routes/auth.py`)
- Authentication routes → User records: creates users (evidence: `backend/routes/auth.py`)
- Conversation routes → Conversation service: manages history (evidence: `backend/routes/conversation.py`)
- Conversation service → PostgreSQL database: persists records (evidence: `backend/service/conversation.py`)
- Conversation service → Conversation records: creates and loads (evidence: `backend/service/conversation.py`)
- Conversation service → Image records: creates images (evidence: `backend/service/conversation.py`)
- Conversation service → Reply records: stores replies (evidence: `backend/service/conversation.py`)
- Conversation service → Image hosting: uploads images (evidence: `backend/service/conversation.py`)
- Image hosting → OpenStreetMap services: hosts images
- Conversation records → User records: belongs to user (evidence: `backend/models/conversation.py`)
- Conversation records → Image records: has images (evidence: `backend/models/conversation.py`)
- Image records → Reply records: has reply (evidence: `backend/models/image.py`)
