# kd4r/satquery architecture

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

- Interactive diagram: https://gitdiagram.com/kd4r/satquery
- Repository: https://github.com/kd4r/satquery

## Overview

SatQuery AI is a natural-language satellite intelligence platform. A user submits a mission query in the web app; the agent plans the analysis, arbitrates sensors, searches EO catalogues, obtains observations, calls inference, and produces confidence and evidence for a synthesized result. Mission/AOI lifecycle and asynchronous geospatial processing are adjacent product capabilities. The sampled orchestrator and service excerpts support the main analysis links; unsampled gateway and mission wiring is left unspecified.

Main entry points: [`services/agent/graph/orchestrator.py`](https://github.com/kd4r/satquery/blob/main/services/agent/graph/orchestrator.py) (Run orchestrator), [`services/agent/app/api/implementation.py`](https://github.com/kd4r/satquery/blob/main/services/agent/app/api/implementation.py) (Agent API), [`services/gateway/implementation.py`](https://github.com/kd4r/satquery/blob/main/services/gateway/implementation.py) (API gateway), [`apps/web/components/Dashboard.tsx`](https://github.com/kd4r/satquery/blob/main/apps/web/components/Dashboard.tsx) (Web dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_web["Web dashboard<br/>[Dashboard.tsx]"]
  node_query["Query console<br/>[QueryConsole.tsx]"]
  node_results["Analysis views<br/>[EvidencePanel.tsx]"]
end

subgraph group_mission["Mission and access"]
  node_gateway["API gateway<br/>[implementation.py]"]
  node_mission_api["Mission API<br/>[implementation.py]"]
  node_mission_store[("Mission database<br/>[database.py]")]
end

subgraph group_agent["Agent analysis"]
  node_agent_api["Agent API<br/>[implementation.py]"]
  node_orchestrator["Run orchestrator<br/>[orchestrator.py]"]
  node_intent["Intent extraction"]
  node_sensor["Sensor arbitration"]
  node_acquisition["Acquisition loop"]
  node_tool_executor["Tool execution<br/>[executor.py]"]
  node_stac_tool["STAC search tool<br/>[stac_search.py]"]
  node_confidence["Confidence gate<br/>[confidence_gate.py]"]
  node_evidence["Evidence graph<br/>[graph_builder.py]"]
  node_synthesis["Result synthesis<br/>[synthesizer.py]"]
end

subgraph group_earth_data["Earth observation"]
  node_eo_search["Observation search<br/>[search.py]"]
  node_providers["EO providers"]
end

subgraph group_analysis["Inference and geospatial"]
  node_inference_api["Inference API<br/>[inference.py]"]
  node_analysis_service["Analysis service<br/>[service.py]"]
  node_ml_pipeline["Water analysis"]
  node_geo_api["Geo processing API<br/>[api.py]"]
  node_geo_worker["Geo job worker<br/>[worker.py]"]
end

node_user(("Analyst"))
node_redis[("Redis broker/cache")]
node_satellite_catalogues(("Satellite catalogues"))

node_user -->|"uses"| node_web
node_web -->|"shows"| node_query
node_query -->|"submits query"| node_gateway
node_gateway -->|"routes request"| node_agent_api
node_gateway -->|"routes lifecycle"| node_mission_api
node_mission_api -->|"reads/writes"| node_mission_store
node_agent_api -->|"starts run"| node_orchestrator
node_orchestrator -->|"extracts intent"| node_intent
node_orchestrator -->|"arbitrates sensors"| node_sensor
node_orchestrator -->|"acquires data"| node_acquisition
node_acquisition -->|"executes tools"| node_tool_executor
node_tool_executor -->|"dispatches"| node_stac_tool
node_stac_tool -->|"searches observations"| node_eo_search
node_eo_search -->|"queries provider"| node_providers
node_providers -.->|"searches"| node_satellite_catalogues
node_orchestrator -->|"requests analysis"| node_inference_api
node_inference_api -->|"runs analysis"| node_analysis_service
node_analysis_service -->|"runs method"| node_ml_pipeline
node_orchestrator -->|"evaluates confidence"| node_confidence
node_orchestrator -->|"builds evidence"| node_evidence
node_orchestrator -->|"synthesizes outcome"| node_synthesis
node_synthesis -->|"returns result"| node_agent_api
node_agent_api -->|"returns analysis"| node_results
node_geo_api -->|"dispatches job"| node_geo_worker
node_geo_worker -->|"tracks idempotency"| node_redis

click node_web "https://github.com/kd4r/satquery/blob/main/apps/web/components/Dashboard.tsx"
click node_query "https://github.com/kd4r/satquery/blob/main/apps/web/components/QueryConsole.tsx"
click node_results "https://github.com/kd4r/satquery/blob/main/apps/web/components/EvidencePanel.tsx"
click node_gateway "https://github.com/kd4r/satquery/blob/main/services/gateway/implementation.py"
click node_mission_api "https://github.com/kd4r/satquery/blob/main/services/mission/implementation.py"
click node_mission_store "https://github.com/kd4r/satquery/blob/main/services/mission/database.py"
click node_agent_api "https://github.com/kd4r/satquery/blob/main/services/agent/app/api/implementation.py"
click node_orchestrator "https://github.com/kd4r/satquery/blob/main/services/agent/graph/orchestrator.py"
click node_intent "https://github.com/kd4r/satquery/blob/main/services/agent/nodes/intent_extractor.py"
click node_sensor "https://github.com/kd4r/satquery/blob/main/services/agent/nodes/sensor_arbitrator.py"
click node_acquisition "https://github.com/kd4r/satquery/blob/main/services/agent/graph/acquisition_loop.py"
click node_tool_executor "https://github.com/kd4r/satquery/blob/main/services/agent/tools/executor.py"
click node_stac_tool "https://github.com/kd4r/satquery/blob/main/services/agent/tools/stac_search.py"
click node_eo_search "https://github.com/kd4r/satquery/blob/main/services/eo-data/search.py"
click node_providers "https://github.com/kd4r/satquery/tree/main/packages/providers"
click node_inference_api "https://github.com/kd4r/satquery/blob/main/services/inference/routers/inference.py"
click node_analysis_service "https://github.com/kd4r/satquery/blob/main/services/inference/service.py"
click node_ml_pipeline "https://github.com/kd4r/satquery/tree/main/ml/pipeline"
click node_confidence "https://github.com/kd4r/satquery/blob/main/services/agent/nodes/confidence_gate.py"
click node_evidence "https://github.com/kd4r/satquery/blob/main/services/agent/evidence/graph_builder.py"
click node_synthesis "https://github.com/kd4r/satquery/blob/main/services/agent/nodes/synthesizer.py"
click node_geo_api "https://github.com/kd4r/satquery/blob/main/services/geo/api.py"
click node_geo_worker "https://github.com/kd4r/satquery/blob/main/services/geo/worker.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_query,node_results toneBlue
class node_gateway,node_mission_api,node_mission_store,node_redis toneAmber
class node_agent_api,node_orchestrator,node_intent,node_sensor,node_acquisition,node_tool_executor,node_stac_tool,node_confidence,node_evidence,node_synthesis toneMint
class node_eo_search,node_providers toneRose
class node_inference_api,node_analysis_service,node_ml_pipeline,node_geo_api,node_geo_worker,node_user,node_satellite_catalogues toneIndigo
```

## Components

### Web experience

- [Web dashboard](https://github.com/kd4r/satquery/blob/main/apps/web/components/Dashboard.tsx): `apps/web/components/Dashboard.tsx`
- [Query console](https://github.com/kd4r/satquery/blob/main/apps/web/components/QueryConsole.tsx): `apps/web/components/QueryConsole.tsx`
- [Analysis views](https://github.com/kd4r/satquery/blob/main/apps/web/components/EvidencePanel.tsx): `apps/web/components/EvidencePanel.tsx`

### Mission and access

- [API gateway](https://github.com/kd4r/satquery/blob/main/services/gateway/implementation.py): `services/gateway/implementation.py`
- [Mission API](https://github.com/kd4r/satquery/blob/main/services/mission/implementation.py): `services/mission/implementation.py`
- [Mission database](https://github.com/kd4r/satquery/blob/main/services/mission/database.py): `services/mission/database.py`

### Agent analysis

- [Agent API](https://github.com/kd4r/satquery/blob/main/services/agent/app/api/implementation.py): `services/agent/app/api/implementation.py`
- [Run orchestrator](https://github.com/kd4r/satquery/blob/main/services/agent/graph/orchestrator.py): `services/agent/graph/orchestrator.py`
- [Intent extraction](https://github.com/kd4r/satquery/blob/main/services/agent/nodes/intent_extractor.py): `services/agent/nodes/intent_extractor.py`
- [Sensor arbitration](https://github.com/kd4r/satquery/blob/main/services/agent/nodes/sensor_arbitrator.py): `services/agent/nodes/sensor_arbitrator.py`
- [Acquisition loop](https://github.com/kd4r/satquery/blob/main/services/agent/graph/acquisition_loop.py): `services/agent/graph/acquisition_loop.py`
- [Tool execution](https://github.com/kd4r/satquery/blob/main/services/agent/tools/executor.py): `services/agent/tools/executor.py`
- [STAC search tool](https://github.com/kd4r/satquery/blob/main/services/agent/tools/stac_search.py): `services/agent/tools/stac_search.py`
- [Confidence gate](https://github.com/kd4r/satquery/blob/main/services/agent/nodes/confidence_gate.py): `services/agent/nodes/confidence_gate.py`
- [Evidence graph](https://github.com/kd4r/satquery/blob/main/services/agent/evidence/graph_builder.py): `services/agent/evidence/graph_builder.py`
- [Result synthesis](https://github.com/kd4r/satquery/blob/main/services/agent/nodes/synthesizer.py): `services/agent/nodes/synthesizer.py`

### Earth observation

- [Observation search](https://github.com/kd4r/satquery/blob/main/services/eo-data/search.py): `services/eo-data/search.py`
- [EO providers](https://github.com/kd4r/satquery/tree/main/packages/providers): `packages/providers`

### Inference and geospatial

- [Inference API](https://github.com/kd4r/satquery/blob/main/services/inference/routers/inference.py): `services/inference/routers/inference.py`
- [Analysis service](https://github.com/kd4r/satquery/blob/main/services/inference/service.py): `services/inference/service.py`
- [Water analysis](https://github.com/kd4r/satquery/tree/main/ml/pipeline): `ml/pipeline`
- [Geo processing API](https://github.com/kd4r/satquery/blob/main/services/geo/api.py): `services/geo/api.py`
- [Geo job worker](https://github.com/kd4r/satquery/blob/main/services/geo/worker.py): `services/geo/worker.py`

### Other components

- **Analyst**
- **Redis broker/cache**
- **Satellite catalogues**

## Connections

- Analyst → Web dashboard: uses
- Web dashboard → Query console: shows
- Query console → API gateway: submits query
- API gateway → Agent API: routes request
- API gateway → Mission API: routes lifecycle
- Mission API → Mission database: reads/writes
- Agent API → Run orchestrator: starts run
- Run orchestrator → Intent extraction: extracts intent
- Run orchestrator → Sensor arbitration: arbitrates sensors
- Run orchestrator → Acquisition loop: acquires data
- Acquisition loop → Tool execution: executes tools
- Tool execution → STAC search tool: dispatches
- STAC search tool → Observation search: searches observations
- Observation search → EO providers: queries provider
- EO providers → Satellite catalogues: searches
- Run orchestrator → Inference API: requests analysis
- Inference API → Analysis service: runs analysis
- Analysis service → Water analysis: runs method
- Run orchestrator → Confidence gate: evaluates confidence
- Run orchestrator → Evidence graph: builds evidence
- Run orchestrator → Result synthesis: synthesizes outcome
- Result synthesis → Agent API: returns result
- Agent API → Analysis views: returns analysis
- Geo processing API → Geo job worker: dispatches job
- Geo job worker → Redis broker/cache: tracks idempotency