# P5 — Polling Station Readiness Dashboard (Streamlit + Plotly)

## PURPOSE
An interactive dashboard that gives a control room a single view of polling-station
readiness. The video describes the Additional Commissioner inspecting the 18 stations at
Chandrampalem High School in the Madhurawada zone and insisting that drinking water,
continuous power, and ramps for the elderly and disabled be in place. This dashboard plots
each station's status against those three facilities so a supervisor can see, at a glance,
which sites are fully ready and which still have gaps before polling day.

## WHY THIS MATTERS
A readiness inspection produces a list; a dashboard produces a decision. Turning checklists
into a visual traffic-light view is how managers triage — they act on the red stations
first. This project teaches the last mile of any data pipeline: making the result legible
to the person who must act on it.

## HOW TO BUILD
1. Install deps from `requirements.txt`.
2. Build a Pandas DataFrame of stations with boolean facility columns.
3. Add a sidebar filter for zone and a multiselect for facility.
4. Draw a Plotly stacked/heatmap or grouped bar of readiness; colour gaps red.
5. Show headline metrics with `st.metric` (total, ready, gaps).
6. Run `streamlit run starter/main.py`.

Key snippet:
```python
st.metric("Stations ready", ready_count, f"{ready_count}/{len(df)}")
fig = px.bar(zone_summary, x="zone", y=["water_ok", "power_ok", "ramp_ok"], barmode="group")
st.plotly_chart(fig, use_container_width=True)
```

## WHEN TO USE IN PRODUCTION
Use for live operational visibility during a readiness drive, for review meetings, and for
any recurring audit where stakeholders need self-serve filtering rather than a static PDF.
Do NOT use it as the system of record — a dashboard reads data, it should not be the only
copy. Do NOT put a slow query behind every widget; pre-aggregate so the page stays
responsive, and avoid exposing sensitive station data without access control.

## HOW IT HELPS STUDENTS
Students learn Streamlit layout, Plotly chart building, caching, and the discipline of
designing for a non-technical operator — a direct bridge from analysis to action.

## STARTER CODE
`starter/main.py` builds the sample DataFrame, renders metrics, a zone summary chart, and a
per-station table, with `# TODO` markers for real data sources and caching.
