# thenameisdebojit/asterra-ai architecture

> Architecture diagram of the GitHub repository thenameisdebojit/asterra-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/thenameisdebojit/asterra-ai
- Repository: https://github.com/thenameisdebojit/asterra-ai

## Overview

ASTERRA AI (DepthWizard) turns uploaded or map-selected imagery into relative height estimates, geospatially calibrated DSM products, and interactive 3D views. The main production path is job creation, raster ingestion and semantic analysis, depth inference, optional DEM/GCP calibration, enrichment, and reconstruction. The repository also documents progressive model adaptation and browser-based hazard visualization. Backend links follow the sampled pipeline and source references; README-described capabilities are retained where implementation details were not sampled.

Main entry points: [`backend/pipeline.py`](https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/pipeline.py) (Reconstruction pipeline), [`frontend/src/App.jsx`](https://github.com/thenameisdebojit/asterra-ai/blob/main/frontend/src/App.jsx) (Application shell), [`backend/main.py`](https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/main.py) (FastAPI endpoints), [`backend/jobs.py`](https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/jobs.py) (Job queue)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web experience"]
  node_app["Application shell<br/>[App.jsx]"]
  node_clientstate["Workflow state<br/>[useAppStore.js]"]
  node_viewer["3D viewer<br/>[ViewerScreen.jsx]"]
  node_hazardhook["Hazard scene<br/>[useHazardScene.js]"]
  node_hazardlayers["Hazard layers<br/>[hazardLayers.js]"]
end

subgraph group_api["Job backend"]
  node_api["FastAPI endpoints<br/>[main.py]"]
  node_jobs["Job queue<br/>[jobs.py]"]
  node_store[("Job and artifact store<br/>[storage.py]")]
  node_pipeline["Reconstruction pipeline<br/>[pipeline.py]"]
end

subgraph group_geo["Depth and geospatial"]
  node_imagery["Imagery discovery<br/>[imagery_service.py]"]
  node_inferenceadapter["Inference adapter"]
  node_depthmodel["Tiled depth inference"]
  node_segmentation["Semantic segmentation"]
  node_segmentengine["Segmentation engine<br/>[engine.py]"]
  node_calservice["Calibration service"]
  node_calengine["DEM calibration"]
  node_dem["Elevation references<br/>[dem_service.py]"]
  node_buildings["Building enrichment"]
end

subgraph group_render["Visualization and adaptation"]
  node_reconstruct["3D reconstruction"]
  node_surface["Terrain surface<br/>[terrain_surface.py]"]
  node_mesh["Mesh and GLB export<br/>[generate_3d.py]"]
  node_adaptation["Progressive adaptation"]
  node_satelliteadapt["Satellite adaptation"]
end

node_user(("Imagery user"))

node_user -->|"uses"| node_app
node_app -->|"reads state"| node_clientstate
node_app -->|"renders"| node_viewer
node_hazardhook -->|"uses layers"| node_hazardlayers
node_hazardhook -->|"updates state"| node_clientstate
node_user -->|"uploads or requests"| node_api
node_api -->|"creates jobs"| node_jobs
node_jobs -->|"persists state"| node_store
node_jobs -->|"runs pipeline"| node_pipeline
node_api -->|"requests map imagery"| node_imagery
node_pipeline -->|"reads and updates"| node_store
node_pipeline -->|"materializes scenes"| node_imagery
node_pipeline -->|"runs segmentation"| node_segmentation
node_segmentation -->|"delegates inference"| node_segmentengine
node_pipeline -->|"runs depth inference"| node_inferenceadapter
node_inferenceadapter -->|"loads and invokes"| node_depthmodel
node_pipeline -->|"gets elevation data"| node_dem
node_pipeline -->|"requests calibration"| node_calservice
node_calservice -->|"delegates calibration"| node_calengine
node_pipeline -->|"enriches buildings"| node_buildings
node_pipeline -->|"requests reconstruction"| node_reconstruct
node_reconstruct -->|"generates 3D output"| node_mesh
node_pipeline -->|"produces surface"| node_surface
node_user -.->|"trains progressively"| node_adaptation
node_adaptation -.->|"transfers stages"| node_satelliteadapt
node_depthmodel -.->|"calibrates relative depth"| node_calengine
node_calengine -.->|"enables metric surface"| node_surface

click node_app "https://github.com/thenameisdebojit/asterra-ai/blob/main/frontend/src/App.jsx"
click node_clientstate "https://github.com/thenameisdebojit/asterra-ai/blob/main/frontend/src/store/useAppStore.js"
click node_viewer "https://github.com/thenameisdebojit/asterra-ai/blob/main/frontend/src/components/ViewerScreen.jsx"
click node_hazardhook "https://github.com/thenameisdebojit/asterra-ai/blob/main/frontend/src/components/hazards/useHazardScene.js"
click node_hazardlayers "https://github.com/thenameisdebojit/asterra-ai/blob/main/frontend/src/three/hazardLayers.js"
click node_api "https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/main.py"
click node_jobs "https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/jobs.py"
click node_store "https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/storage.py"
click node_pipeline "https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/pipeline.py"
click node_imagery "https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/services/imagery_service.py"
click node_inferenceadapter "https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/services/inference_service.py"
click node_depthmodel "https://github.com/thenameisdebojit/asterra-ai/blob/main/asterra_tiled_inference.py"
click node_segmentation "https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/services/segmentation_service.py"
click node_segmentengine "https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/segmentation/engine.py"
click node_calservice "https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/services/calibration_service.py"
click node_calengine "https://github.com/thenameisdebojit/asterra-ai/blob/main/calibration/calibration_engine.py"
click node_dem "https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/services/dem_service.py"
click node_buildings "https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/services/building_service.py"
click node_reconstruct "https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/services/reconstruction_service.py"
click node_surface "https://github.com/thenameisdebojit/asterra-ai/blob/main/visualization/terrain_surface.py"
click node_mesh "https://github.com/thenameisdebojit/asterra-ai/blob/main/visualization/generate_3d.py"
click node_adaptation "https://github.com/thenameisdebojit/asterra-ai/tree/main/phase1"
click node_satelliteadapt "https://github.com/thenameisdebojit/asterra-ai/tree/main/phase2"

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_app,node_clientstate,node_viewer,node_hazardhook,node_hazardlayers,node_user toneBlue
class node_api,node_jobs,node_store,node_pipeline toneAmber
class node_imagery,node_inferenceadapter,node_depthmodel,node_segmentation,node_segmentengine,node_calservice,node_calengine,node_dem,node_buildings toneMint
class node_reconstruct,node_surface,node_mesh,node_adaptation,node_satelliteadapt toneRose
```

## Components

### Web experience

- [Application shell](https://github.com/thenameisdebojit/asterra-ai/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Workflow state](https://github.com/thenameisdebojit/asterra-ai/blob/main/frontend/src/store/useAppStore.js): `frontend/src/store/useAppStore.js`
- [3D viewer](https://github.com/thenameisdebojit/asterra-ai/blob/main/frontend/src/components/ViewerScreen.jsx): `frontend/src/components/ViewerScreen.jsx`
- [Hazard scene](https://github.com/thenameisdebojit/asterra-ai/blob/main/frontend/src/components/hazards/useHazardScene.js): `frontend/src/components/hazards/useHazardScene.js`
- [Hazard layers](https://github.com/thenameisdebojit/asterra-ai/blob/main/frontend/src/three/hazardLayers.js): `frontend/src/three/hazardLayers.js`

### Job backend

- [FastAPI endpoints](https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/main.py): `backend/main.py`
- [Job queue](https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/jobs.py): `backend/jobs.py`
- [Job and artifact store](https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/storage.py): `backend/storage.py`
- [Reconstruction pipeline](https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/pipeline.py): `backend/pipeline.py`

### Depth and geospatial

- [Imagery discovery](https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/services/imagery_service.py): `backend/services/imagery_service.py`
- [Inference adapter](https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/services/inference_service.py): `backend/services/inference_service.py`
- [Tiled depth inference](https://github.com/thenameisdebojit/asterra-ai/blob/main/asterra_tiled_inference.py): `asterra_tiled_inference.py`
- [Semantic segmentation](https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/services/segmentation_service.py): `backend/services/segmentation_service.py`
- [Segmentation engine](https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/segmentation/engine.py): `backend/segmentation/engine.py`
- [Calibration service](https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/services/calibration_service.py): `backend/services/calibration_service.py`
- [DEM calibration](https://github.com/thenameisdebojit/asterra-ai/blob/main/calibration/calibration_engine.py): `calibration/calibration_engine.py`
- [Elevation references](https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/services/dem_service.py): `backend/services/dem_service.py`
- [Building enrichment](https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/services/building_service.py): `backend/services/building_service.py`

### Visualization and adaptation

- [3D reconstruction](https://github.com/thenameisdebojit/asterra-ai/blob/main/backend/services/reconstruction_service.py): `backend/services/reconstruction_service.py`
- [Terrain surface](https://github.com/thenameisdebojit/asterra-ai/blob/main/visualization/terrain_surface.py): `visualization/terrain_surface.py`
- [Mesh and GLB export](https://github.com/thenameisdebojit/asterra-ai/blob/main/visualization/generate_3d.py): `visualization/generate_3d.py`
- [Progressive adaptation](https://github.com/thenameisdebojit/asterra-ai/tree/main/phase1): `phase1`
- [Satellite adaptation](https://github.com/thenameisdebojit/asterra-ai/tree/main/phase2): `phase2`

### Other components

- **Imagery user**

## Connections

- Imagery user → Application shell: uses (evidence: `frontend/src/App.jsx`)
- Application shell → Workflow state: reads state (evidence: `frontend/src/App.jsx`)
- Application shell → 3D viewer: renders (evidence: `frontend/src/App.jsx`)
- Hazard scene → Hazard layers: uses layers (evidence: `frontend/src/components/hazards/useHazardScene.js`)
- Hazard scene → Workflow state: updates state (evidence: `frontend/src/components/hazards/useHazardScene.js`)
- Imagery user → FastAPI endpoints: uploads or requests (evidence: `backend/main.py`)
- FastAPI endpoints → Job queue: creates jobs (evidence: `backend/main.py`)
- Job queue → Job and artifact store: persists state (evidence: `backend/jobs.py`)
- Job queue → Reconstruction pipeline: runs pipeline (evidence: `backend/jobs.py`)
- FastAPI endpoints → Imagery discovery: requests map imagery (evidence: `backend/main.py`)
- Reconstruction pipeline → Job and artifact store: reads and updates (evidence: `backend/pipeline.py`)
- Reconstruction pipeline → Imagery discovery: materializes scenes (evidence: `backend/pipeline.py`)
- Reconstruction pipeline → Semantic segmentation: runs segmentation (evidence: `backend/pipeline.py`)
- Semantic segmentation → Segmentation engine: delegates inference (evidence: `backend/services/segmentation_service.py`)
- Reconstruction pipeline → Inference adapter: runs depth inference (evidence: `backend/pipeline.py`)
- Inference adapter → Tiled depth inference: loads and invokes (evidence: `backend/services/inference_service.py`)
- Reconstruction pipeline → Elevation references: gets elevation data (evidence: `backend/pipeline.py`)
- Reconstruction pipeline → Calibration service: requests calibration (evidence: `backend/pipeline.py`)
- Calibration service → DEM calibration: delegates calibration (evidence: `backend/services/calibration_service.py`)
- Reconstruction pipeline → Building enrichment: enriches buildings (evidence: `backend/pipeline.py`)
- Reconstruction pipeline → 3D reconstruction: requests reconstruction (evidence: `backend/pipeline.py`)
- 3D reconstruction → Mesh and GLB export: generates 3D output (evidence: `backend/services/reconstruction_service.py`)
- Reconstruction pipeline → Terrain surface: produces surface (evidence: `backend/pipeline.py`)
- Imagery user → Progressive adaptation: trains progressively (evidence: `README.md`)
- Progressive adaptation → Satellite adaptation: transfers stages (evidence: `README.md`)
- Tiled depth inference → DEM calibration: calibrates relative depth (evidence: `README.md`)
- DEM calibration → Terrain surface: enables metric surface (evidence: `README.md`)