How yacine204/geoguessr_assistant works
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 Prediction orchestrator · conversation.py Conversation service · backend/main.py FastAPI app · auth.py Authentication routes
Components 27
Client experience
- React app
frontend/client/src/App.jsx - Globe and chat UI
frontend/client/src/components/globe/globe.jsx - API client
frontend/client/src/services/apiClient.js
Backend API
- FastAPI app
backend/main.py - Image guess route
backend/routes/guess.py - Authentication routes
backend/routes/auth.py - Conversation routes
backend/routes/conversation.py
Location analysis
- Sign detection
assistant_logic/helpers/file_parsing.py - OCR and text
assistant_logic/helpers/ocr.py - Language filtering
assistant_logic/helpers/language_filtering.py - Country filtering
assistant_logic/helpers/country_filtering.py - Convention and country rules
assistant_logic/rules/convention/country_distribution.py - Country distribution
assistant_logic/rules/distribution/geoguessr_country_distribution.py - Prediction orchestrator
assistant_logic/main.py
Accounts and history
- PostgreSQL database
backend/database/db.py - Token security
backend/core/security.py - User records
backend/models/user.py - Conversation records
backend/models/conversation.py - Image records
backend/models/image.py - Reply records
backend/models/reply.py - Conversation service
backend/service/conversation.py - Image hosting
backend/service/cloudinary.py
Geographic services
- Place search
assistant_logic/helpers/nominatim.py - Location clustering
assistant_logic/helpers/location_clustering.py - OSM validation
assistant_logic/helpers/over_pass_query.py
Other components
- GeoGuessr player
- OpenStreetMap services
Connections 33
- GeoGuessr player → React app: uses
README.md - React app → Globe and chat UI: renders
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
backend/main.py - Image guess route → Prediction orchestrator: runs prediction
backend/routes/guess.py - Prediction orchestrator → Sign detection: detects signs
assistant_logic/main.py - Prediction orchestrator → OCR and text: extracts text
assistant_logic/main.py - Prediction orchestrator → Language filtering: detects language
assistant_logic/main.py - Prediction orchestrator → Country filtering: filters countries
assistant_logic/main.py - Country filtering → Convention and country rules: uses convention data
assistant_logic/helpers/country_filtering.py - Country filtering → Language filtering: uses language clues
assistant_logic/helpers/country_filtering.py - Country filtering → Country distribution: ranks countries
- Prediction orchestrator → Place search: searches candidates
assistant_logic/main.py - Prediction orchestrator → Location clustering: clusters locations
assistant_logic/main.py - Prediction orchestrator → OSM validation: validates candidates
assistant_logic/main.py - OSM validation → OpenStreetMap services: queries features
assistant_logic/helpers/over_pass_query.py - Place search → OpenStreetMap services: searches places
- FastAPI app → Authentication routes: registers route
backend/main.py - FastAPI app → Conversation routes: registers route
backend/main.py - Authentication routes → PostgreSQL database: queries users
backend/routes/auth.py - Authentication routes → Token security: checks credentials
backend/routes/auth.py - Authentication routes → User records: creates users
backend/routes/auth.py - Conversation routes → Conversation service: manages history
backend/routes/conversation.py - Conversation service → PostgreSQL database: persists records
backend/service/conversation.py - Conversation service → Conversation records: creates and loads
backend/service/conversation.py - Conversation service → Image records: creates images
backend/service/conversation.py - Conversation service → Reply records: stores replies
backend/service/conversation.py - Conversation service → Image hosting: uploads images
backend/service/conversation.py - Image hosting → OpenStreetMap services: hosts images
- Conversation records → User records: belongs to user
backend/models/conversation.py - Conversation records → Image records: has images
backend/models/conversation.py - Image records → Reply records: has reply
backend/models/image.py