# codewithteds/geofind-geospatial-intelligence-platform architecture

> Architecture diagram of the GitHub repository codewithteds/geofind-geospatial-intelligence-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codewithteds/geofind-geospatial-intelligence-platform
- Repository: https://github.com/codewithteds/geofind-geospatial-intelligence-platform

## Overview

Oxbit combines a location-intelligence toolkit with a location-based learning game. A client signs in, chooses an unlocked level, submits a geographic answer, and can review progress and rankings; administrators manage question content. Separately, GIS users run spatial tools over saved locations, with map-oriented results and documented external geodata integrations. The graph reflects controller and service calls visible in sampled source; several documented feature integrations have no sampled implementation, so their wiring is intentionally not inferred.

Main entry points: [`app/Http/Controllers/LocationController.php`](https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Http/Controllers/LocationController.php) (GIS Endpoints), [`app/Http/Controllers/Api/QuestionController.php`](https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Http/Controllers/Api/QuestionController.php) (Question API), [`app/Services/SpatialAnalysisService.php`](https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Services/SpatialAnalysisService.php) (Spatial Analysis), [`resources/js/play.js`](https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/resources/js/play.js) (Play Interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Portals and Access"]
  node_client_login["Client Login"]
  node_client_auth["Client Auth"]
  node_admin_login["Admin Login"]
end

subgraph group_game["Learning Game"]
  node_level_controller["Level Access"]
  node_level_service["Level Progress<br/>[LevelService.php]"]
  node_question_api["Question API"]
  node_question_service["Question Engine"]
  node_play_ui["Play Interface<br/>[play.js]"]
  node_leaderboard["Leaderboard<br/>[Leaderboard.php]"]
  node_map_ui["Game Map"]
end

subgraph group_gis["GIS Toolkit"]
  node_location_controller["GIS Endpoints"]
  node_location_service["Location Operations"]
  node_spatial_services["Spatial Analysis"]
  node_geocoding["Geocoding"]
  node_location_ui["GIS Tools"]
end

subgraph group_content["Content Administration"]
  node_admin_questions["Question Management<br/>[Index.php]"]
end

subgraph group_state["Domain State"]
  node_database[("Application Data<br/>[Location.php]")]
  node_user_model["User State<br/>[User.php]"]
  node_answer_model["Answer State<br/>[UserAnswer.php]"]
  node_question_model["Question State<br/>[Question.php]"]
end

node_client(("Client"))
node_admin(("Administrator"))
node_nominatim{{"Nominatim"}}
node_overpass{{"Overpass POI"}}
node_open_meteo{{"Open-Meteo"}}
node_open_elevation{{"Open-Elevation"}}

node_client -->|"signs in"| node_client_login
node_client_login -->|"authenticates"| node_client_auth
node_client_auth -->|"registers"| node_user_model
node_admin -->|"signs in"| node_admin_login
node_client -->|"opens levels"| node_level_controller
node_level_controller -->|"loads progress"| node_level_service
node_level_service -->|"reads progress"| node_user_model
node_client -->|"plays level"| node_play_ui
node_play_ui -->|"submits answer"| node_question_api
node_question_api -->|"handles request"| node_question_service
node_question_service -->|"manages content"| node_question_model
node_question_api -->|"checks access"| node_user_model
node_question_api -->|"records answers"| node_answer_model
node_play_ui -->|"shows review"| node_map_ui
node_client -->|"views rankings"| node_leaderboard
node_admin -->|"manages questions"| node_admin_questions
node_admin_questions -->|"manages content"| node_question_service
node_client -->|"uses GIS tools"| node_location_ui
node_location_ui -->|"requests analysis"| node_location_controller
node_location_controller -->|"runs operations"| node_location_service
node_location_controller -->|"requests analysis"| node_spatial_services
node_location_controller -->|"looks up address"| node_geocoding
node_location_service -->|"reads locations"| node_database
node_location_service -->|"writes locations"| node_database
node_location_controller -->|"validates locations"| node_database
node_geocoding -.->|"geocodes"| node_nominatim
node_spatial_services -.->|"finds POIs"| node_overpass
node_spatial_services -.->|"gets forecasts"| node_open_meteo
node_spatial_services -.->|"gets elevation"| node_open_elevation

click node_client_login "https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Http/Controllers/Client/Auth/LoginController.php"
click node_client_auth "https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Services/Auth/ClientAuthService.php"
click node_admin_login "https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Http/Controllers/Admin/Auth/LoginController.php"
click node_level_controller "https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Http/Controllers/Client/LevelController.php"
click node_level_service "https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Services/Game/LevelService.php"
click node_question_api "https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Http/Controllers/Api/QuestionController.php"
click node_question_service "https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Services/QuestionService.php"
click node_play_ui "https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/resources/js/play.js"
click node_leaderboard "https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Livewire/Leaderboard.php"
click node_admin_questions "https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Livewire/Admin/Questions/Index.php"
click node_location_controller "https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Http/Controllers/LocationController.php"
click node_location_service "https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Services/LocationService.php"
click node_spatial_services "https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Services/SpatialAnalysisService.php"
click node_geocoding "https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Services/GeocodingService.php"
click node_location_ui "https://github.com/codewithteds/geofind-geospatial-intelligence-platform/tree/main/resources/views/components/locations"
click node_map_ui "https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/resources/js/services/ReviewMapService.js"
click node_database "https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Models/Location.php"
click node_user_model "https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Models/User.php"
click node_answer_model "https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Models/UserAnswer.php"
click node_question_model "https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Models/Question.php"

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_login,node_client_auth,node_admin_login,node_client toneBlue
class node_level_controller,node_level_service,node_question_api,node_question_service,node_play_ui,node_leaderboard,node_map_ui toneAmber
class node_location_controller,node_location_service,node_spatial_services,node_geocoding,node_location_ui toneMint
class node_admin_questions toneRose
class node_database,node_user_model,node_answer_model,node_question_model,node_admin,node_nominatim,node_overpass,node_open_meteo,node_open_elevation toneIndigo
```

## Components

### Portals and Access

- [Client Login](https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Http/Controllers/Client/Auth/LoginController.php): `app/Http/Controllers/Client/Auth/LoginController.php`
- [Client Auth](https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Services/Auth/ClientAuthService.php): `app/Services/Auth/ClientAuthService.php`
- [Admin Login](https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Http/Controllers/Admin/Auth/LoginController.php): `app/Http/Controllers/Admin/Auth/LoginController.php`

### Learning Game

- [Level Access](https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Http/Controllers/Client/LevelController.php): `app/Http/Controllers/Client/LevelController.php`
- [Level Progress](https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Services/Game/LevelService.php): `app/Services/Game/LevelService.php`
- [Question API](https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Http/Controllers/Api/QuestionController.php): `app/Http/Controllers/Api/QuestionController.php`
- [Question Engine](https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Services/QuestionService.php): `app/Services/QuestionService.php`
- [Play Interface](https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/resources/js/play.js): `resources/js/play.js`
- [Leaderboard](https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Livewire/Leaderboard.php): `app/Livewire/Leaderboard.php`
- [Game Map](https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/resources/js/services/ReviewMapService.js): `resources/js/services/ReviewMapService.js`

### GIS Toolkit

- [GIS Endpoints](https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Http/Controllers/LocationController.php): `app/Http/Controllers/LocationController.php`
- [Location Operations](https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Services/LocationService.php): `app/Services/LocationService.php`
- [Spatial Analysis](https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Services/SpatialAnalysisService.php): `app/Services/SpatialAnalysisService.php`
- [Geocoding](https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Services/GeocodingService.php): `app/Services/GeocodingService.php`
- [GIS Tools](https://github.com/codewithteds/geofind-geospatial-intelligence-platform/tree/main/resources/views/components/locations): `resources/views/components/locations`

### Content Administration

- [Question Management](https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Livewire/Admin/Questions/Index.php): `app/Livewire/Admin/Questions/Index.php`

### Domain State

- [Application Data](https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Models/Location.php): `app/Models/Location.php`
- [User State](https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Models/User.php): `app/Models/User.php`
- [Answer State](https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Models/UserAnswer.php): `app/Models/UserAnswer.php`
- [Question State](https://github.com/codewithteds/geofind-geospatial-intelligence-platform/blob/main/app/Models/Question.php): `app/Models/Question.php`

### Other components

- **Client**
- **Administrator**
- **Nominatim**
- **Overpass POI**
- **Open-Meteo**
- **Open-Elevation**

## Connections

- Client → Client Login: signs in
- Client Login → Client Auth: authenticates
- Client Auth → User State: registers
- Administrator → Admin Login: signs in
- Client → Level Access: opens levels
- Level Access → Level Progress: loads progress
- Level Progress → User State: reads progress
- Client → Play Interface: plays level
- Play Interface → Question API: submits answer
- Question API → Question Engine: handles request
- Question Engine → Question State: manages content
- Question API → User State: checks access
- Question API → Answer State: records answers
- Play Interface → Game Map: shows review
- Client → Leaderboard: views rankings
- Administrator → Question Management: manages questions
- Question Management → Question Engine: manages content
- Client → GIS Tools: uses GIS tools
- GIS Tools → GIS Endpoints: requests analysis
- GIS Endpoints → Location Operations: runs operations
- GIS Endpoints → Spatial Analysis: requests analysis
- GIS Endpoints → Geocoding: looks up address
- Location Operations → Application Data: reads locations
- Location Operations → Application Data: writes locations
- GIS Endpoints → Application Data: validates locations
- Geocoding → Nominatim: geocodes
- Spatial Analysis → Overpass POI: finds POIs
- Spatial Analysis → Open-Meteo: gets forecasts
- Spatial Analysis → Open-Elevation: gets elevation