# sheel34/bhuvan architecture

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

- Interactive diagram: https://gitdiagram.com/sheel34/bhuvan
- Repository: https://github.com/sheel34/bhuvan

## Overview

BHUVAN is a lunar terrain-intelligence platform with a Mars HiRISE analysis extension. Users explore the Moon and mission atlas, select a site, inspect reconstructed terrain and analysis layers, then generate and export reports. The browser’s React/Three.js workspace calls a FastAPI backend for terrain data and analysis; backend capabilities also include async jobs, NASA/USGS data ingestion, optional GAN enhancement, and machine telemetry. Relationships for unsampled modules are included only where the README or source index supports them.

Main entry points: [`backend/main.py`](https://github.com/sheel34/bhuvan/blob/main/backend/main.py) (FastAPI service), [`backend/jobs/tasks.py`](https://github.com/sheel34/bhuvan/blob/main/backend/jobs/tasks.py) (Analysis worker), [`src/lib/api.js`](https://github.com/sheel34/bhuvan/blob/main/src/lib/api.js) (API client), [`src/App.jsx`](https://github.com/sheel34/bhuvan/blob/main/src/App.jsx) (Workspace app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser experience"]
  node_app["Workspace app<br/>[App.jsx]"]
  node_globe["Moon globe<br/>[MoonGlobe.jsx]"]
  node_atlas["Mission atlas<br/>[lunarMissions.js]"]
  node_scene["Terrain scene<br/>[SceneCanvas.jsx]"]
  node_chunked["Chunked terrain<br/>[TerrainChunked.jsx]"]
  node_terrainutil["Terrain interaction<br/>[terrain.js]"]
  node_api["API client<br/>[api.js]"]
  node_missions_ui["Mission dossiers<br/>[MissionDossier.jsx]"]
  node_reports_ui["Report interface<br/>[ReportModal.jsx]"]
  node_monitor["System monitor<br/>[SystemMonitor.jsx]"]
end

subgraph group_backend["Analysis backend"]
  node_api_server["FastAPI service<br/>[main.py]"]
  node_jobs_api["Async job API<br/>[routes.py]"]
  node_jobs_task["Analysis worker<br/>[tasks.py]"]
end

subgraph group_data["Terrain data"]
  node_data_fetch["Lunar DEM data<br/>[dem_fetch.py]"]
  node_lroc["LROC downloader<br/>[lroc_downloader.py]"]
  node_hirise["HiRISE downloader"]
  node_tiles["Tile processing<br/>[tile_processor.py]"]
end

subgraph group_compute["Analysis compute"]
  node_ingest["Terrain ingestion<br/>[ingest.py]"]
  node_analysis["Terrain analysis"]
  node_intelligence["Surface intelligence<br/>[intelligence.py]"]
  node_landing["Landing zones<br/>[landing_zones.py]"]
  node_tercom["TERCOM matching<br/>[tercom.py]"]
  node_ai["Terrain GAN<br/>[runtime.py]"]
end

subgraph group_services["Reports and services"]
  node_reports["Report generation<br/>[reports.py]"]
  node_store[("Workspace store<br/>[store.py]")]
  node_telemetry["Machine telemetry<br/>[telemetry.py]"]
  node_celery["Celery queue<br/>[celery_app.py]"]
end

node_user(("Mission planner"))

node_user -->|"explores"| node_globe
node_globe -->|"shows missions"| node_atlas
node_user -->|"opens dossier"| node_missions_ui
node_app -->|"renders"| node_globe
node_app -->|"renders workspace"| node_scene
node_app -->|"requests terrain and reports"| node_api
node_scene -->|"renders terrain"| node_chunked
node_scene -->|"samples heights"| node_terrainutil
node_api -->|"calls backend"| node_api_server
node_api_server -->|"fetches DEM regions"| node_data_fetch
node_api_server -->|"loads lunar data"| node_lroc
node_api_server -->|"runs analysis"| node_analysis
node_api_server -->|"requests intelligence"| node_intelligence
node_api_server -->|"ranks safe zones"| node_landing
node_api_server -->|"uses matching"| node_tercom
node_api_server -->|"generates reports"| node_reports
node_reports_ui -->|"requests report"| node_api
node_api_server -->|"persists workspace"| node_store
node_monitor -->|"requests stats"| node_api
node_api_server -->|"reads machine stats"| node_telemetry
node_jobs_api -->|"dispatches jobs"| node_celery
node_jobs_api -->|"queues analysis"| node_jobs_task
node_jobs_task -->|"ingests uploads"| node_ingest
node_jobs_task -->|"loads Mars DEM"| node_hirise
node_jobs_task -->|"uses analysis pipeline"| node_api_server
node_jobs_task -->|"optionally enhances"| node_ai
node_api_server -->|"serves HiRISE catalog"| node_hirise
node_api_server -.->|"optionally enhances terrain"| node_ai
node_hirise -.->|"processes terrain tiles"| node_tiles

click node_app "https://github.com/sheel34/bhuvan/blob/main/src/App.jsx"
click node_globe "https://github.com/sheel34/bhuvan/blob/main/src/scene/MoonGlobe.jsx"
click node_atlas "https://github.com/sheel34/bhuvan/blob/main/src/lib/lunarMissions.js"
click node_scene "https://github.com/sheel34/bhuvan/blob/main/src/scene/SceneCanvas.jsx"
click node_chunked "https://github.com/sheel34/bhuvan/blob/main/src/scene/TerrainChunked.jsx"
click node_terrainutil "https://github.com/sheel34/bhuvan/blob/main/src/engine/terrain.js"
click node_api "https://github.com/sheel34/bhuvan/blob/main/src/lib/api.js"
click node_missions_ui "https://github.com/sheel34/bhuvan/blob/main/src/components/MissionDossier.jsx"
click node_reports_ui "https://github.com/sheel34/bhuvan/blob/main/src/components/ReportModal.jsx"
click node_monitor "https://github.com/sheel34/bhuvan/blob/main/src/components/SystemMonitor.jsx"
click node_api_server "https://github.com/sheel34/bhuvan/blob/main/backend/main.py"
click node_jobs_api "https://github.com/sheel34/bhuvan/blob/main/backend/jobs/routes.py"
click node_jobs_task "https://github.com/sheel34/bhuvan/blob/main/backend/jobs/tasks.py"
click node_ingest "https://github.com/sheel34/bhuvan/blob/main/backend/pipeline/ingest.py"
click node_analysis "https://github.com/sheel34/bhuvan/blob/main/backend/pipeline/terrain_analysis.py"
click node_intelligence "https://github.com/sheel34/bhuvan/blob/main/backend/pipeline/intelligence.py"
click node_landing "https://github.com/sheel34/bhuvan/blob/main/backend/pipeline/landing_zones.py"
click node_tercom "https://github.com/sheel34/bhuvan/blob/main/backend/pipeline/tercom.py"
click node_ai "https://github.com/sheel34/bhuvan/blob/main/backend/ai/runtime.py"
click node_data_fetch "https://github.com/sheel34/bhuvan/blob/main/backend/data/dem_fetch.py"
click node_lroc "https://github.com/sheel34/bhuvan/blob/main/backend/data/lroc_downloader.py"
click node_hirise "https://github.com/sheel34/bhuvan/blob/main/backend/data/hirise_downloader.py"
click node_tiles "https://github.com/sheel34/bhuvan/blob/main/backend/data/tile_processor.py"
click node_reports "https://github.com/sheel34/bhuvan/blob/main/backend/workspace/reports.py"
click node_store "https://github.com/sheel34/bhuvan/blob/main/backend/workspace/store.py"
click node_telemetry "https://github.com/sheel34/bhuvan/blob/main/backend/system/telemetry.py"
click node_celery "https://github.com/sheel34/bhuvan/blob/main/backend/jobs/celery_app.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_app,node_globe,node_atlas,node_scene,node_chunked,node_terrainutil,node_api,node_missions_ui,node_reports_ui,node_monitor toneBlue
class node_api_server,node_jobs_api,node_jobs_task toneAmber
class node_data_fetch,node_lroc,node_hirise,node_tiles toneMint
class node_ingest,node_analysis,node_intelligence,node_landing,node_tercom,node_ai toneRose
class node_reports,node_store,node_telemetry,node_celery,node_user toneIndigo
```

## Components

### Browser experience

- [Workspace app](https://github.com/sheel34/bhuvan/blob/main/src/App.jsx): `src/App.jsx`
- [Moon globe](https://github.com/sheel34/bhuvan/blob/main/src/scene/MoonGlobe.jsx): `src/scene/MoonGlobe.jsx`
- [Mission atlas](https://github.com/sheel34/bhuvan/blob/main/src/lib/lunarMissions.js): `src/lib/lunarMissions.js`
- [Terrain scene](https://github.com/sheel34/bhuvan/blob/main/src/scene/SceneCanvas.jsx): `src/scene/SceneCanvas.jsx`
- [Chunked terrain](https://github.com/sheel34/bhuvan/blob/main/src/scene/TerrainChunked.jsx): `src/scene/TerrainChunked.jsx`
- [Terrain interaction](https://github.com/sheel34/bhuvan/blob/main/src/engine/terrain.js): `src/engine/terrain.js`
- [API client](https://github.com/sheel34/bhuvan/blob/main/src/lib/api.js): `src/lib/api.js`
- [Mission dossiers](https://github.com/sheel34/bhuvan/blob/main/src/components/MissionDossier.jsx): `src/components/MissionDossier.jsx`
- [Report interface](https://github.com/sheel34/bhuvan/blob/main/src/components/ReportModal.jsx): `src/components/ReportModal.jsx`
- [System monitor](https://github.com/sheel34/bhuvan/blob/main/src/components/SystemMonitor.jsx): `src/components/SystemMonitor.jsx`

### Analysis backend

- [FastAPI service](https://github.com/sheel34/bhuvan/blob/main/backend/main.py): `backend/main.py`
- [Async job API](https://github.com/sheel34/bhuvan/blob/main/backend/jobs/routes.py): `backend/jobs/routes.py`
- [Analysis worker](https://github.com/sheel34/bhuvan/blob/main/backend/jobs/tasks.py): `backend/jobs/tasks.py`

### Terrain data

- [Lunar DEM data](https://github.com/sheel34/bhuvan/blob/main/backend/data/dem_fetch.py): `backend/data/dem_fetch.py`
- [LROC downloader](https://github.com/sheel34/bhuvan/blob/main/backend/data/lroc_downloader.py): `backend/data/lroc_downloader.py`
- [HiRISE downloader](https://github.com/sheel34/bhuvan/blob/main/backend/data/hirise_downloader.py): `backend/data/hirise_downloader.py`
- [Tile processing](https://github.com/sheel34/bhuvan/blob/main/backend/data/tile_processor.py): `backend/data/tile_processor.py`

### Analysis compute

- [Terrain ingestion](https://github.com/sheel34/bhuvan/blob/main/backend/pipeline/ingest.py): `backend/pipeline/ingest.py`
- [Terrain analysis](https://github.com/sheel34/bhuvan/blob/main/backend/pipeline/terrain_analysis.py): `backend/pipeline/terrain_analysis.py`
- [Surface intelligence](https://github.com/sheel34/bhuvan/blob/main/backend/pipeline/intelligence.py): `backend/pipeline/intelligence.py`
- [Landing zones](https://github.com/sheel34/bhuvan/blob/main/backend/pipeline/landing_zones.py): `backend/pipeline/landing_zones.py`
- [TERCOM matching](https://github.com/sheel34/bhuvan/blob/main/backend/pipeline/tercom.py): `backend/pipeline/tercom.py`
- [Terrain GAN](https://github.com/sheel34/bhuvan/blob/main/backend/ai/runtime.py): `backend/ai/runtime.py`

### Reports and services

- [Report generation](https://github.com/sheel34/bhuvan/blob/main/backend/workspace/reports.py): `backend/workspace/reports.py`
- [Workspace store](https://github.com/sheel34/bhuvan/blob/main/backend/workspace/store.py): `backend/workspace/store.py`
- [Machine telemetry](https://github.com/sheel34/bhuvan/blob/main/backend/system/telemetry.py): `backend/system/telemetry.py`
- [Celery queue](https://github.com/sheel34/bhuvan/blob/main/backend/jobs/celery_app.py): `backend/jobs/celery_app.py`

### Other components

- **Mission planner**

## Connections

- Mission planner → Moon globe: explores (evidence: `README.md`)
- Moon globe → Mission atlas: shows missions (evidence: `src/scene/MoonGlobe.jsx`)
- Mission planner → Mission dossiers: opens dossier (evidence: `README.md`)
- Workspace app → Moon globe: renders (evidence: `src/App.jsx`)
- Workspace app → Terrain scene: renders workspace (evidence: `src/App.jsx`)
- Workspace app → API client: requests terrain and reports (evidence: `src/App.jsx`)
- Terrain scene → Chunked terrain: renders terrain (evidence: `src/scene/SceneCanvas.jsx`)
- Terrain scene → Terrain interaction: samples heights (evidence: `src/scene/SceneCanvas.jsx`)
- API client → FastAPI service: calls backend (evidence: `README.md`)
- FastAPI service → Lunar DEM data: fetches DEM regions (evidence: `backend/main.py`)
- FastAPI service → LROC downloader: loads lunar data (evidence: `backend/main.py`)
- FastAPI service → Terrain analysis: runs analysis (evidence: `backend/main.py`)
- FastAPI service → Surface intelligence: requests intelligence (evidence: `backend/main.py`)
- FastAPI service → Landing zones: ranks safe zones (evidence: `backend/main.py`)
- FastAPI service → TERCOM matching: uses matching (evidence: `backend/main.py`)
- FastAPI service → Report generation: generates reports (evidence: `README.md`)
- Report interface → API client: requests report (evidence: `src/App.jsx`)
- FastAPI service → Workspace store: persists workspace (evidence: `backend/main.py`)
- System monitor → API client: requests stats (evidence: `src/components/SystemMonitor.jsx`)
- FastAPI service → Machine telemetry: reads machine stats (evidence: `backend/main.py`)
- Async job API → Celery queue: dispatches jobs (evidence: `backend/jobs/routes.py`)
- Async job API → Analysis worker: queues analysis (evidence: `backend/jobs/routes.py`)
- Analysis worker → Terrain ingestion: ingests uploads (evidence: `backend/jobs/tasks.py`)
- Analysis worker → HiRISE downloader: loads Mars DEM (evidence: `backend/jobs/tasks.py`)
- Analysis worker → FastAPI service: uses analysis pipeline (evidence: `backend/jobs/tasks.py`)
- Analysis worker → Terrain GAN: optionally enhances (evidence: `backend/jobs/tasks.py`)
- FastAPI service → HiRISE downloader: serves HiRISE catalog (evidence: `backend/main.py`)
- FastAPI service → Terrain GAN: optionally enhances terrain (evidence: `README.md`)
- HiRISE downloader → Tile processing: processes terrain tiles
