# praneyaarora/satquerryai architecture

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

- Interactive diagram: https://gitdiagram.com/praneyaarora/satquerryai
- Repository: https://github.com/praneyaarora/satquerryai

## Overview

SatQuery is an Earth-observation assistant: users upload GeoTIFFs and ask natural-language questions, then receive validated raster context, tool-driven geospatial analyses, and a summary through the React UI, REST API, or MCP interface. The graph emphasizes the documented upload and query workflows and preserves the major imagery, weather, analysis, vision, and workflow capabilities. Some orchestrator internals and route wiring are unsampled; uncertain connections are omitted rather than inferred.

Main entry points: [`backend/tools/executor.py`](https://github.com/praneyaarora/satquerryai/blob/main/backend/tools/executor.py) (Tool executor), [`satquery_server.py`](https://github.com/praneyaarora/satquerryai/blob/main/satquery_server.py) (MCP tool server), [`backend/orchestrator/graph.py`](https://github.com/praneyaarora/satquerryai/blob/main/backend/orchestrator/graph.py) (Query orchestration), [`backend/main.py`](https://github.com/praneyaarora/satquerryai/blob/main/backend/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User interfaces"]
  node_web["React chat UI<br/>[App.jsx]"]
  node_mcp["MCP tool server<br/>[satquery_server.py]"]
  node_answers["Results and artifacts"]
end

subgraph group_api["API and ingestion"]
  node_rest["FastAPI app<br/>[main.py]"]
  node_query_route["Query routes<br/>[query.py]"]
  node_upload_route["Raster upload<br/>[uploads.py]"]
  node_raster_route["Raster preview routes<br/>[rasters.py]"]
  node_ingest["Raster ingestion<br/>[ingest_graph.py]"]
end

subgraph group_agent["Planning and execution"]
  node_state["Query state<br/>[state.py]"]
  node_query_graph["Query orchestration<br/>[graph.py]"]
  node_planner["LLM planning<br/>[llm.py]"]
  node_registry["Tool registry<br/>[registry.py]"]
  node_executor["Tool executor<br/>[executor.py]"]
end

subgraph group_science["Earth observation tools"]
  node_workflows["Mission workflows"]
  node_optical["Optical imagery"]
  node_multispectral["Multispectral imagery"]
  node_sar["SAR imagery"]
  node_weather["Weather data"]
  node_indices["Vegetation indices"]
  node_metadata["GeoTIFF metadata"]
  node_temporal["Temporal change"]
  node_landcover["Landcover terrain"]
  node_webintel["Web intelligence"]
  node_geocoding["Geocoding and POI"]
  node_affine["Affine markup"]
end

subgraph group_vision["Vision and rendering"]
  node_preview["Raster rendering<br/>[raster_preview.py]"]
  node_vision_tool["Vision providers"]
  node_local_vlm["Local model service<br/>[server.py]"]
end

node_user(("User"))

node_user -->|"asks or uploads"| node_web
node_web -->|"HTTP requests"| node_rest
node_rest -->|"mounts routes"| node_query_route
node_rest -->|"mounts routes"| node_upload_route
node_rest -->|"mounts routes"| node_raster_route
node_query_route -->|"runs query"| node_query_graph
node_upload_route -->|"runs ingestion"| node_ingest
node_ingest -->|"executes metadata and geocode tools"| node_executor
node_ingest -->|"validates raster"| node_metadata
node_query_route -->|"uses query state"| node_state
node_query_graph -->|"shares state"| node_state
node_query_graph -->|"plans requests"| node_planner
node_query_graph -->|"loads tool registry"| node_registry
node_executor -->|"resolves tools"| node_registry
node_query_graph -.->|"dispatches tools"| node_executor
node_executor -->|"calls"| node_optical
node_executor -->|"calls"| node_multispectral
node_executor -->|"calls"| node_sar
node_executor -->|"calls"| node_weather
node_executor -->|"calls"| node_indices
node_executor -->|"calls"| node_metadata
node_executor -->|"calls"| node_temporal
node_executor -->|"calls"| node_landcover
node_executor -->|"calls"| node_webintel
node_executor -->|"calls"| node_geocoding
node_executor -->|"calls"| node_affine
node_executor -->|"dispatches missions"| node_workflows
node_mcp -->|"exposes tools"| node_optical
node_mcp -->|"exposes tools"| node_multispectral
node_mcp -->|"exposes tools"| node_sar
node_mcp -->|"exposes tools"| node_weather
node_mcp -.->|"exposes tools"| node_indices
node_mcp -.->|"exposes tools"| node_metadata
node_mcp -.->|"exposes tools"| node_temporal
node_mcp -.->|"exposes tools"| node_landcover
node_mcp -.->|"exposes tools"| node_webintel
node_mcp -->|"exposes tools"| node_geocoding
node_mcp -->|"exposes tools"| node_affine
node_raster_route -->|"renders preview"| node_preview
node_executor -->|"renders vision input"| node_preview
node_preview -.->|"uses markup engine"| node_affine
node_executor -.->|"invokes vision"| node_vision_tool
node_vision_tool -.->|"optional local inference"| node_local_vlm
node_query_route -->|"returns query results"| node_answers
node_web -.->|"shows results"| node_answers

click node_web "https://github.com/praneyaarora/satquerryai/blob/main/frontend/src/App.jsx"
click node_rest "https://github.com/praneyaarora/satquerryai/blob/main/backend/main.py"
click node_query_route "https://github.com/praneyaarora/satquerryai/blob/main/backend/api/routes/query.py"
click node_upload_route "https://github.com/praneyaarora/satquerryai/blob/main/backend/api/routes/uploads.py"
click node_raster_route "https://github.com/praneyaarora/satquerryai/blob/main/backend/api/routes/rasters.py"
click node_ingest "https://github.com/praneyaarora/satquerryai/blob/main/backend/orchestrator/ingest_graph.py"
click node_state "https://github.com/praneyaarora/satquerryai/blob/main/backend/orchestrator/state.py"
click node_query_graph "https://github.com/praneyaarora/satquerryai/blob/main/backend/orchestrator/graph.py"
click node_planner "https://github.com/praneyaarora/satquerryai/blob/main/backend/orchestrator/llm.py"
click node_registry "https://github.com/praneyaarora/satquerryai/blob/main/backend/orchestrator/registry.py"
click node_executor "https://github.com/praneyaarora/satquerryai/blob/main/backend/tools/executor.py"
click node_mcp "https://github.com/praneyaarora/satquerryai/blob/main/satquery_server.py"
click node_workflows "https://github.com/praneyaarora/satquerryai/blob/main/satquery_workflows.py"
click node_optical "https://github.com/praneyaarora/satquerryai/blob/main/Tool_1_fetch_optical_imagery/fetch_optical_imagery.py"
click node_multispectral "https://github.com/praneyaarora/satquerryai/blob/main/Tool_2_fetch_multispectral_imagery/fetch_multispectral_imagery.py"
click node_sar "https://github.com/praneyaarora/satquerryai/blob/main/Tool_3_fetch_sar_imagery/fetch_sar_imagery.py"
click node_weather "https://github.com/praneyaarora/satquerryai/blob/main/Tool_4_fetch_weather_environment/fetch_weather_environment.py"
click node_indices "https://github.com/praneyaarora/satquerryai/blob/main/Tool_5_compute_vegetation_indices/compute_vegetation_indices.py"
click node_metadata "https://github.com/praneyaarora/satquerryai/blob/main/Tool_6_inspect_geotiff_metadata/inspect_geotiff_metadata.py"
click node_temporal "https://github.com/praneyaarora/satquerryai/blob/main/Tool_7_analyze_temporal_change/analyze_temporal_change.py"
click node_landcover "https://github.com/praneyaarora/satquerryai/blob/main/Tool_8_analyze_spatial_landcover_terrain/analyze_spatial_landcover_terrain.py"
click node_webintel "https://github.com/praneyaarora/satquerryai/blob/main/Tool_9_fetch_web_intelligence/fetch_web_intelligence.py"
click node_geocoding "https://github.com/praneyaarora/satquerryai/blob/main/Tool_10_spatial_geocoding_poi/spatial_geocoding_poi.py"
click node_affine "https://github.com/praneyaarora/satquerryai/blob/main/Tool_11_deterministic_affine_markup/deterministic_affine_markup.py"
click node_preview "https://github.com/praneyaarora/satquerryai/blob/main/backend/rendering/raster_preview.py"
click node_vision_tool "https://github.com/praneyaarora/satquerryai/tree/main/backend/vision"
click node_local_vlm "https://github.com/praneyaarora/satquerryai/blob/main/local_model_server/server.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_web,node_mcp,node_answers,node_user toneBlue
class node_rest,node_query_route,node_upload_route,node_raster_route,node_ingest toneAmber
class node_state,node_query_graph,node_planner,node_registry,node_executor toneMint
class node_workflows,node_optical,node_multispectral,node_sar,node_weather,node_indices,node_metadata,node_temporal,node_landcover,node_webintel,node_geocoding,node_affine toneRose
class node_preview,node_vision_tool,node_local_vlm toneIndigo
```

## Components

### User interfaces

- [React chat UI](https://github.com/praneyaarora/satquerryai/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [MCP tool server](https://github.com/praneyaarora/satquerryai/blob/main/satquery_server.py): `satquery_server.py`
- **Results and artifacts**

### API and ingestion

- [FastAPI app](https://github.com/praneyaarora/satquerryai/blob/main/backend/main.py): `backend/main.py`
- [Query routes](https://github.com/praneyaarora/satquerryai/blob/main/backend/api/routes/query.py): `backend/api/routes/query.py`
- [Raster upload](https://github.com/praneyaarora/satquerryai/blob/main/backend/api/routes/uploads.py): `backend/api/routes/uploads.py`
- [Raster preview routes](https://github.com/praneyaarora/satquerryai/blob/main/backend/api/routes/rasters.py): `backend/api/routes/rasters.py`
- [Raster ingestion](https://github.com/praneyaarora/satquerryai/blob/main/backend/orchestrator/ingest_graph.py): `backend/orchestrator/ingest_graph.py`

### Planning and execution

- [Query state](https://github.com/praneyaarora/satquerryai/blob/main/backend/orchestrator/state.py): `backend/orchestrator/state.py`
- [Query orchestration](https://github.com/praneyaarora/satquerryai/blob/main/backend/orchestrator/graph.py): `backend/orchestrator/graph.py`
- [LLM planning](https://github.com/praneyaarora/satquerryai/blob/main/backend/orchestrator/llm.py): `backend/orchestrator/llm.py`
- [Tool registry](https://github.com/praneyaarora/satquerryai/blob/main/backend/orchestrator/registry.py): `backend/orchestrator/registry.py`
- [Tool executor](https://github.com/praneyaarora/satquerryai/blob/main/backend/tools/executor.py): `backend/tools/executor.py`

### Earth observation tools

- [Mission workflows](https://github.com/praneyaarora/satquerryai/blob/main/satquery_workflows.py): `satquery_workflows.py`
- [Optical imagery](https://github.com/praneyaarora/satquerryai/blob/main/Tool_1_fetch_optical_imagery/fetch_optical_imagery.py): `Tool_1_fetch_optical_imagery/fetch_optical_imagery.py`
- [Multispectral imagery](https://github.com/praneyaarora/satquerryai/blob/main/Tool_2_fetch_multispectral_imagery/fetch_multispectral_imagery.py): `Tool_2_fetch_multispectral_imagery/fetch_multispectral_imagery.py`
- [SAR imagery](https://github.com/praneyaarora/satquerryai/blob/main/Tool_3_fetch_sar_imagery/fetch_sar_imagery.py): `Tool_3_fetch_sar_imagery/fetch_sar_imagery.py`
- [Weather data](https://github.com/praneyaarora/satquerryai/blob/main/Tool_4_fetch_weather_environment/fetch_weather_environment.py): `Tool_4_fetch_weather_environment/fetch_weather_environment.py`
- [Vegetation indices](https://github.com/praneyaarora/satquerryai/blob/main/Tool_5_compute_vegetation_indices/compute_vegetation_indices.py): `Tool_5_compute_vegetation_indices/compute_vegetation_indices.py`
- [GeoTIFF metadata](https://github.com/praneyaarora/satquerryai/blob/main/Tool_6_inspect_geotiff_metadata/inspect_geotiff_metadata.py): `Tool_6_inspect_geotiff_metadata/inspect_geotiff_metadata.py`
- [Temporal change](https://github.com/praneyaarora/satquerryai/blob/main/Tool_7_analyze_temporal_change/analyze_temporal_change.py): `Tool_7_analyze_temporal_change/analyze_temporal_change.py`
- [Landcover terrain](https://github.com/praneyaarora/satquerryai/blob/main/Tool_8_analyze_spatial_landcover_terrain/analyze_spatial_landcover_terrain.py): `Tool_8_analyze_spatial_landcover_terrain/analyze_spatial_landcover_terrain.py`
- [Web intelligence](https://github.com/praneyaarora/satquerryai/blob/main/Tool_9_fetch_web_intelligence/fetch_web_intelligence.py): `Tool_9_fetch_web_intelligence/fetch_web_intelligence.py`
- [Geocoding and POI](https://github.com/praneyaarora/satquerryai/blob/main/Tool_10_spatial_geocoding_poi/spatial_geocoding_poi.py): `Tool_10_spatial_geocoding_poi/spatial_geocoding_poi.py`
- [Affine markup](https://github.com/praneyaarora/satquerryai/blob/main/Tool_11_deterministic_affine_markup/deterministic_affine_markup.py): `Tool_11_deterministic_affine_markup/deterministic_affine_markup.py`

### Vision and rendering

- [Raster rendering](https://github.com/praneyaarora/satquerryai/blob/main/backend/rendering/raster_preview.py): `backend/rendering/raster_preview.py`
- [Vision providers](https://github.com/praneyaarora/satquerryai/tree/main/backend/vision): `backend/vision`
- [Local model service](https://github.com/praneyaarora/satquerryai/blob/main/local_model_server/server.py): `local_model_server/server.py`

### Other components

- **User**

## Connections

- User → React chat UI: asks or uploads
- React chat UI → FastAPI app: HTTP requests
- FastAPI app → Query routes: mounts routes (evidence: `backend/main.py`)
- FastAPI app → Raster upload: mounts routes (evidence: `backend/main.py`)
- FastAPI app → Raster preview routes: mounts routes (evidence: `backend/main.py`)
- Query routes → Query orchestration: runs query (evidence: `backend/api/routes/query.py`)
- Raster upload → Raster ingestion: runs ingestion (evidence: `backend/api/routes/uploads.py`)
- Raster ingestion → Tool executor: executes metadata and geocode tools (evidence: `backend/orchestrator/ingest_graph.py`)
- Raster ingestion → GeoTIFF metadata: validates raster (evidence: `backend/orchestrator/ingest_graph.py`)
- Query routes → Query state: uses query state (evidence: `backend/api/routes/query.py`)
- Query orchestration → Query state: shares state (evidence: `backend/orchestrator/graph.py`)
- Query orchestration → LLM planning: plans requests (evidence: `backend/orchestrator/graph.py`)
- Query orchestration → Tool registry: loads tool registry (evidence: `backend/orchestrator/graph.py`)
- Tool executor → Tool registry: resolves tools (evidence: `backend/tools/executor.py`)
- Query orchestration → Tool executor: dispatches tools
- Tool executor → Optical imagery: calls (evidence: `backend/tools/executor.py`)
- Tool executor → Multispectral imagery: calls (evidence: `backend/tools/executor.py`)
- Tool executor → SAR imagery: calls (evidence: `backend/tools/executor.py`)
- Tool executor → Weather data: calls (evidence: `backend/tools/executor.py`)
- Tool executor → Vegetation indices: calls (evidence: `backend/tools/executor.py`)
- Tool executor → GeoTIFF metadata: calls (evidence: `backend/tools/executor.py`)
- Tool executor → Temporal change: calls (evidence: `backend/tools/executor.py`)
- Tool executor → Landcover terrain: calls (evidence: `backend/tools/executor.py`)
- Tool executor → Web intelligence: calls (evidence: `backend/tools/executor.py`)
- Tool executor → Geocoding and POI: calls (evidence: `backend/tools/executor.py`)
- Tool executor → Affine markup: calls (evidence: `backend/tools/executor.py`)
- Tool executor → Mission workflows: dispatches missions (evidence: `backend/tools/executor.py`)
- MCP tool server → Optical imagery: exposes tools (evidence: `satquery_server.py`)
- MCP tool server → Multispectral imagery: exposes tools (evidence: `satquery_server.py`)
- MCP tool server → SAR imagery: exposes tools (evidence: `satquery_server.py`)
- MCP tool server → Weather data: exposes tools (evidence: `satquery_server.py`)
- MCP tool server → Vegetation indices: exposes tools (evidence: `satquery_server.py`)
- MCP tool server → GeoTIFF metadata: exposes tools (evidence: `satquery_server.py`)
- MCP tool server → Temporal change: exposes tools (evidence: `satquery_server.py`)
- MCP tool server → Landcover terrain: exposes tools (evidence: `satquery_server.py`)
- MCP tool server → Web intelligence: exposes tools (evidence: `satquery_server.py`)
- MCP tool server → Geocoding and POI: exposes tools (evidence: `satquery_server.py`)
- MCP tool server → Affine markup: exposes tools (evidence: `satquery_server.py`)
- Raster preview routes → Raster rendering: renders preview (evidence: `backend/api/routes/rasters.py`)
- Tool executor → Raster rendering: renders vision input (evidence: `backend/rendering/raster_preview.py`)
- Raster rendering → Affine markup: uses markup engine (evidence: `backend/rendering/raster_preview.py`)
- Tool executor → Vision providers: invokes vision (evidence: `backend/tools/executor.py`)
- Vision providers → Local model service: optional local inference
- Query routes → Results and artifacts: returns query results (evidence: `backend/api/routes/query.py`)
- React chat UI → Results and artifacts: shows results
