# jhaabhijeet864/depthwizard architecture

> Architecture diagram of the GitHub repository jhaabhijeet864/depthwizard, 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/jhaabhijeet864/depthwizard
- Repository: https://github.com/jhaabhijeet864/depthwizard

## Overview

DepthWizard turns uploaded optical imagery or DEMs into elevation rasters, then presents them as interactive 3D terrain for inspection, calibration, hazard visualization, and export. The main upload-to-result path is visible in the frontend API hook and backend depth route; true DEMs bypass neural inference in the depth engine. The README documents additional calibration, local inference, and export capabilities. Some wiring is unsampled, so those links are shown only where supported by the tree or explicit documentation.

Main entry points: [`frontend/src/components/scene/DepthMesh.tsx`](https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/components/scene/DepthMesh.tsx) (Terrain mesh), [`frontend/src/components/layout/UploadForm.tsx`](https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/components/layout/UploadForm.tsx) (Upload form), [`backend/api/routes/depth.py`](https://github.com/jhaabhijeet864/depthwizard/blob/main/backend/api/routes/depth.py) (Depth endpoint), [`frontend/src/lib/api.ts`](https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/lib/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Operator workflow"]
  node_dashboard["Dashboard<br/>[DashboardView.tsx]"]
  node_upload["Upload form<br/>[UploadForm.tsx]"]
  node_appstate["App state<br/>[useAppStore.ts]"]
  node_depthhook["Depth API hook<br/>[useDepthApi.ts]"]
  node_apiclient["API client<br/>[api.ts]"]
end

subgraph group_processing["Elevation processing"]
  node_depthroute["Depth endpoint<br/>[depth.py]"]
  node_engine["Depth engine<br/>[depth_engine.py]"]
  node_geo["GIS geometry<br/>[gis_utils.py]"]
  node_clientdepth["Browser inference<br/>[clientDepth.ts]"]
end

subgraph group_terrain["3D terrain"]
  node_viewport["Viewport<br/>[ViewportView.tsx]"]
  node_scene["Scene renderer<br/>[ViewportScene.tsx]"]
  node_mesh["Terrain mesh<br/>[DepthMesh.tsx]"]
  node_shader["Terrain shading"]
  node_telemetry["Telemetry HUD<br/>[TelemetryHUD.tsx]"]
end

subgraph group_analysis["Calibration and export"]
  node_calroute["Calibration endpoint<br/>[calibrate.py]"]
  node_geometry["Geometry services<br/>[geometry.py]"]
  node_sidebar["Terrain controls<br/>[RightSidebar.tsx]"]
  node_exports["Export utilities<br/>[exportUtils.ts]"]
end

node_operator(("Operator"))

node_operator -->|"opens"| node_dashboard
node_dashboard -->|"presents"| node_upload
node_upload -->|"requests estimate"| node_depthhook
node_depthhook -->|"calls"| node_apiclient
node_apiclient -->|"posts image"| node_depthroute
node_depthroute -->|"estimates depth"| node_engine
node_depthroute -->|"exports raster"| node_geo
node_depthroute -->|"returns raster"| node_apiclient
node_upload -->|"stores upload"| node_appstate
node_depthhook -->|"updates results"| node_appstate
node_upload -.->|"may infer locally"| node_clientdepth
node_operator -->|"inspects terrain"| node_viewport
node_viewport -->|"renders"| node_scene
node_scene -->|"mounts"| node_mesh
node_mesh -->|"reads terrain state"| node_appstate
node_mesh -->|"applies shading"| node_shader
node_mesh -->|"provides hover data"| node_telemetry
node_operator -->|"sets analysis options"| node_sidebar
node_sidebar -->|"updates controls"| node_appstate
node_operator -->|"submits calibration"| node_calroute
node_calroute -->|"fits calibration"| node_geometry
node_sidebar -->|"starts export"| node_exports
node_exports -->|"requests GeoTIFF"| node_apiclient
node_exports -->|"exports mesh"| node_mesh

click node_dashboard "https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/pages/DashboardView.tsx"
click node_upload "https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/components/layout/UploadForm.tsx"
click node_appstate "https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/store/useAppStore.ts"
click node_depthhook "https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/hooks/useDepthApi.ts"
click node_apiclient "https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/lib/api.ts"
click node_depthroute "https://github.com/jhaabhijeet864/depthwizard/blob/main/backend/api/routes/depth.py"
click node_engine "https://github.com/jhaabhijeet864/depthwizard/blob/main/backend/services/depth_engine.py"
click node_geo "https://github.com/jhaabhijeet864/depthwizard/blob/main/backend/services/gis_utils.py"
click node_calroute "https://github.com/jhaabhijeet864/depthwizard/blob/main/backend/api/routes/calibrate.py"
click node_geometry "https://github.com/jhaabhijeet864/depthwizard/blob/main/backend/services/geometry.py"
click node_clientdepth "https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/lib/clientDepth.ts"
click node_viewport "https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/pages/ViewportView.tsx"
click node_scene "https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/components/scene/ViewportScene.tsx"
click node_mesh "https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/components/scene/DepthMesh.tsx"
click node_shader "https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/shaders/displacement.glsl.ts"
click node_telemetry "https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/components/scene/TelemetryHUD.tsx"
click node_sidebar "https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/components/layout/RightSidebar.tsx"
click node_exports "https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/lib/exportUtils.ts"

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_dashboard,node_upload,node_appstate,node_depthhook,node_apiclient toneBlue
class node_depthroute,node_engine,node_geo,node_clientdepth toneAmber
class node_viewport,node_scene,node_mesh,node_shader,node_telemetry toneMint
class node_calroute,node_geometry,node_sidebar,node_exports toneRose
class node_operator toneIndigo
```

## Components

### Operator workflow

- [Dashboard](https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/pages/DashboardView.tsx): `frontend/src/pages/DashboardView.tsx`
- [Upload form](https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/components/layout/UploadForm.tsx): `frontend/src/components/layout/UploadForm.tsx`
- [App state](https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/store/useAppStore.ts): `frontend/src/store/useAppStore.ts`
- [Depth API hook](https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/hooks/useDepthApi.ts): `frontend/src/hooks/useDepthApi.ts`
- [API client](https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### Elevation processing

- [Depth endpoint](https://github.com/jhaabhijeet864/depthwizard/blob/main/backend/api/routes/depth.py): `backend/api/routes/depth.py`
- [Depth engine](https://github.com/jhaabhijeet864/depthwizard/blob/main/backend/services/depth_engine.py): `backend/services/depth_engine.py`
- [GIS geometry](https://github.com/jhaabhijeet864/depthwizard/blob/main/backend/services/gis_utils.py): `backend/services/gis_utils.py`
- [Browser inference](https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/lib/clientDepth.ts): `frontend/src/lib/clientDepth.ts`

### 3D terrain

- [Viewport](https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/pages/ViewportView.tsx): `frontend/src/pages/ViewportView.tsx`
- [Scene renderer](https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/components/scene/ViewportScene.tsx): `frontend/src/components/scene/ViewportScene.tsx`
- [Terrain mesh](https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/components/scene/DepthMesh.tsx): `frontend/src/components/scene/DepthMesh.tsx`
- [Terrain shading](https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/shaders/displacement.glsl.ts): `frontend/src/shaders/displacement.glsl.ts`
- [Telemetry HUD](https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/components/scene/TelemetryHUD.tsx): `frontend/src/components/scene/TelemetryHUD.tsx`

### Calibration and export

- [Calibration endpoint](https://github.com/jhaabhijeet864/depthwizard/blob/main/backend/api/routes/calibrate.py): `backend/api/routes/calibrate.py`
- [Geometry services](https://github.com/jhaabhijeet864/depthwizard/blob/main/backend/services/geometry.py): `backend/services/geometry.py`
- [Terrain controls](https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/components/layout/RightSidebar.tsx): `frontend/src/components/layout/RightSidebar.tsx`
- [Export utilities](https://github.com/jhaabhijeet864/depthwizard/blob/main/frontend/src/lib/exportUtils.ts): `frontend/src/lib/exportUtils.ts`

### Other components

- **Operator**

## Connections

- Operator → Dashboard: opens
- Dashboard → Upload form: presents
- Upload form → Depth API hook: requests estimate
- Depth API hook → API client: calls
- API client → Depth endpoint: posts image
- Depth endpoint → Depth engine: estimates depth
- Depth endpoint → GIS geometry: exports raster
- Depth endpoint → API client: returns raster
- Upload form → App state: stores upload
- Depth API hook → App state: updates results
- Upload form → Browser inference: may infer locally
- Operator → Viewport: inspects terrain
- Viewport → Scene renderer: renders
- Scene renderer → Terrain mesh: mounts
- Terrain mesh → App state: reads terrain state
- Terrain mesh → Terrain shading: applies shading
- Terrain mesh → Telemetry HUD: provides hover data
- Operator → Terrain controls: sets analysis options
- Terrain controls → App state: updates controls
- Operator → Calibration endpoint: submits calibration
- Calibration endpoint → Geometry services: fits calibration
- Terrain controls → Export utilities: starts export
- Export utilities → API client: requests GeoTIFF
- Export utilities → Terrain mesh: exports mesh