# Telangana Indiramma Housing Progress Dashboard (Streamlit + Plotly)

## PURPOSE
An interactive dashboard that shows Indiramma housing delivery across Telangana
districts: applications received, sanctions issued, houses under construction,
and families handed a home. The transcript says the government is "prepared to
realize the dream of owning a home for every eligible poor family" and is providing
housing "as quickly as possible" — this dashboard turns those statements into
visible, filterable numbers that any citizen or official can inspect.

## WHY THIS MATTERS
Public welfare claims should be verifiable at a glance. The video also states there
is "no question of taking a step back" in welfare implementation, even when
financial difficulties arise. A dashboard is how that resolve is audited month over
month: if the under-construction count flatlines while sanctions rise, the
pipeline is blocked, and anyone can see it. Visual accountability is the cheapest
anti-corruption tool a scheme has.

## HOW TO BUILD
1. `pip install streamlit plotly pandas`.
2. Load a district-level CSV into a cached Pandas frame with `@st.cache_data`.
3. Build a sidebar with district multiselect and a reporting-month slider.
4. Render a Plotly grouped bar of applications vs. sanctions per district.
5. Add a stacked area chart of pipeline stage over time (a funnel-to-handover view).
6. Show a KPI row: total sanctioned, total handed over, median days to handover.

Key snippet:

```python
@st.cache_data(ttl=600)
def load(path: str) -> pd.DataFrame:
    df = pd.read_csv(path, parse_dates=["month"])
    return df

df = load(DATA_PATH)
districts = st.sidebar.multiselect("District", sorted(df["district"].unique()),
                                   default=sorted(df["district"].unique())[:6])
view = df[df["district"].isin(districts)]
fig = px.bar(view, x="district", y=["applications", "sanctioned", "handed_over"],
             barmode="group", title="Indiramma delivery by district")
st.plotly_chart(fig, use_container_width=True)
```

## WHEN TO USE IN PRODUCTION
Use it as a public transparency portal, an internal review screen for a district
collector, or a monthly newsletter embed. It fits wherever a read-only, near-real-time
aggregate view is enough. Do NOT use a dashboard for transaction entry or approval —
that needs a form and a workflow. Do NOT put personally identifiable citizen data on a
public Streamlit page; aggregate to district and month.

## HOW IT HELPS STUDENTS
Students learn cached data loading, declarative charting with Plotly Express, dashboard
layout and KPI composition, and the discipline of aggregating privacy-sensitive data
before publishing — all directly reusable for civic-tech and BI work.

## STARTER CODE
See `starter/main.py` — a Streamlit app with cached loading, sidebar filters, KPI metrics,
a Plotly grouped bar and stacked area, and a deterministic sample-data fallback.
