# poorvajawale/northstar architecture

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

- Interactive diagram: https://gitdiagram.com/poorvajawale/northstar
- Repository: https://github.com/poorvajawale/northstar

## Overview

SatQuery AI is a conversational remote-sensing assistant: users submit satellite imagery and a natural-language question, then receive an answer with visual evidence, confidence, and an execution trace. The frontend calls the FastAPI application, which ingests images and delegates analysis to the agent controller. The controller inspects inputs, classifies intent, selects a registered specialist tool, and returns a result for reporting and display. The README documents single-image, bi-temporal, and optical–SAR capabilities; change and fusion tools may be configurable or mocked. Some internal wiring is not visible in the sampled excerpts, so uncertain links are omitted.

Main entry points: [`backend/agent/controller.py`](https://github.com/poorvajawale/northstar/blob/main/backend/agent/controller.py) (Agent controller), [`backend/agent/registry.py`](https://github.com/poorvajawale/northstar/blob/main/backend/agent/registry.py) (Tool registry), [`backend/main.py`](https://github.com/poorvajawale/northstar/blob/main/backend/main.py) (FastAPI endpoints), [`frontend/src/App.jsx`](https://github.com/poorvajawale/northstar/blob/main/frontend/src/App.jsx) (SatQuery interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User interface"]
  node_ui["SatQuery interface<br/>[App.jsx]"]
  node_app_mount["React entry<br/>[main.jsx]"]
end

subgraph group_api["API and sessions"]
  node_api_app["FastAPI endpoints<br/>[main.py]"]
  node_image_io["Image ingestion<br/>[io.py]"]
end

subgraph group_agent["Agent routing"]
  node_agent_controller["Agent controller<br/>[controller.py]"]
  node_inspection["Input inspection<br/>[inspector.py]"]
  node_intent["Query classification<br/>[intent.py]"]
  node_registry["Tool registry<br/>[registry.py]"]
end

subgraph group_analysis["Image analysis"]
  node_geochat["GeoChat analysis<br/>[geochat_tool.py]"]
  node_change["Change analysis<br/>[change_tool.py]"]
  node_optical_sar["Optical-SAR reasoning"]
  node_landcover["Land-cover analysis<br/>[landcover_tool.py]"]
  node_disaster["Disaster assessment<br/>[disaster_tool.py]"]
end

subgraph group_results["Evidence and results"]
  node_confidence["Confidence scoring<br/>[confidence.py]"]
  node_alignment["Geospatial alignment<br/>[alignment.py]"]
  node_schemas["Result schemas<br/>[schemas.py]"]
  node_report["Evidence reports<br/>[builder.py]"]
end

node_user(("Imagery analyst"))
node_service_user(("API consumer"))

node_user -->|"submits imagery"| node_ui
node_app_mount -->|"renders"| node_ui
node_ui -->|"sends queries"| node_api_app
node_api_app -->|"decodes uploads"| node_image_io
node_api_app -->|"runs analysis"| node_agent_controller
node_agent_controller -->|"inspects inputs"| node_inspection
node_agent_controller -->|"classifies query"| node_intent
node_agent_controller -->|"selects tool"| node_registry
node_registry -->|"dispatches"| node_geochat
node_registry -->|"dispatches"| node_change
node_registry -->|"dispatches"| node_optical_sar
node_registry -->|"dispatches"| node_landcover
node_registry -->|"dispatches"| node_disaster
node_agent_controller -->|"scores result"| node_confidence
node_agent_controller -->|"builds response"| node_schemas
node_api_app -->|"builds report"| node_report
node_api_app -->|"returns results"| node_ui
node_ui -->|"shows evidence"| node_service_user

click node_ui "https://github.com/poorvajawale/northstar/blob/main/frontend/src/App.jsx"
click node_app_mount "https://github.com/poorvajawale/northstar/blob/main/frontend/src/main.jsx"
click node_api_app "https://github.com/poorvajawale/northstar/blob/main/backend/main.py"
click node_image_io "https://github.com/poorvajawale/northstar/blob/main/backend/geo/io.py"
click node_agent_controller "https://github.com/poorvajawale/northstar/blob/main/backend/agent/controller.py"
click node_inspection "https://github.com/poorvajawale/northstar/blob/main/backend/agent/inspector.py"
click node_intent "https://github.com/poorvajawale/northstar/blob/main/backend/agent/intent.py"
click node_registry "https://github.com/poorvajawale/northstar/blob/main/backend/agent/registry.py"
click node_confidence "https://github.com/poorvajawale/northstar/blob/main/backend/agent/confidence.py"
click node_geochat "https://github.com/poorvajawale/northstar/blob/main/backend/tools/geochat_tool.py"
click node_change "https://github.com/poorvajawale/northstar/blob/main/backend/tools/change_tool.py"
click node_optical_sar "https://github.com/poorvajawale/northstar/blob/main/backend/tools/optical_sar_tool.py"
click node_landcover "https://github.com/poorvajawale/northstar/blob/main/backend/tools/landcover_tool.py"
click node_disaster "https://github.com/poorvajawale/northstar/blob/main/backend/tools/disaster_tool.py"
click node_alignment "https://github.com/poorvajawale/northstar/blob/main/backend/geo/alignment.py"
click node_schemas "https://github.com/poorvajawale/northstar/blob/main/backend/schemas.py"
click node_report "https://github.com/poorvajawale/northstar/blob/main/backend/report/builder.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_ui,node_app_mount toneBlue
class node_api_app,node_image_io toneAmber
class node_agent_controller,node_inspection,node_intent,node_registry,node_service_user toneMint
class node_geochat,node_change,node_optical_sar,node_landcover,node_disaster toneRose
class node_confidence,node_alignment,node_schemas,node_report,node_user toneIndigo
```

## Components

### User interface

- [SatQuery interface](https://github.com/poorvajawale/northstar/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [React entry](https://github.com/poorvajawale/northstar/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`

### API and sessions

- [FastAPI endpoints](https://github.com/poorvajawale/northstar/blob/main/backend/main.py): `backend/main.py`
- [Image ingestion](https://github.com/poorvajawale/northstar/blob/main/backend/geo/io.py): `backend/geo/io.py`

### Agent routing

- [Agent controller](https://github.com/poorvajawale/northstar/blob/main/backend/agent/controller.py): `backend/agent/controller.py`
- [Input inspection](https://github.com/poorvajawale/northstar/blob/main/backend/agent/inspector.py): `backend/agent/inspector.py`
- [Query classification](https://github.com/poorvajawale/northstar/blob/main/backend/agent/intent.py): `backend/agent/intent.py`
- [Tool registry](https://github.com/poorvajawale/northstar/blob/main/backend/agent/registry.py): `backend/agent/registry.py`

### Image analysis

- [GeoChat analysis](https://github.com/poorvajawale/northstar/blob/main/backend/tools/geochat_tool.py): `backend/tools/geochat_tool.py`
- [Change analysis](https://github.com/poorvajawale/northstar/blob/main/backend/tools/change_tool.py): `backend/tools/change_tool.py`
- [Optical-SAR reasoning](https://github.com/poorvajawale/northstar/blob/main/backend/tools/optical_sar_tool.py): `backend/tools/optical_sar_tool.py`
- [Land-cover analysis](https://github.com/poorvajawale/northstar/blob/main/backend/tools/landcover_tool.py): `backend/tools/landcover_tool.py`
- [Disaster assessment](https://github.com/poorvajawale/northstar/blob/main/backend/tools/disaster_tool.py): `backend/tools/disaster_tool.py`

### Evidence and results

- [Confidence scoring](https://github.com/poorvajawale/northstar/blob/main/backend/agent/confidence.py): `backend/agent/confidence.py`
- [Geospatial alignment](https://github.com/poorvajawale/northstar/blob/main/backend/geo/alignment.py): `backend/geo/alignment.py`
- [Result schemas](https://github.com/poorvajawale/northstar/blob/main/backend/schemas.py): `backend/schemas.py`
- [Evidence reports](https://github.com/poorvajawale/northstar/blob/main/backend/report/builder.py): `backend/report/builder.py`

### Other components

- **Imagery analyst**
- **API consumer**

## Connections

- Imagery analyst → SatQuery interface: submits imagery
- React entry → SatQuery interface: renders
- SatQuery interface → FastAPI endpoints: sends queries
- FastAPI endpoints → Image ingestion: decodes uploads
- FastAPI endpoints → Agent controller: runs analysis
- Agent controller → Input inspection: inspects inputs
- Agent controller → Query classification: classifies query
- Agent controller → Tool registry: selects tool
- Tool registry → GeoChat analysis: dispatches
- Tool registry → Change analysis: dispatches
- Tool registry → Optical-SAR reasoning: dispatches
- Tool registry → Land-cover analysis: dispatches
- Tool registry → Disaster assessment: dispatches
- Agent controller → Confidence scoring: scores result
- Agent controller → Result schemas: builds response
- FastAPI endpoints → Evidence reports: builds report
- FastAPI endpoints → SatQuery interface: returns results
- SatQuery interface → API consumer: shows evidence