# homssalomssa/geo-rag-platform architecture

> Architecture diagram of the GitHub repository homssalomssa/geo-rag-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/homssalomssa/geo-rag-platform
- Repository: https://github.com/homssalomssa/geo-rag-platform

## Overview

Geo-RAG Platform accepts satellite images and analysis settings through a React UI, submits asynchronous jobs to FastAPI, and returns progress and completed reports. Backend workers extract visual features, reserve a spatial-enrichment stage, retrieve urban-geography knowledge, and generate an answer; the API exposes job, health, cache, and spatial status functions. A separate orchestrator coordinates the same analysis services. The README documents the main stages; some worker links are supported by the source index, while unsampled implementation details are not inferred.

Main entry points: [`app/services/job_queue.py`](https://github.com/homssalomssa/geo-rag-platform/blob/main/app/services/job_queue.py) (Job Queue), [`frontend/src/App.jsx`](https://github.com/homssalomssa/geo-rag-platform/blob/main/frontend/src/App.jsx) (App Flow), [`app/api/routes.py`](https://github.com/homssalomssa/geo-rag-platform/blob/main/app/api/routes.py) (HTTP Routes), [`app/workers/retriever.py`](https://github.com/homssalomssa/geo-rag-platform/blob/main/app/workers/retriever.py) (Retrieval Worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Analysis UI"]
  node_app["App Flow<br/>[App.jsx]"]
  node_upload["Upload Controls<br/>[UploadPage.jsx]"]
  node_results["Results View<br/>[ResultsPage.jsx]"]
  node_status["System Status"]
  node_api_client["API Client<br/>[api.js]"]
end

subgraph group_api["API and Jobs"]
  node_routes["HTTP Routes<br/>[routes.py]"]
  node_schemas["API Schemas<br/>[schemas.py]"]
  node_queue[("Job Queue<br/>[job_queue.py]")]
end

subgraph group_pipeline["Analysis Pipeline"]
  node_vision_worker["Vision Worker"]
  node_retriever["Retrieval Worker<br/>[retriever.py]"]
  node_answer_worker["Answer Worker"]
  node_orchestrator["Analysis Orchestrator<br/>[orchestrator.py]"]
end

subgraph group_knowledge["Knowledge and Context"]
  node_cache[("Result Cache<br/>[cache_manager.py]")]
  node_spatial["Spatial Enrichment"]
  node_rag["Knowledge Retrieval<br/>[rag_service.py]"]
end

subgraph group_inference["Local Inference"]
  node_prompt["Prompt Builder<br/>[prompt_builder.py]"]
  node_vision["Vision Service<br/>[vision_service.py]"]
  node_llm["LLM Service<br/>[llm_service.py]"]
end

node_user(("Analyst"))
node_ollama{{"Ollama"}}

node_user -->|"sets analysis"| node_app
node_app -->|"renders"| node_upload
node_app -->|"submits and polls"| node_api_client
node_app -->|"renders results"| node_results
node_app -->|"renders status"| node_status
node_api_client -->|"calls API"| node_routes
node_routes -->|"uses schemas"| node_schemas
node_routes -->|"tracks jobs"| node_queue
node_routes -->|"manages cache"| node_cache
node_routes -->|"checks status"| node_spatial
node_queue -.->|"dispatches stages"| node_vision_worker
node_queue -.->|"dispatches stages"| node_retriever
node_queue -.->|"dispatches stages"| node_answer_worker
node_vision_worker -->|"extracts features"| node_vision
node_vision_worker -->|"caches features"| node_cache
node_vision_worker -->|"updates progress"| node_queue
node_retriever -->|"retrieves knowledge"| node_rag
node_retriever -->|"enriches context"| node_spatial
node_retriever -->|"caches retrieval"| node_cache
node_retriever -->|"updates progress"| node_queue
node_answer_worker -->|"builds prompt"| node_prompt
node_answer_worker -->|"generates answer"| node_llm
node_answer_worker -->|"reads and stores"| node_cache
node_answer_worker -->|"updates progress"| node_queue
node_orchestrator -->|"extracts features"| node_vision
node_orchestrator -->|"retrieves context"| node_rag
node_orchestrator -->|"builds prompt"| node_prompt
node_orchestrator -->|"generates answer"| node_llm
node_vision -->|"requests inference"| node_ollama
node_llm -->|"requests generation"| node_ollama

click node_app "https://github.com/homssalomssa/geo-rag-platform/blob/main/frontend/src/App.jsx"
click node_upload "https://github.com/homssalomssa/geo-rag-platform/blob/main/frontend/src/pages/UploadPage.jsx"
click node_results "https://github.com/homssalomssa/geo-rag-platform/blob/main/frontend/src/pages/ResultsPage.jsx"
click node_status "https://github.com/homssalomssa/geo-rag-platform/blob/main/frontend/src/pages/SystemStatusPage.jsx"
click node_api_client "https://github.com/homssalomssa/geo-rag-platform/blob/main/frontend/src/utils/api.js"
click node_routes "https://github.com/homssalomssa/geo-rag-platform/blob/main/app/api/routes.py"
click node_schemas "https://github.com/homssalomssa/geo-rag-platform/blob/main/app/api/schemas.py"
click node_queue "https://github.com/homssalomssa/geo-rag-platform/blob/main/app/services/job_queue.py"
click node_vision_worker "https://github.com/homssalomssa/geo-rag-platform/blob/main/app/workers/vision_extractor.py"
click node_retriever "https://github.com/homssalomssa/geo-rag-platform/blob/main/app/workers/retriever.py"
click node_answer_worker "https://github.com/homssalomssa/geo-rag-platform/blob/main/app/workers/answer_generator.py"
click node_orchestrator "https://github.com/homssalomssa/geo-rag-platform/blob/main/app/core/orchestrator.py"
click node_cache "https://github.com/homssalomssa/geo-rag-platform/blob/main/app/utils/cache_manager.py"
click node_spatial "https://github.com/homssalomssa/geo-rag-platform/blob/main/app/utils/spatial_enricher.py"
click node_rag "https://github.com/homssalomssa/geo-rag-platform/blob/main/app/services/rag_service.py"
click node_prompt "https://github.com/homssalomssa/geo-rag-platform/blob/main/app/core/prompt_builder.py"
click node_vision "https://github.com/homssalomssa/geo-rag-platform/blob/main/app/services/vision_service.py"
click node_llm "https://github.com/homssalomssa/geo-rag-platform/blob/main/app/services/llm_service.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_app,node_upload,node_results,node_status,node_api_client toneBlue
class node_routes,node_schemas,node_queue toneAmber
class node_vision_worker,node_retriever,node_answer_worker,node_orchestrator toneMint
class node_cache,node_spatial,node_rag toneRose
class node_prompt,node_vision,node_llm,node_user,node_ollama toneIndigo
```

## Components

### Analysis UI

- [App Flow](https://github.com/homssalomssa/geo-rag-platform/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Upload Controls](https://github.com/homssalomssa/geo-rag-platform/blob/main/frontend/src/pages/UploadPage.jsx): `frontend/src/pages/UploadPage.jsx`
- [Results View](https://github.com/homssalomssa/geo-rag-platform/blob/main/frontend/src/pages/ResultsPage.jsx): `frontend/src/pages/ResultsPage.jsx`
- [System Status](https://github.com/homssalomssa/geo-rag-platform/blob/main/frontend/src/pages/SystemStatusPage.jsx): `frontend/src/pages/SystemStatusPage.jsx`
- [API Client](https://github.com/homssalomssa/geo-rag-platform/blob/main/frontend/src/utils/api.js): `frontend/src/utils/api.js`

### API and Jobs

- [HTTP Routes](https://github.com/homssalomssa/geo-rag-platform/blob/main/app/api/routes.py): `app/api/routes.py`
- [API Schemas](https://github.com/homssalomssa/geo-rag-platform/blob/main/app/api/schemas.py): `app/api/schemas.py`
- [Job Queue](https://github.com/homssalomssa/geo-rag-platform/blob/main/app/services/job_queue.py): `app/services/job_queue.py`

### Analysis Pipeline

- [Vision Worker](https://github.com/homssalomssa/geo-rag-platform/blob/main/app/workers/vision_extractor.py): `app/workers/vision_extractor.py`
- [Retrieval Worker](https://github.com/homssalomssa/geo-rag-platform/blob/main/app/workers/retriever.py): `app/workers/retriever.py`
- [Answer Worker](https://github.com/homssalomssa/geo-rag-platform/blob/main/app/workers/answer_generator.py): `app/workers/answer_generator.py`
- [Analysis Orchestrator](https://github.com/homssalomssa/geo-rag-platform/blob/main/app/core/orchestrator.py): `app/core/orchestrator.py`

### Knowledge and Context

- [Result Cache](https://github.com/homssalomssa/geo-rag-platform/blob/main/app/utils/cache_manager.py): `app/utils/cache_manager.py`
- [Spatial Enrichment](https://github.com/homssalomssa/geo-rag-platform/blob/main/app/utils/spatial_enricher.py): `app/utils/spatial_enricher.py`
- [Knowledge Retrieval](https://github.com/homssalomssa/geo-rag-platform/blob/main/app/services/rag_service.py): `app/services/rag_service.py`

### Local Inference

- [Prompt Builder](https://github.com/homssalomssa/geo-rag-platform/blob/main/app/core/prompt_builder.py): `app/core/prompt_builder.py`
- [Vision Service](https://github.com/homssalomssa/geo-rag-platform/blob/main/app/services/vision_service.py): `app/services/vision_service.py`
- [LLM Service](https://github.com/homssalomssa/geo-rag-platform/blob/main/app/services/llm_service.py): `app/services/llm_service.py`

### Other components

- **Analyst**
- **Ollama**

## Connections

- Analyst → App Flow: sets analysis
- App Flow → Upload Controls: renders (evidence: `frontend/src/App.jsx`)
- App Flow → API Client: submits and polls (evidence: `frontend/src/App.jsx`)
- App Flow → Results View: renders results (evidence: `frontend/src/App.jsx`)
- App Flow → System Status: renders status (evidence: `frontend/src/App.jsx`)
- API Client → HTTP Routes: calls API
- HTTP Routes → API Schemas: uses schemas (evidence: `app/api/routes.py`)
- HTTP Routes → Job Queue: tracks jobs (evidence: `app/api/routes.py`)
- HTTP Routes → Result Cache: manages cache (evidence: `app/api/routes.py`)
- HTTP Routes → Spatial Enrichment: checks status (evidence: `app/api/routes.py`)
- Job Queue → Vision Worker: dispatches stages (evidence: `app/workers/vision_extractor.py`)
- Job Queue → Retrieval Worker: dispatches stages (evidence: `app/workers/retriever.py`)
- Job Queue → Answer Worker: dispatches stages (evidence: `app/workers/answer_generator.py`)
- Vision Worker → Vision Service: extracts features (evidence: `app/workers/vision_extractor.py`)
- Vision Worker → Result Cache: caches features (evidence: `app/workers/vision_extractor.py`)
- Vision Worker → Job Queue: updates progress (evidence: `app/workers/vision_extractor.py`)
- Retrieval Worker → Knowledge Retrieval: retrieves knowledge (evidence: `app/workers/retriever.py`)
- Retrieval Worker → Spatial Enrichment: enriches context (evidence: `app/workers/retriever.py`)
- Retrieval Worker → Result Cache: caches retrieval (evidence: `app/workers/retriever.py`)
- Retrieval Worker → Job Queue: updates progress (evidence: `app/workers/retriever.py`)
- Answer Worker → Prompt Builder: builds prompt (evidence: `app/workers/answer_generator.py`)
- Answer Worker → LLM Service: generates answer (evidence: `app/workers/answer_generator.py`)
- Answer Worker → Result Cache: reads and stores (evidence: `app/workers/answer_generator.py`)
- Answer Worker → Job Queue: updates progress (evidence: `app/workers/answer_generator.py`)
- Analysis Orchestrator → Vision Service: extracts features (evidence: `app/core/orchestrator.py`)
- Analysis Orchestrator → Knowledge Retrieval: retrieves context (evidence: `app/core/orchestrator.py`)
- Analysis Orchestrator → Prompt Builder: builds prompt (evidence: `app/core/orchestrator.py`)
- Analysis Orchestrator → LLM Service: generates answer (evidence: `app/core/orchestrator.py`)
- Vision Service → Ollama: requests inference
- LLM Service → Ollama: requests generation (evidence: `app/services/llm_service.py`)
