# vedsongire/ground_water_intelligence architecture

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

- Interactive diagram: https://gitdiagram.com/vedsongire/ground_water_intelligence
- Repository: https://github.com/vedsongire/ground_water_intelligence

## Overview

This is a deterministic groundwater monitoring and early-warning platform for India and Maharashtra. Its principal workflow ingests heterogeneous observations, normalizes and quality-flags them, derives analytical products, serves read-only API responses, and presents site and regional intelligence in a geospatial dashboard. The README documents major analytical capabilities beyond the sampled implementation excerpts; those are represented as distinct subsystems, with documented but unverified artifact production links marked dashed. Data ingestion and API wiring are more directly evidenced in source excerpts.

Main entry points: [`src/data/pipeline.py`](https://github.com/vedsongire/ground_water_intelligence/blob/main/src/data/pipeline.py) (Ingestion pipeline), [`frontend/src/App.tsx`](https://github.com/vedsongire/ground_water_intelligence/blob/main/frontend/src/App.tsx) (Dashboard shell), [`src/data/quality.py`](https://github.com/vedsongire/ground_water_intelligence/blob/main/src/data/quality.py) (Quality control), [`src/api/routes/analytics.py`](https://github.com/vedsongire/ground_water_intelligence/blob/main/src/api/routes/analytics.py) (Analytics endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_pipeline["Ingestion pipeline<br/>[pipeline.py]"]
  node_loaders["Dataset loaders<br/>[loaders.py]"]
  node_normalization["Normalization<br/>[normalization.py]"]
  node_quality["Quality control<br/>[quality.py]"]
end

subgraph group_analytics["Hydrological analytics"]
  node_temporal["Temporal analysis<br/>[temporal.py]"]
  node_seasonal["Seasonal analysis<br/>[seasonal.py]"]
  node_spatial["Spatial analysis<br/>[spatial.py]"]
  node_baselines["Historical baselines<br/>[baselines.py]"]
  node_conditions["Condition classification<br/>[conditions.py]"]
  node_alerts["Statistical alerts<br/>[engine.py]"]
  node_forecast["Persistence forecast"]
  node_drought["Drought intelligence"]
  node_flood["Flood potential"]
  node_stress["Groundwater stress"]
  node_advanced["Advanced analytics"]
  node_trends["Trend analysis<br/>[trends.py]"]
end

subgraph group_service["Read-only service"]
  node_dal["DuckDB access<br/>[dal.py]"]
  node_routes["Site endpoints<br/>[candidate_sites.py]"]
  node_analytics_routes["Analytics endpoints<br/>[analytics.py]"]
  node_api["FastAPI service<br/>[main.py]"]
end

subgraph group_dashboard["Dashboard"]
  node_app["Dashboard shell<br/>[App.tsx]"]
  node_client["API client<br/>[api.ts]"]
  node_map["Site map<br/>[MapView.tsx]"]
  node_investigation["Site investigation"]
  node_analytics_ui["Analytics view"]
end

node_raw[("Observation data")]
node_artifacts[("Processed artifacts")]
node_user(("Dashboard user"))

node_raw -.->|"supplies observations"| node_pipeline
node_pipeline -->|"loads datasets"| node_loaders
node_pipeline -->|"normalizes data"| node_normalization
node_pipeline -->|"assesses quality"| node_quality
node_normalization -.->|"flags records"| node_quality
node_pipeline -->|"writes Parquet"| node_artifacts
node_quality -.->|"enables features"| node_temporal
node_quality -.->|"enables features"| node_seasonal
node_quality -.->|"enables features"| node_spatial
node_artifacts -.->|"feeds analytics"| node_baselines
node_artifacts -.->|"feeds analytics"| node_conditions
node_artifacts -.->|"feeds analytics"| node_alerts
node_artifacts -.->|"feeds analytics"| node_forecast
node_artifacts -.->|"feeds analytics"| node_drought
node_artifacts -.->|"feeds analytics"| node_flood
node_artifacts -.->|"feeds analytics"| node_stress
node_artifacts -.->|"feeds analytics"| node_advanced
node_artifacts -.->|"feeds analytics"| node_trends
node_artifacts -->|"read by DuckDB"| node_dal
node_api -->|"registers routes"| node_routes
node_api -->|"registers routes"| node_analytics_routes
node_routes -->|"queries data"| node_dal
node_analytics_routes -->|"queries data"| node_dal
node_analytics_routes -->|"uses analytics"| node_advanced
node_analytics_routes -->|"uses trends"| node_trends
node_user -.->|"uses dashboard"| node_app
node_app -->|"fetches sites"| node_client
node_app -->|"renders map"| node_map
node_app -->|"renders panel"| node_investigation
node_investigation -->|"fetches site data"| node_client
node_app -->|"renders analytics"| node_analytics_ui
node_client -.->|"requests JSON"| node_api

click node_pipeline "https://github.com/vedsongire/ground_water_intelligence/blob/main/src/data/pipeline.py"
click node_loaders "https://github.com/vedsongire/ground_water_intelligence/blob/main/src/data/loaders.py"
click node_normalization "https://github.com/vedsongire/ground_water_intelligence/blob/main/src/data/normalization.py"
click node_quality "https://github.com/vedsongire/ground_water_intelligence/blob/main/src/data/quality.py"
click node_temporal "https://github.com/vedsongire/ground_water_intelligence/blob/main/src/features/temporal.py"
click node_seasonal "https://github.com/vedsongire/ground_water_intelligence/blob/main/src/features/seasonal.py"
click node_spatial "https://github.com/vedsongire/ground_water_intelligence/blob/main/src/features/spatial.py"
click node_baselines "https://github.com/vedsongire/ground_water_intelligence/blob/main/src/features/baselines.py"
click node_conditions "https://github.com/vedsongire/ground_water_intelligence/blob/main/src/features/conditions.py"
click node_alerts "https://github.com/vedsongire/ground_water_intelligence/blob/main/src/alerting/engine.py"
click node_forecast "https://github.com/vedsongire/ground_water_intelligence/blob/main/src/models/persistence_forecast.py"
click node_drought "https://github.com/vedsongire/ground_water_intelligence/blob/main/src/features/drought_intelligence.py"
click node_flood "https://github.com/vedsongire/ground_water_intelligence/blob/main/src/features/flood_intelligence.py"
click node_stress "https://github.com/vedsongire/ground_water_intelligence/blob/main/src/features/groundwater_stress.py"
click node_advanced "https://github.com/vedsongire/ground_water_intelligence/blob/main/src/features/advanced_analytics.py"
click node_trends "https://github.com/vedsongire/ground_water_intelligence/blob/main/src/features/trends.py"
click node_dal "https://github.com/vedsongire/ground_water_intelligence/blob/main/src/api/dal.py"
click node_routes "https://github.com/vedsongire/ground_water_intelligence/blob/main/src/api/routes/candidate_sites.py"
click node_analytics_routes "https://github.com/vedsongire/ground_water_intelligence/blob/main/src/api/routes/analytics.py"
click node_api "https://github.com/vedsongire/ground_water_intelligence/blob/main/src/api/main.py"
click node_app "https://github.com/vedsongire/ground_water_intelligence/blob/main/frontend/src/App.tsx"
click node_client "https://github.com/vedsongire/ground_water_intelligence/blob/main/frontend/src/services/api.ts"
click node_map "https://github.com/vedsongire/ground_water_intelligence/blob/main/frontend/src/components/MapView.tsx"
click node_investigation "https://github.com/vedsongire/ground_water_intelligence/blob/main/frontend/src/components/InvestigationPanel.tsx"
click node_analytics_ui "https://github.com/vedsongire/ground_water_intelligence/blob/main/frontend/src/components/AdvancedAnalytics.tsx"

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,node_loaders,node_normalization,node_quality,node_user toneBlue
class node_temporal,node_seasonal,node_spatial,node_baselines,node_conditions,node_alerts,node_forecast,node_drought,node_flood,node_stress,node_advanced,node_trends,node_raw,node_artifacts toneAmber
class node_dal,node_routes,node_analytics_routes,node_api toneMint
class node_app,node_client,node_map,node_investigation,node_analytics_ui toneRose
```

## Components

### Data preparation

- [Ingestion pipeline](https://github.com/vedsongire/ground_water_intelligence/blob/main/src/data/pipeline.py): `src/data/pipeline.py`
- [Dataset loaders](https://github.com/vedsongire/ground_water_intelligence/blob/main/src/data/loaders.py): `src/data/loaders.py`
- [Normalization](https://github.com/vedsongire/ground_water_intelligence/blob/main/src/data/normalization.py): `src/data/normalization.py`
- [Quality control](https://github.com/vedsongire/ground_water_intelligence/blob/main/src/data/quality.py): `src/data/quality.py`

### Hydrological analytics

- [Temporal analysis](https://github.com/vedsongire/ground_water_intelligence/blob/main/src/features/temporal.py): `src/features/temporal.py`
- [Seasonal analysis](https://github.com/vedsongire/ground_water_intelligence/blob/main/src/features/seasonal.py): `src/features/seasonal.py`
- [Spatial analysis](https://github.com/vedsongire/ground_water_intelligence/blob/main/src/features/spatial.py): `src/features/spatial.py`
- [Historical baselines](https://github.com/vedsongire/ground_water_intelligence/blob/main/src/features/baselines.py): `src/features/baselines.py`
- [Condition classification](https://github.com/vedsongire/ground_water_intelligence/blob/main/src/features/conditions.py): `src/features/conditions.py`
- [Statistical alerts](https://github.com/vedsongire/ground_water_intelligence/blob/main/src/alerting/engine.py): `src/alerting/engine.py`
- [Persistence forecast](https://github.com/vedsongire/ground_water_intelligence/blob/main/src/models/persistence_forecast.py): `src/models/persistence_forecast.py`
- [Drought intelligence](https://github.com/vedsongire/ground_water_intelligence/blob/main/src/features/drought_intelligence.py): `src/features/drought_intelligence.py`
- [Flood potential](https://github.com/vedsongire/ground_water_intelligence/blob/main/src/features/flood_intelligence.py): `src/features/flood_intelligence.py`
- [Groundwater stress](https://github.com/vedsongire/ground_water_intelligence/blob/main/src/features/groundwater_stress.py): `src/features/groundwater_stress.py`
- [Advanced analytics](https://github.com/vedsongire/ground_water_intelligence/blob/main/src/features/advanced_analytics.py): `src/features/advanced_analytics.py`
- [Trend analysis](https://github.com/vedsongire/ground_water_intelligence/blob/main/src/features/trends.py): `src/features/trends.py`

### Read-only service

- [DuckDB access](https://github.com/vedsongire/ground_water_intelligence/blob/main/src/api/dal.py): `src/api/dal.py`
- [Site endpoints](https://github.com/vedsongire/ground_water_intelligence/blob/main/src/api/routes/candidate_sites.py): `src/api/routes/candidate_sites.py`
- [Analytics endpoints](https://github.com/vedsongire/ground_water_intelligence/blob/main/src/api/routes/analytics.py): `src/api/routes/analytics.py`
- [FastAPI service](https://github.com/vedsongire/ground_water_intelligence/blob/main/src/api/main.py): `src/api/main.py`

### Dashboard

- [Dashboard shell](https://github.com/vedsongire/ground_water_intelligence/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/vedsongire/ground_water_intelligence/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Site map](https://github.com/vedsongire/ground_water_intelligence/blob/main/frontend/src/components/MapView.tsx): `frontend/src/components/MapView.tsx`
- [Site investigation](https://github.com/vedsongire/ground_water_intelligence/blob/main/frontend/src/components/InvestigationPanel.tsx): `frontend/src/components/InvestigationPanel.tsx`
- [Analytics view](https://github.com/vedsongire/ground_water_intelligence/blob/main/frontend/src/components/AdvancedAnalytics.tsx): `frontend/src/components/AdvancedAnalytics.tsx`

### Other components

- **Observation data**
- **Processed artifacts**
- **Dashboard user**

## Connections

- Observation data → Ingestion pipeline: supplies observations
- Ingestion pipeline → Dataset loaders: loads datasets (evidence: `src/data/pipeline.py`)
- Ingestion pipeline → Normalization: normalizes data (evidence: `src/data/pipeline.py`)
- Ingestion pipeline → Quality control: assesses quality (evidence: `src/data/pipeline.py`)
- Normalization → Quality control: flags records
- Ingestion pipeline → Processed artifacts: writes Parquet (evidence: `src/data/pipeline.py`)
- Quality control → Temporal analysis: enables features
- Quality control → Seasonal analysis: enables features
- Quality control → Spatial analysis: enables features
- Processed artifacts → Historical baselines: feeds analytics
- Processed artifacts → Condition classification: feeds analytics
- Processed artifacts → Statistical alerts: feeds analytics
- Processed artifacts → Persistence forecast: feeds analytics
- Processed artifacts → Drought intelligence: feeds analytics
- Processed artifacts → Flood potential: feeds analytics
- Processed artifacts → Groundwater stress: feeds analytics
- Processed artifacts → Advanced analytics: feeds analytics
- Processed artifacts → Trend analysis: feeds analytics
- Processed artifacts → DuckDB access: read by DuckDB (evidence: `src/api/dal.py`)
- FastAPI service → Site endpoints: registers routes (evidence: `src/api/main.py`)
- FastAPI service → Analytics endpoints: registers routes (evidence: `src/api/main.py`)
- Site endpoints → DuckDB access: queries data (evidence: `src/api/routes/candidate_sites.py`)
- Analytics endpoints → DuckDB access: queries data (evidence: `src/api/routes/analytics.py`)
- Analytics endpoints → Advanced analytics: uses analytics (evidence: `src/api/routes/analytics.py`)
- Analytics endpoints → Trend analysis: uses trends (evidence: `src/api/routes/analytics.py`)
- Dashboard user → Dashboard shell: uses dashboard
- Dashboard shell → API client: fetches sites (evidence: `frontend/src/App.tsx`)
- Dashboard shell → Site map: renders map (evidence: `frontend/src/App.tsx`)
- Dashboard shell → Site investigation: renders panel (evidence: `frontend/src/App.tsx`)
- Site investigation → API client: fetches site data (evidence: `frontend/src/components/InvestigationPanel.tsx`)
- Dashboard shell → Analytics view: renders analytics
- API client → FastAPI service: requests JSON
