# ditheshshettigar00-jpg/geopovertyai architecture

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

- Interactive diagram: https://gitdiagram.com/ditheshshettigar00-jpg/geopovertyai
- Repository: https://github.com/ditheshshettigar00-jpg/geopovertyai

## Overview

GeoPoverty AI estimates district-level deprivation from satellite-derived indicators, compares estimates with NFHS-5 survey benchmarks, and exposes results through a web dashboard. The documented workflow runs from geospatial feature extraction through leakage-aware state-held-out modeling to district predictions and decision-support views. The graph also includes authentication, reporting, and indicator services. Some links reflect README-documented capabilities rather than inspected call sites; unsampled modules are represented only where the README or source index supports their role.

Main entry points: [`backend/api/routes.py`](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/api/routes.py) (Prediction API), [`backend/app.py`](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/app.py) (Flask application), [`backend/api/reports.py`](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/api/reports.py) (District reports), [`backend/services/model_service.py`](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/services/model_service.py) (Model service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_geo["Geospatial data"]
  node_extract["Satellite features"]
  node_boundaries["District boundaries"]
  node_match["Name matching<br/>[name_keys.py]"]
end

subgraph group_ml["Modeling and explanation"]
  node_features["Feature pipeline<br/>[pipelines.py]"]
  node_validation["Spatial validation<br/>[geo_validation.py]"]
  node_training["Model training<br/>[train_models.py]"]
  node_shap["SHAP explanations<br/>[shap_explain.py]"]
end

subgraph group_api["Application services"]
  node_app["Flask application<br/>[app.py]"]
  node_routes["Prediction API<br/>[routes.py]"]
  node_model["Model service<br/>[model_service.py]"]
  node_indicators["District indicators"]
  node_profiles["District profiles<br/>[profile_service.py]"]
  node_hotspots["Hotspot clustering<br/>[hotspot_service.py]"]
  node_residuals["Hidden gap detector"]
  node_reports["District reports<br/>[reports.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_admin["Administration<br/>[admin.py]"]
  node_db[("SQLite data<br/>[db_service.py]")]
end

subgraph group_ui["Dashboard"]
  node_map["Choropleth map<br/>[map.js]"]
  node_predict["Scenario explorer<br/>[predict.js]"]
  node_compare["District comparison<br/>[compare.js]"]
  node_hotspot_ui["Hotspot view<br/>[hotspots.js]"]
end

node_analyst(("Researcher"))

node_analyst -->|"uses dashboard"| node_app
node_boundaries -.->|"supplies districts"| node_extract
node_extract -->|"provides indicators"| node_features
node_match -->|"matches district names"| node_indicators
node_features -->|"preprocesses features"| node_training
node_validation -->|"validates state-held-out"| node_training
node_training -->|"supplies fitted model"| node_model
node_model -->|"explains estimates"| node_shap
node_app -->|"registers API"| node_routes
node_app -->|"registers authentication"| node_auth
node_app -->|"registers reports"| node_reports
node_app -->|"registers administration"| node_admin
node_routes -->|"requests predictions"| node_model
node_routes -->|"requests clusters"| node_hotspots
node_routes -->|"requests residual atlas"| node_residuals
node_routes -->|"requests profiles"| node_profiles
node_routes -->|"requests indicators"| node_indicators
node_routes -->|"reads area data"| node_db
node_reports -->|"reads report data"| node_db
node_reports -->|"uses estimates"| node_model
node_reports -->|"uses indicators"| node_indicators
node_auth -->|"reads and writes accounts"| node_db
node_admin -.->|"manages accounts"| node_db
node_map -->|"fetches map data"| node_routes
node_predict -->|"requests scenarios"| node_routes
node_compare -.->|"requests district data"| node_routes
node_hotspot_ui -.->|"requests hotspots"| node_routes
node_analyst -->|"requests district reports"| node_reports
node_analyst -->|"reviews gap candidates"| node_residuals
node_analyst -->|"reviews district indicators"| node_indicators

click node_extract "https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/geospatial/extract_geospatial_features.py"
click node_boundaries "https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/geospatial/fetch_district_boundaries.py"
click node_match "https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/preprocessing/name_keys.py"
click node_features "https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/training/pipelines.py"
click node_validation "https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/training/geo_validation.py"
click node_training "https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/training/train_models.py"
click node_shap "https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/explainability/shap_explain.py"
click node_app "https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/app.py"
click node_routes "https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/api/routes.py"
click node_model "https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/services/model_service.py"
click node_indicators "https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/services/indicator_service.py"
click node_profiles "https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/services/profile_service.py"
click node_hotspots "https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/services/hotspot_service.py"
click node_residuals "https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/services/residual_service.py"
click node_reports "https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/api/reports.py"
click node_auth "https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/api/auth.py"
click node_admin "https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/api/admin.py"
click node_db "https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/services/db_service.py"
click node_map "https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/frontend/static/js/map.js"
click node_predict "https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/frontend/static/js/predict.js"
click node_compare "https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/frontend/static/js/compare.js"
click node_hotspot_ui "https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/frontend/static/js/hotspots.js"

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_extract,node_boundaries,node_match toneBlue
class node_features,node_validation,node_training,node_shap toneAmber
class node_app,node_routes,node_model,node_indicators,node_profiles,node_hotspots,node_residuals,node_reports,node_auth,node_admin,node_db toneMint
class node_map,node_predict,node_compare,node_hotspot_ui toneRose
class node_analyst toneIndigo
```

## Components

### Geospatial data

- [Satellite features](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/geospatial/extract_geospatial_features.py): `geospatial/extract_geospatial_features.py`
- [District boundaries](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/geospatial/fetch_district_boundaries.py): `geospatial/fetch_district_boundaries.py`
- [Name matching](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/preprocessing/name_keys.py): `preprocessing/name_keys.py`

### Modeling and explanation

- [Feature pipeline](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/training/pipelines.py): `training/pipelines.py`
- [Spatial validation](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/training/geo_validation.py): `training/geo_validation.py`
- [Model training](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/training/train_models.py): `training/train_models.py`
- [SHAP explanations](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/explainability/shap_explain.py): `explainability/shap_explain.py`

### Application services

- [Flask application](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/app.py): `backend/app.py`
- [Prediction API](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/api/routes.py): `backend/api/routes.py`
- [Model service](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/services/model_service.py): `backend/services/model_service.py`
- [District indicators](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/services/indicator_service.py): `backend/services/indicator_service.py`
- [District profiles](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/services/profile_service.py): `backend/services/profile_service.py`
- [Hotspot clustering](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/services/hotspot_service.py): `backend/services/hotspot_service.py`
- [Hidden gap detector](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/services/residual_service.py): `backend/services/residual_service.py`
- [District reports](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/api/reports.py): `backend/api/reports.py`
- [Authentication](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/api/auth.py): `backend/api/auth.py`
- [Administration](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/api/admin.py): `backend/api/admin.py`
- [SQLite data](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/backend/services/db_service.py): `backend/services/db_service.py`

### Dashboard

- [Choropleth map](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/frontend/static/js/map.js): `frontend/static/js/map.js`
- [Scenario explorer](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/frontend/static/js/predict.js): `frontend/static/js/predict.js`
- [District comparison](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/frontend/static/js/compare.js): `frontend/static/js/compare.js`
- [Hotspot view](https://github.com/ditheshshettigar00-jpg/geopovertyai/blob/master/frontend/static/js/hotspots.js): `frontend/static/js/hotspots.js`

### Other components

- **Researcher**

## Connections

- Researcher → Flask application: uses dashboard
- District boundaries → Satellite features: supplies districts
- Satellite features → Feature pipeline: provides indicators
- Name matching → District indicators: matches district names (evidence: `backend/services/indicator_service.py`)
- Feature pipeline → Model training: preprocesses features (evidence: `training/pipelines.py`)
- Spatial validation → Model training: validates state-held-out
- Model training → Model service: supplies fitted model
- Model service → SHAP explanations: explains estimates (evidence: `backend/services/model_service.py`)
- Flask application → Prediction API: registers API (evidence: `backend/app.py`)
- Flask application → Authentication: registers authentication (evidence: `backend/app.py`)
- Flask application → District reports: registers reports (evidence: `backend/app.py`)
- Flask application → Administration: registers administration (evidence: `backend/app.py`)
- Prediction API → Model service: requests predictions (evidence: `backend/api/routes.py`)
- Prediction API → Hotspot clustering: requests clusters (evidence: `backend/api/routes.py`)
- Prediction API → Hidden gap detector: requests residual atlas (evidence: `backend/api/routes.py`)
- Prediction API → District profiles: requests profiles (evidence: `backend/api/routes.py`)
- Prediction API → District indicators: requests indicators (evidence: `backend/api/routes.py`)
- Prediction API → SQLite data: reads area data (evidence: `backend/api/routes.py`)
- District reports → SQLite data: reads report data (evidence: `backend/api/reports.py`)
- District reports → Model service: uses estimates (evidence: `backend/api/reports.py`)
- District reports → District indicators: uses indicators (evidence: `backend/api/reports.py`)
- Authentication → SQLite data: reads and writes accounts (evidence: `backend/api/auth.py`)
- Administration → SQLite data: manages accounts
- Choropleth map → Prediction API: fetches map data
- Scenario explorer → Prediction API: requests scenarios
- District comparison → Prediction API: requests district data
- Hotspot view → Prediction API: requests hotspots
- Researcher → District reports: requests district reports
- Researcher → Hidden gap detector: reviews gap candidates
- Researcher → District indicators: reviews district indicators
