# Bhuvanagiri Jal Setu — Village Water Supply Status Web App (Gradio)

## PURPOSE
When groundwater levels collapsed across Yadadri district, 44 villages hit a severe
drinking-water crisis and officials rented 50 private borewells as an emergency fix. This
project builds a small Gradio web app that lets a Rural Water Supply field officer register
a village's daily supply status — tanker arrivals, borewell flow, and household coverage —
and instantly see whether the village is "covered", "at risk", or "critical". It turns the
scattered facts reported by Executive Engineer Karunakaran into a single tamper-evident log.

## WHY THIS MATTERS
The video's core message is rapid response under scarcity: a fixed stock of 50 rented
borewells must serve 44 villages without anyone going dry. That is a prioritisation problem.
The app codifies the rule "every village gets a minimum litres-per-household threshold"
so a human dispatcher cannot silently starve a village. It teaches the student how a simple
form plus a deterministic scoring rule becomes an operational tool.

## HOW TO BUILD
1. `pip install gradio pandas`
2. Define a `Village` dataclass and a rule-based `assess_status()` function.
3. Build a Gradio `Blocks` UI with inputs (village name, tanker count, litres delivered,
   households) and a `gr.Dataframe` output.
4. Persist submissions to a CSV so the 44-village roster survives restarts.

```python
def assess_status(litres, households, min_lpcd=40):
    lpcd = litres / max(households, 1)
    if lpcd >= min_lpcd:
        return "covered", round(lpcd, 1)
    if lpcd >= min_lpcd * 0.6:
        return "at risk", round(lpcd, 1)
    return "critical", round(lpcd, 1)
```

## WHEN TO USE IN PRODUCTION
Use it for emergency rural water-supply tracking, tanker dispatching, and drought relief
dashboards where connectivity is patchy and a lightweight single-process app is enough.
Do NOT use it when you need multi-user auth, high write concurrency, or hard audit trails
— swap Gradio for FastAPI plus a real database there.

## HOW IT HELPS STUDENTS
Students practise turning a real news statement into a typed data model, a testable
business rule, and a working UI in under 100 lines. They learn threshold logic, CSV
persistence, and the difference between a demo and an operational tool.

## STARTER CODE
See `starter/main.py` — a runnable Gradio skeleton with TODO markers for the persistence
layer, a per-village borewell coverage field, and validation.
