# xdzy-td/satquery-ai architecture

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

- Interactive diagram: https://gitdiagram.com/xdzy-td/satquery-ai
- Repository: https://github.com/xdzy-td/satquery-ai

## Overview

Aetheris is an agentic remote-sensing analysis service. Its main workflow accepts a question and imagery through the HTTP interface, plans and validates specialist-tool calls, executes them, and returns an answer with evidence, confidence, and an audit trail. A second, separately exposed SAT-OS workflow wraps the core pipeline with answerability, verification, certification, reporting, and run records. The M01–M20 pipeline provides an additional hardening and imagery-processing path. Unsampled modules are represented by their existing directories; edges are limited to documented or excerpt-supported relationships.

Main entry points: [`controller/planner.py`](https://github.com/xdzy-td/satquery-ai/blob/main/controller/planner.py) (Agentic planner), [`pipeline/services/sat_pipeline.py`](https://github.com/xdzy-td/satquery-ai/blob/main/pipeline/services/sat_pipeline.py) (SAT-OS pipeline), [`pipeline/services/pipeline.py`](https://github.com/xdzy-td/satquery-ai/blob/main/pipeline/services/pipeline.py) (Aetheris pipeline), [`interfaces/api/sat_routes.py`](https://github.com/xdzy-td/satquery-ai/blob/main/interfaces/api/sat_routes.py) (SAT-OS routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interfaces"]
  node_http["FastAPI service<br/>[app.py]"]
  node_sat_api["SAT-OS routes<br/>[sat_routes.py]"]
  node_console["Text console<br/>[console.py]"]
  node_voice["Voice I/O"]
  node_pipeline_api["Pipeline GUI<br/>[app.py]"]
end

subgraph group_agent["Agentic controller"]
  node_planner["Agentic planner<br/>[planner.py]"]
  node_llm_planner["LLM planner<br/>[llm_planner.py]"]
  node_policy["Policy and contracts<br/>[policy.py]"]
  node_executor["Plan executor<br/>[executor.py]"]
  node_tool_registry["Tool registry<br/>[tool_registry.py]"]
  node_memory[("Routing memory<br/>[memory.py]")]
  node_audit[("Audit trail<br/>[audit_log.py]")]
  node_artifacts[("Artifact store<br/>[artifacts.py]")]
  node_confidence["Confidence scoring"]
  node_model_registry[("Model registry<br/>[model_registry.py]")]
end

subgraph group_analysis["Imagery analysis"]
  node_specialists["Specialist tools"]
  node_imagery["Imagery and raster I/O<br/>[_imagery.py]"]
  node_preprocessing["Image preprocessing"]
  node_geo_rag[("Geo-RAG indexing<br/>[indexer.py]")]
end

subgraph group_pipeline["Pipeline services"]
  node_pipeline_service["Aetheris pipeline<br/>[pipeline.py]"]
  node_pipeline_contracts["Result contracts<br/>[contracts.py]"]
  node_pipeline_modules["M01–M20 modules"]
  node_dag["DAG visualization<br/>[orchestrator.py]"]
end

subgraph group_sat["SAT-OS assurance"]
  node_sat_service["SAT-OS pipeline<br/>[sat_pipeline.py]"]
  node_sat_stages["SAT assurance stages"]
  node_sat_schemas["SAT schemas<br/>[sat_schemas.py]"]
end

node_user(("Analyst"))
node_ollama["Ollama service"]

node_user -->|"submits query"| node_http
node_http -->|"routes requests"| node_planner
node_user -->|"submits query"| node_console
node_console -->|"shares controller wiring"| node_planner
node_user -->|"submits SAT query"| node_sat_api
node_sat_api -->|"invokes pipeline"| node_sat_service
node_planner -->|"validates plan"| node_policy
node_planner -->|"executes plan"| node_executor
node_planner -->|"requests planning"| node_llm_planner
node_llm_planner -->|"requests plan"| node_ollama
node_planner -->|"resolves tools"| node_tool_registry
node_planner -->|"uses routing memory"| node_memory
node_planner -->|"records execution"| node_audit
node_planner -->|"scores confidence"| node_confidence
node_planner -->|"identifies models"| node_model_registry
node_executor -->|"dispatches tools"| node_specialists
node_specialists -->|"uses imagery utilities"| node_imagery
node_imagery -.->|"prepares imagery"| node_preprocessing
node_specialists -.->|"includes retrieval"| node_geo_rag
node_user -->|"submits imagery"| node_pipeline_api
node_pipeline_api -->|"runs analysis"| node_pipeline_service
node_pipeline_service -->|"runs modules"| node_pipeline_modules
node_pipeline_service -->|"returns contracts"| node_pipeline_contracts
node_pipeline_api -.->|"offers DAG view"| node_dag
node_sat_service -->|"runs inner pipeline"| node_pipeline_service
node_sat_service -->|"performs assurance"| node_sat_stages
node_sat_service -->|"builds typed records"| node_sat_schemas
node_sat_api -->|"uses request schemas"| node_sat_schemas

click node_http "https://github.com/xdzy-td/satquery-ai/blob/main/interfaces/api/app.py"
click node_sat_api "https://github.com/xdzy-td/satquery-ai/blob/main/interfaces/api/sat_routes.py"
click node_console "https://github.com/xdzy-td/satquery-ai/blob/main/interfaces/ui/console.py"
click node_voice "https://github.com/xdzy-td/satquery-ai/tree/main/interfaces/voice"
click node_planner "https://github.com/xdzy-td/satquery-ai/blob/main/controller/planner.py"
click node_llm_planner "https://github.com/xdzy-td/satquery-ai/blob/main/controller/llm_planner.py"
click node_policy "https://github.com/xdzy-td/satquery-ai/blob/main/controller/policy.py"
click node_executor "https://github.com/xdzy-td/satquery-ai/blob/main/controller/executor.py"
click node_tool_registry "https://github.com/xdzy-td/satquery-ai/blob/main/controller/tool_registry.py"
click node_memory "https://github.com/xdzy-td/satquery-ai/blob/main/controller/memory.py"
click node_audit "https://github.com/xdzy-td/satquery-ai/blob/main/controller/audit_log.py"
click node_artifacts "https://github.com/xdzy-td/satquery-ai/blob/main/controller/artifacts.py"
click node_confidence "https://github.com/xdzy-td/satquery-ai/tree/main/confidence"
click node_model_registry "https://github.com/xdzy-td/satquery-ai/blob/main/controller/model_registry.py"
click node_specialists "https://github.com/xdzy-td/satquery-ai/tree/main/specialists"
click node_imagery "https://github.com/xdzy-td/satquery-ai/blob/main/specialists/_imagery.py"
click node_preprocessing "https://github.com/xdzy-td/satquery-ai/tree/main/preprocessing"
click node_geo_rag "https://github.com/xdzy-td/satquery-ai/blob/main/specialists/geo_rag/indexer.py"
click node_pipeline_api "https://github.com/xdzy-td/satquery-ai/blob/main/pipeline/gui/app.py"
click node_pipeline_service "https://github.com/xdzy-td/satquery-ai/blob/main/pipeline/services/pipeline.py"
click node_pipeline_contracts "https://github.com/xdzy-td/satquery-ai/blob/main/pipeline/schemas/contracts.py"
click node_pipeline_modules "https://github.com/xdzy-td/satquery-ai/tree/main/pipeline/modules"
click node_dag "https://github.com/xdzy-td/satquery-ai/blob/main/pipeline/services/orchestrator.py"
click node_sat_service "https://github.com/xdzy-td/satquery-ai/blob/main/pipeline/services/sat_pipeline.py"
click node_sat_stages "https://github.com/xdzy-td/satquery-ai/tree/main/pipeline/modules"
click node_sat_schemas "https://github.com/xdzy-td/satquery-ai/blob/main/pipeline/schemas/sat_schemas.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_http,node_sat_api,node_console,node_voice,node_pipeline_api toneBlue
class node_planner,node_llm_planner,node_policy,node_executor,node_tool_registry,node_memory,node_audit,node_artifacts,node_confidence,node_model_registry toneAmber
class node_specialists,node_imagery,node_preprocessing,node_geo_rag toneMint
class node_pipeline_service,node_pipeline_contracts,node_pipeline_modules,node_dag toneRose
class node_sat_service,node_sat_stages,node_sat_schemas,node_user,node_ollama toneIndigo
```

## Components

### User interfaces

- [FastAPI service](https://github.com/xdzy-td/satquery-ai/blob/main/interfaces/api/app.py): `interfaces/api/app.py`
- [SAT-OS routes](https://github.com/xdzy-td/satquery-ai/blob/main/interfaces/api/sat_routes.py): `interfaces/api/sat_routes.py`
- [Text console](https://github.com/xdzy-td/satquery-ai/blob/main/interfaces/ui/console.py): `interfaces/ui/console.py`
- [Voice I/O](https://github.com/xdzy-td/satquery-ai/tree/main/interfaces/voice): `interfaces/voice`
- [Pipeline GUI](https://github.com/xdzy-td/satquery-ai/blob/main/pipeline/gui/app.py): `pipeline/gui/app.py`

### Agentic controller

- [Agentic planner](https://github.com/xdzy-td/satquery-ai/blob/main/controller/planner.py): `controller/planner.py`
- [LLM planner](https://github.com/xdzy-td/satquery-ai/blob/main/controller/llm_planner.py): `controller/llm_planner.py`
- [Policy and contracts](https://github.com/xdzy-td/satquery-ai/blob/main/controller/policy.py): `controller/policy.py`
- [Plan executor](https://github.com/xdzy-td/satquery-ai/blob/main/controller/executor.py): `controller/executor.py`
- [Tool registry](https://github.com/xdzy-td/satquery-ai/blob/main/controller/tool_registry.py): `controller/tool_registry.py`
- [Routing memory](https://github.com/xdzy-td/satquery-ai/blob/main/controller/memory.py): `controller/memory.py`
- [Audit trail](https://github.com/xdzy-td/satquery-ai/blob/main/controller/audit_log.py): `controller/audit_log.py`
- [Artifact store](https://github.com/xdzy-td/satquery-ai/blob/main/controller/artifacts.py): `controller/artifacts.py`
- [Confidence scoring](https://github.com/xdzy-td/satquery-ai/tree/main/confidence): `confidence`
- [Model registry](https://github.com/xdzy-td/satquery-ai/blob/main/controller/model_registry.py): `controller/model_registry.py`

### Imagery analysis

- [Specialist tools](https://github.com/xdzy-td/satquery-ai/tree/main/specialists): `specialists`
- [Imagery and raster I/O](https://github.com/xdzy-td/satquery-ai/blob/main/specialists/_imagery.py): `specialists/_imagery.py`
- [Image preprocessing](https://github.com/xdzy-td/satquery-ai/tree/main/preprocessing): `preprocessing`
- [Geo-RAG indexing](https://github.com/xdzy-td/satquery-ai/blob/main/specialists/geo_rag/indexer.py): `specialists/geo_rag/indexer.py`

### Pipeline services

- [Aetheris pipeline](https://github.com/xdzy-td/satquery-ai/blob/main/pipeline/services/pipeline.py): `pipeline/services/pipeline.py`
- [Result contracts](https://github.com/xdzy-td/satquery-ai/blob/main/pipeline/schemas/contracts.py): `pipeline/schemas/contracts.py`
- [M01–M20 modules](https://github.com/xdzy-td/satquery-ai/tree/main/pipeline/modules): `pipeline/modules`
- [DAG visualization](https://github.com/xdzy-td/satquery-ai/blob/main/pipeline/services/orchestrator.py): `pipeline/services/orchestrator.py`

### SAT-OS assurance

- [SAT-OS pipeline](https://github.com/xdzy-td/satquery-ai/blob/main/pipeline/services/sat_pipeline.py): `pipeline/services/sat_pipeline.py`
- [SAT assurance stages](https://github.com/xdzy-td/satquery-ai/tree/main/pipeline/modules): `pipeline/modules`
- [SAT schemas](https://github.com/xdzy-td/satquery-ai/blob/main/pipeline/schemas/sat_schemas.py): `pipeline/schemas/sat_schemas.py`

### Other components

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

## Connections

- Analyst → FastAPI service: submits query (evidence: `README.md`)
- FastAPI service → Agentic planner: routes requests (evidence: `interfaces/api/app.py`)
- Analyst → Text console: submits query (evidence: `README.md`)
- Text console → Agentic planner: shares controller wiring
- Analyst → SAT-OS routes: submits SAT query (evidence: `interfaces/api/sat_routes.py`)
- SAT-OS routes → SAT-OS pipeline: invokes pipeline (evidence: `interfaces/api/sat_routes.py`)
- Agentic planner → Policy and contracts: validates plan (evidence: `README.md`)
- Agentic planner → Plan executor: executes plan (evidence: `README.md`)
- Agentic planner → LLM planner: requests planning (evidence: `controller/planner.py`)
- LLM planner → Ollama service: requests plan
- Agentic planner → Tool registry: resolves tools (evidence: `controller/planner.py`)
- Agentic planner → Routing memory: uses routing memory (evidence: `controller/planner.py`)
- Agentic planner → Audit trail: records execution (evidence: `controller/planner.py`)
- Agentic planner → Confidence scoring: scores confidence (evidence: `controller/planner.py`)
- Agentic planner → Model registry: identifies models (evidence: `controller/planner.py`)
- Plan executor → Specialist tools: dispatches tools (evidence: `README.md`)
- Specialist tools → Imagery and raster I/O: uses imagery utilities (evidence: `specialists/change_detection/model.py`)
- Imagery and raster I/O → Image preprocessing: prepares imagery
- Specialist tools → Geo-RAG indexing: includes retrieval
- Analyst → Pipeline GUI: submits imagery (evidence: `pipeline/gui/app.py`)
- Pipeline GUI → Aetheris pipeline: runs analysis (evidence: `pipeline/gui/app.py`)
- Aetheris pipeline → M01–M20 modules: runs modules (evidence: `pipeline/services/pipeline.py`)
- Aetheris pipeline → Result contracts: returns contracts (evidence: `pipeline/services/pipeline.py`)
- Pipeline GUI → DAG visualization: offers DAG view (evidence: `pipeline/gui/app.py`)
- SAT-OS pipeline → Aetheris pipeline: runs inner pipeline (evidence: `pipeline/services/sat_pipeline.py`)
- SAT-OS pipeline → SAT assurance stages: performs assurance (evidence: `pipeline/services/sat_pipeline.py`)
- SAT-OS pipeline → SAT schemas: builds typed records (evidence: `pipeline/services/sat_pipeline.py`)
- SAT-OS routes → SAT schemas: uses request schemas (evidence: `interfaces/api/sat_routes.py`)