# pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system architecture

> Architecture diagram of the GitHub repository pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system, 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/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system
- Repository: https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system

## Overview

This repository combines a district-scale landslide modelling pipeline with a planner-facing decision product and an interactive 3D scenario simulator. A planner can inspect the district or adjust factors, run a scenario, and review susceptibility, confidence, explanations, sensitivity, and prioritisation. The documented pipeline audits data, builds and evaluates thematic models, calibrates them, performs raster inference, and applies decision layers. Some API service and decision-layer wiring is inferred only from documented capabilities and the file tree; those connections are left out where ownership is unclear.

Main entry points: [`run_pipeline.py`](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/run_pipeline.py) (Pipeline runner), [`frontend/src/services/predictionApi.ts`](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/frontend/src/services/predictionApi.ts) (Prediction API client), [`frontend/src/App.tsx`](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/frontend/src/App.tsx) (Simulator workspace), [`src/models/train.py`](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/src/models/train.py) (Model training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Modelling pipeline"]
  node_pipeline_runner["Pipeline runner<br/>[run_pipeline.py]"]
  node_data_audit["Data audit<br/>[audit.py]"]
  node_data_inputs[("Validated data<br/>[loaders.py]")]
  node_features["Feature building<br/>[build.py]"]
  node_themes["Theme partitioning<br/>[themes.py]"]
  node_spatial_cv["Spatial evaluation<br/>[spatial_stage.py]"]
  node_training["Model training<br/>[train.py]"]
  node_calibration["Calibration<br/>[calibration.py]"]
  node_model_bundle[("Model bundles<br/>[bundle.py]")]
  node_raster_inference["Raster inference<br/>[raster.py]"]
end

subgraph group_decision["Decision intelligence"]
  node_decision_layers["Planner decision layers<br/>[layers.py]"]
  node_interpretability["Interpretability"]
  node_map_visualisation["Map visualisation<br/>[maps.py]"]
end

subgraph group_api["Prediction API"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_prediction_router["Prediction routes<br/>[prediction.py]"]
  node_prediction_service["Prediction service<br/>[prediction.py]"]
  node_district_router["District routes<br/>[district.py]"]
  node_district_service["District service<br/>[district.py]"]
  node_prediction_response["Prediction response<br/>[requests.py]"]
end

subgraph group_frontend["Interactive simulator"]
  node_browser(("Planner browser"))
  node_app["Simulator workspace<br/>[App.tsx]"]
  node_run_hook["Scenario runner"]
  node_boot_hook["Backend startup<br/>[useBootSequence.ts]"]
  node_api_client["Prediction API client<br/>[predictionApi.ts]"]
  node_store["Simulation state<br/>[simulationStore.ts]"]
  node_viewport["3D district view"]
  node_results["Analysis results<br/>[ResultPanel.tsx]"]
  node_sensitivity["Sensitivity sweep<br/>[useSensitivity.ts]"]
end

node_planner(("District planner"))

node_pipeline_runner -->|"runs stages"| node_data_audit
node_data_audit -->|"audits inputs"| node_data_inputs
node_features -->|"loads data"| node_data_inputs
node_features -->|"builds features"| node_themes
node_spatial_cv -->|"evaluates features"| node_features
node_training -->|"trains on"| node_features
node_training -->|"fits theme models"| node_themes
node_training -->|"uses evaluation"| node_spatial_cv
node_training -->|"saves models"| node_model_bundle
node_calibration -->|"calibrates models"| node_model_bundle
node_raster_inference -->|"loads models"| node_model_bundle
node_raster_inference -->|"reads rasters"| node_data_inputs
node_raster_inference -->|"feeds susceptibility"| node_decision_layers
node_decision_layers -->|"produces planner maps"| node_map_visualisation
node_interpretability -->|"explains predictions"| node_decision_layers
node_pipeline_runner -->|"runs stages"| node_spatial_cv
node_pipeline_runner -->|"runs stages"| node_training
node_pipeline_runner -->|"runs stages"| node_calibration
node_pipeline_runner -->|"runs stages"| node_raster_inference
node_pipeline_runner -->|"runs stages"| node_decision_layers
node_api_app -->|"registers routes"| node_prediction_router
node_api_app -->|"registers routes"| node_district_router
node_api_app -->|"starts service"| node_prediction_service
node_api_app -->|"starts service"| node_district_service
node_prediction_router -->|"handles prediction"| node_prediction_service
node_district_router -->|"serves district data"| node_district_service
node_prediction_service -->|"uses models"| node_model_bundle
node_prediction_service -->|"requests explanations"| node_interpretability
node_browser -->|"uses simulator"| node_app
node_app -->|"checks readiness"| node_boot_hook
node_boot_hook -->|"polls health"| node_api_client
node_app -->|"starts scenario"| node_run_hook
node_run_hook -->|"updates run state"| node_store
node_run_hook -->|"submits factors"| node_api_client
node_api_client -->|"calls prediction API"| node_prediction_router
node_prediction_service -->|"returns result"| node_prediction_response
node_prediction_response -->|"delivers response"| node_api_client
node_app -->|"renders scene"| node_viewport
node_app -->|"renders analysis"| node_results
node_results -->|"reads results"| node_store
node_sensitivity -->|"requests sweep"| node_api_client
node_api_client -->|"requests sensitivity"| node_prediction_router
node_planner -->|"opens simulator"| node_browser

click node_pipeline_runner "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/run_pipeline.py"
click node_data_audit "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/src/data/audit.py"
click node_data_inputs "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/src/data/loaders.py"
click node_features "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/src/features/build.py"
click node_themes "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/src/features/themes.py"
click node_spatial_cv "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/src/evaluation/spatial_stage.py"
click node_training "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/src/models/train.py"
click node_calibration "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/src/models/calibration.py"
click node_model_bundle "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/src/models/bundle.py"
click node_raster_inference "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/src/inference/raster.py"
click node_decision_layers "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/src/decision/layers.py"
click node_interpretability "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/src/evaluation/interpretability.py"
click node_map_visualisation "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/src/visualisation/maps.py"
click node_api_app "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/api/app/main.py"
click node_prediction_router "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/api/app/routers/prediction.py"
click node_prediction_service "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/api/app/services/prediction.py"
click node_district_router "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/api/app/routers/district.py"
click node_district_service "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/api/app/services/district.py"
click node_app "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/frontend/src/App.tsx"
click node_run_hook "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/frontend/src/hooks/useRunSimulation.ts"
click node_boot_hook "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/frontend/src/hooks/useBootSequence.ts"
click node_api_client "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/frontend/src/services/predictionApi.ts"
click node_store "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/frontend/src/store/simulationStore.ts"
click node_viewport "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/frontend/src/components/simulation/SimulationViewport.tsx"
click node_results "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/frontend/src/components/results/ResultPanel.tsx"
click node_sensitivity "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/frontend/src/hooks/useSensitivity.ts"
click node_prediction_response "https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/api/app/schemas/requests.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_pipeline_runner,node_data_audit,node_data_inputs,node_features,node_themes,node_spatial_cv,node_training,node_calibration,node_model_bundle,node_raster_inference toneBlue
class node_decision_layers,node_interpretability,node_map_visualisation toneAmber
class node_api_app,node_prediction_router,node_prediction_service,node_district_router,node_district_service,node_prediction_response toneMint
class node_browser,node_app,node_run_hook,node_boot_hook,node_api_client,node_store,node_viewport,node_results,node_sensitivity toneRose
class node_planner toneIndigo
```

## Components

### Modelling pipeline

- [Pipeline runner](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/run_pipeline.py): `run_pipeline.py`
- [Data audit](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/src/data/audit.py): `src/data/audit.py`
- [Validated data](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/src/data/loaders.py): `src/data/loaders.py`
- [Feature building](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/src/features/build.py): `src/features/build.py`
- [Theme partitioning](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/src/features/themes.py): `src/features/themes.py`
- [Spatial evaluation](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/src/evaluation/spatial_stage.py): `src/evaluation/spatial_stage.py`
- [Model training](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/src/models/train.py): `src/models/train.py`
- [Calibration](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/src/models/calibration.py): `src/models/calibration.py`
- [Model bundles](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/src/models/bundle.py): `src/models/bundle.py`
- [Raster inference](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/src/inference/raster.py): `src/inference/raster.py`

### Decision intelligence

- [Planner decision layers](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/src/decision/layers.py): `src/decision/layers.py`
- [Interpretability](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/src/evaluation/interpretability.py): `src/evaluation/interpretability.py`
- [Map visualisation](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/src/visualisation/maps.py): `src/visualisation/maps.py`

### Prediction API

- [FastAPI application](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/api/app/main.py): `api/app/main.py`
- [Prediction routes](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/api/app/routers/prediction.py): `api/app/routers/prediction.py`
- [Prediction service](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/api/app/services/prediction.py): `api/app/services/prediction.py`
- [District routes](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/api/app/routers/district.py): `api/app/routers/district.py`
- [District service](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/api/app/services/district.py): `api/app/services/district.py`
- [Prediction response](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/api/app/schemas/requests.py): `api/app/schemas/requests.py`

### Interactive simulator

- **Planner browser**
- [Simulator workspace](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Scenario runner](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/frontend/src/hooks/useRunSimulation.ts): `frontend/src/hooks/useRunSimulation.ts`
- [Backend startup](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/frontend/src/hooks/useBootSequence.ts): `frontend/src/hooks/useBootSequence.ts`
- [Prediction API client](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/frontend/src/services/predictionApi.ts): `frontend/src/services/predictionApi.ts`
- [Simulation state](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/frontend/src/store/simulationStore.ts): `frontend/src/store/simulationStore.ts`
- [3D district view](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/frontend/src/components/simulation/SimulationViewport.tsx): `frontend/src/components/simulation/SimulationViewport.tsx`
- [Analysis results](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/frontend/src/components/results/ResultPanel.tsx): `frontend/src/components/results/ResultPanel.tsx`
- [Sensitivity sweep](https://github.com/pathansohail3131/geosafe-ai-explainable-spatiotemporal-landslide-risk-and-early-warning-decision-intelligence-system/blob/main/frontend/src/hooks/useSensitivity.ts): `frontend/src/hooks/useSensitivity.ts`

### Other components

- **District planner**

## Connections

- Pipeline runner → Data audit: runs stages
- Data audit → Validated data: audits inputs
- Feature building → Validated data: loads data
- Feature building → Theme partitioning: builds features
- Spatial evaluation → Feature building: evaluates features
- Model training → Feature building: trains on
- Model training → Theme partitioning: fits theme models
- Model training → Spatial evaluation: uses evaluation
- Model training → Model bundles: saves models
- Calibration → Model bundles: calibrates models
- Raster inference → Model bundles: loads models
- Raster inference → Validated data: reads rasters
- Raster inference → Planner decision layers: feeds susceptibility
- Planner decision layers → Map visualisation: produces planner maps
- Interpretability → Planner decision layers: explains predictions
- Pipeline runner → Spatial evaluation: runs stages
- Pipeline runner → Model training: runs stages
- Pipeline runner → Calibration: runs stages
- Pipeline runner → Raster inference: runs stages
- Pipeline runner → Planner decision layers: runs stages
- FastAPI application → Prediction routes: registers routes
- FastAPI application → District routes: registers routes
- FastAPI application → Prediction service: starts service
- FastAPI application → District service: starts service
- Prediction routes → Prediction service: handles prediction
- District routes → District service: serves district data
- Prediction service → Model bundles: uses models
- Prediction service → Interpretability: requests explanations
- Planner browser → Simulator workspace: uses simulator
- Simulator workspace → Backend startup: checks readiness
- Backend startup → Prediction API client: polls health
- Simulator workspace → Scenario runner: starts scenario
- Scenario runner → Simulation state: updates run state
- Scenario runner → Prediction API client: submits factors
- Prediction API client → Prediction routes: calls prediction API
- Prediction service → Prediction response: returns result
- Prediction response → Prediction API client: delivers response
- Simulator workspace → 3D district view: renders scene
- Simulator workspace → Analysis results: renders analysis
- Analysis results → Simulation state: reads results
- Sensitivity sweep → Prediction API client: requests sweep
- Prediction API client → Prediction routes: requests sensitivity
- District planner → Planner browser: opens simulator