# anish-lab-blip/satquery-ai architecture

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

- Interactive diagram: https://gitdiagram.com/anish-lab-blip/satquery-ai
- Repository: https://github.com/anish-lab-blip/satquery-ai

## Overview

SatQuery AI accepts satellite-image questions and routes each request through an advisory intent router and deterministic policy planner to task specialists; the controller dispatches them and assembles a confidence-scored result with evidence and an execution trace. Its documented capabilities include VQA and captioning, grounding, bi-temporal change detection, change-VQA, and optical-SAR fusion. The deployment tree also contains a stateless gateway and inference-serving components. Some runtime modules are unsampled, so the graph shows only documented or excerpt-supported connections and does not infer internal preprocessing or evaluation wiring.

Main entry points: [`core/registry.py`](https://github.com/anish-lab-blip/satquery-ai/blob/main/core/registry.py) (Specialist registry), [`core/controller.py`](https://github.com/anish-lab-blip/satquery-ai/blob/main/core/controller.py) (Analysis controller), [`gateway/app.py`](https://github.com/anish-lab-blip/satquery-ai/blob/main/gateway/app.py) (API gateway), [`deploy/render/main.py`](https://github.com/anish-lab-blip/satquery-ai/blob/main/deploy/render/main.py) (Render proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and deployment"]
  node_gateway["API gateway<br/>[app.py]"]
  node_render["Render proxy<br/>[main.py]"]
  node_codespace["Inference server<br/>[serve.py]"]
  node_serving["Serving adapters<br/>[serving.py]"]
end

subgraph group_control["Request orchestration"]
  node_controller["Analysis controller<br/>[controller.py]"]
  node_router["Intent router<br/>[classifier.py]"]
  node_planner["Policy planner<br/>[planner.py]"]
  node_registry["Specialist registry<br/>[registry.py]"]
end

subgraph group_specialists["Task specialists"]
  node_vqa["VQA and caption<br/>[inference.py]"]
  node_grounding["Visual grounding<br/>[specialist.py]"]
  node_change["Change detection<br/>[specialist.py]"]
  node_changevqa["Change-VQA<br/>[vqa_specialist.py]"]
  node_opticalsar["Optical-SAR fusion<br/>[specialist.py]"]
end

subgraph group_shared["Shared capabilities"]
  node_preprocess["Image preparation<br/>[imagery.py]"]
  node_geospatial["Geospatial transforms<br/>[transform.py]"]
  node_evidence["Evidence aggregation<br/>[engine.py]"]
  node_confidence["Confidence calibration<br/>[confidence.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluation["Benchmark evaluation<br/>[runner.py]"]
end

node_user(("Questioner"))
node_frontend["Static frontend"]

node_user -->|"asks"| node_frontend
node_frontend -->|"sends request"| node_gateway
node_gateway -.->|"proxies request"| node_render
node_render -.->|"forwards inference"| node_codespace
node_codespace -->|"serves request"| node_serving
node_serving -->|"runs analysis"| node_controller
node_controller -->|"requests intent"| node_router
node_controller -->|"requests plan"| node_planner
node_planner -->|"selects specialists"| node_registry
node_controller -->|"dispatches plan"| node_registry
node_registry -->|"constructs"| node_vqa
node_registry -->|"constructs"| node_grounding
node_registry -->|"constructs"| node_change
node_registry -->|"constructs"| node_changevqa
node_registry -->|"constructs"| node_opticalsar
node_controller -->|"aggregates results"| node_evidence
node_evidence -->|"calibrates scores"| node_confidence
node_controller -->|"returns envelope"| node_frontend

click node_gateway "https://github.com/anish-lab-blip/satquery-ai/blob/main/gateway/app.py"
click node_render "https://github.com/anish-lab-blip/satquery-ai/blob/main/deploy/render/main.py"
click node_codespace "https://github.com/anish-lab-blip/satquery-ai/blob/main/deploy/codespace/serve.py"
click node_serving "https://github.com/anish-lab-blip/satquery-ai/blob/main/app/serving.py"
click node_controller "https://github.com/anish-lab-blip/satquery-ai/blob/main/core/controller.py"
click node_router "https://github.com/anish-lab-blip/satquery-ai/blob/main/router/classifier.py"
click node_planner "https://github.com/anish-lab-blip/satquery-ai/blob/main/core/planner.py"
click node_registry "https://github.com/anish-lab-blip/satquery-ai/blob/main/core/registry.py"
click node_vqa "https://github.com/anish-lab-blip/satquery-ai/blob/main/specialists/vqa/inference.py"
click node_grounding "https://github.com/anish-lab-blip/satquery-ai/blob/main/specialists/grounding/specialist.py"
click node_change "https://github.com/anish-lab-blip/satquery-ai/blob/main/specialists/change/specialist.py"
click node_changevqa "https://github.com/anish-lab-blip/satquery-ai/blob/main/specialists/change/vqa_specialist.py"
click node_opticalsar "https://github.com/anish-lab-blip/satquery-ai/blob/main/specialists/optical_sar/specialist.py"
click node_preprocess "https://github.com/anish-lab-blip/satquery-ai/blob/main/preprocessing/imagery.py"
click node_geospatial "https://github.com/anish-lab-blip/satquery-ai/blob/main/geospatial/transform.py"
click node_evidence "https://github.com/anish-lab-blip/satquery-ai/blob/main/evidence/engine.py"
click node_confidence "https://github.com/anish-lab-blip/satquery-ai/blob/main/evidence/confidence.py"
click node_evaluation "https://github.com/anish-lab-blip/satquery-ai/blob/main/evaluation/runner.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_gateway,node_render,node_codespace,node_serving,node_frontend toneBlue
class node_controller,node_router,node_planner,node_registry toneAmber
class node_vqa,node_grounding,node_change,node_changevqa,node_opticalsar toneMint
class node_preprocess,node_geospatial,node_evidence,node_confidence toneRose
class node_evaluation,node_user toneIndigo
```

## Components

### API and deployment

- [API gateway](https://github.com/anish-lab-blip/satquery-ai/blob/main/gateway/app.py): `gateway/app.py`
- [Render proxy](https://github.com/anish-lab-blip/satquery-ai/blob/main/deploy/render/main.py): `deploy/render/main.py`
- [Inference server](https://github.com/anish-lab-blip/satquery-ai/blob/main/deploy/codespace/serve.py): `deploy/codespace/serve.py`
- [Serving adapters](https://github.com/anish-lab-blip/satquery-ai/blob/main/app/serving.py): `app/serving.py`

### Request orchestration

- [Analysis controller](https://github.com/anish-lab-blip/satquery-ai/blob/main/core/controller.py): `core/controller.py`
- [Intent router](https://github.com/anish-lab-blip/satquery-ai/blob/main/router/classifier.py): `router/classifier.py`
- [Policy planner](https://github.com/anish-lab-blip/satquery-ai/blob/main/core/planner.py): `core/planner.py`
- [Specialist registry](https://github.com/anish-lab-blip/satquery-ai/blob/main/core/registry.py): `core/registry.py`

### Task specialists

- [VQA and caption](https://github.com/anish-lab-blip/satquery-ai/blob/main/specialists/vqa/inference.py): `specialists/vqa/inference.py`
- [Visual grounding](https://github.com/anish-lab-blip/satquery-ai/blob/main/specialists/grounding/specialist.py): `specialists/grounding/specialist.py`
- [Change detection](https://github.com/anish-lab-blip/satquery-ai/blob/main/specialists/change/specialist.py): `specialists/change/specialist.py`
- [Change-VQA](https://github.com/anish-lab-blip/satquery-ai/blob/main/specialists/change/vqa_specialist.py): `specialists/change/vqa_specialist.py`
- [Optical-SAR fusion](https://github.com/anish-lab-blip/satquery-ai/blob/main/specialists/optical_sar/specialist.py): `specialists/optical_sar/specialist.py`

### Shared capabilities

- [Image preparation](https://github.com/anish-lab-blip/satquery-ai/blob/main/preprocessing/imagery.py): `preprocessing/imagery.py`
- [Geospatial transforms](https://github.com/anish-lab-blip/satquery-ai/blob/main/geospatial/transform.py): `geospatial/transform.py`
- [Evidence aggregation](https://github.com/anish-lab-blip/satquery-ai/blob/main/evidence/engine.py): `evidence/engine.py`
- [Confidence calibration](https://github.com/anish-lab-blip/satquery-ai/blob/main/evidence/confidence.py): `evidence/confidence.py`

### Evaluation

- [Benchmark evaluation](https://github.com/anish-lab-blip/satquery-ai/blob/main/evaluation/runner.py): `evaluation/runner.py`

### Other components

- **Questioner**
- **Static frontend**

## Connections

- Questioner → Static frontend: asks
- Static frontend → API gateway: sends request
- API gateway → Render proxy: proxies request
- Render proxy → Inference server: forwards inference
- Inference server → Serving adapters: serves request
- Serving adapters → Analysis controller: runs analysis
- Analysis controller → Intent router: requests intent
- Analysis controller → Policy planner: requests plan
- Policy planner → Specialist registry: selects specialists
- Analysis controller → Specialist registry: dispatches plan
- Specialist registry → VQA and caption: constructs
- Specialist registry → Visual grounding: constructs
- Specialist registry → Change detection: constructs
- Specialist registry → Change-VQA: constructs
- Specialist registry → Optical-SAR fusion: constructs
- Analysis controller → Evidence aggregation: aggregates results
- Evidence aggregation → Confidence calibration: calibrates scores
- Analysis controller → Static frontend: returns envelope