# Yadadri Water Crisis Dashboard — Streamlit + Plotly

## PURPOSE
A single-screen command dashboard for the water emergency in Yadadri district: 44 villages
hit by falling groundwater, supplied by 50 rented private borewells. It visualises daily
litres delivered per village, flags those below the drinking-water minimum, tracks the
private-borewell rental fleet, and shows a district-wide trend so an engineer can see the
crisis shrinking or growing at a glance.

## WHY THIS MATTERS
The video is a status report — "44 villages, 50 borewells, no shortages expected". A status
report is only actionable if you can see *which* villages are still weak. This project turns
that narration into a living view: one stacked bar of supply by village, one line of daily
trend, one KPI row (villages critical, borewells active, mean LPCD). It is the difference
between a headline and a tool.

## HOW TO BUILD
1. `pip install streamlit plotly pandas`
2. Load a `supply.csv` (date, village, litres, households, borewells_active).
3. Add sidebar filters: date range, village multiselect, LPCD threshold slider.
4. Build Plotly figures — a bar of litres by village, a line of district trend, a KPI header.

```python
import streamlit as st, plotly.express as px, pandas as pd

df = pd.read_csv("supply.csv", parse_dates=["date"])
df["lpcd"] = df["litres"] / df["households"].clip(lower=1)
critical = df[df["lpcd"] < 40]

st.metric("Villages critical", critical["village"].nunique())
fig = px.bar(df.groupby("village", as_index=False)["litres"].sum(),
             x="village", y="litres", title="Litres delivered by village")
st.plotly_chart(fig, use_container_width=True)
```

## WHEN TO USE IN PRODUCTION
Great for daily stand-ups, war-room screens during a drought response, or a public-facing
relief transparency dashboard. Do NOT use Streamlit where you need sub-second interactivity
over millions of rows, custom auth, or write-back editing — it re-runs the whole script on
every interaction, so put a real API behind it for heavy use.

## HOW IT HELPS STUDENTS
Students learn the analytics loop end to end: load, derive a KPI, filter, chart, and lay out
a decision screen. They practise Plotly Express, Streamlit state, and clear KPI framing.

## STARTER CODE
`starter/main.py` is a runnable Streamlit app with a deterministic sample-data generator,
KPI metrics, two Plotly charts, and TODO markers for live data and a geospatial map view.
