# West Godavari Layout Compliance Dashboard

## PURPOSE
A **Streamlit + Plotly** dashboard that visualises plot-layout compliance across West
Godavari district panchayats, centred on the mandatory 10% social-space rule from the news
report. It shows, per panchayat, how many layouts breach the rule, the distribution of
reserved social space against the legal 10% line, and an estimate of the revenue the
panchayats lose when developers sell whole parcels as plots without leaving that space. The
goal is a single screen an official or journalist can open to see the scale of the problem.

## WHY THIS MATTERS
The transcript describes a district-wide regulatory failure — "numerous illegal layouts"
across "major panchayats" — and the resulting revenue shortfall. That is a geographic and
comparative story, and a table hides it. A dashboard makes the pattern legible instantly:
which panchayats are worst, how far below 10% the typical layout sits, and roughly how much
money is at stake. This project teaches turning raw compliance records into an argument.

## HOW TO BUILD
1. Load layouts into a Pandas frame (skeleton uses a seeded synthetic generator; TODO is a
   real CSV upload or a `httpx` pull from the registry).
2. Derive `social_space_pct`, `shortfall_sqm`, `est_revenue_loss_inr`, and a `compliant` flag.
3. Add sidebar filters for panchayat and a "non-compliant only" toggle.
4. Show headline metrics with `st.metric`.
5. Build a Plotly bar chart of loss by panchayat and a histogram of reserved percentages
   with a vertical line marking the 10% minimum.
6. Render the full register as a sortable `st.dataframe`.

Key snippet:

```python
fig_hist = px.histogram(view, x="social_space_pct", nbins=20,
                        title="Distribution of reserved social space (%)")
fig_hist.add_vline(x=10.0, line_dash="dash", line_color="red",
                   annotation_text="10% legal minimum")
st.plotly_chart(fig_hist, use_container_width=True)
```

## WHEN TO USE IN PRODUCTION
Great for official review meetings, public transparency portals, press briefings, or a
monitoring tab in a district IT system. Do **not** use it as the approval authority — the
dashboard reports, the checker decides. And do not ship it publicly until the synthetic
dataset is replaced with audited figures, or the loss numbers will be mistaken for official.

## HOW IT HELPS STUDENTS
Students learn data transformation with Pandas, declarative charting with Plotly, interactive
caching (`st.cache_data`), and how to present civic data honestly — labelling estimates as
estimates. These are directly transferable to any analytics role.

## STARTER CODE
`starter/main.py` includes the cached data loader, derived compliance columns, sidebar
filters, metrics, two Plotly figures, and the register table, with `# TODO` markers for real
ingestion and CSV export.
