# Festival Zone Crowd-Safety Dashboard (Streamlit + Plotly)

## PURPOSE
Warangal police issued an advance advisory because festival crowds pile into markets and
malls during Dasara and Diwali, raising stampede risk. Officers and event organizers need
one screen that shows which zones are filling up, where emergency exits are confirmed
ready, and which events still lack mandatory advance security. This Streamlit + Plotly
dashboard renders that view from a small crowd-report table and a set of organizer records.

## WHY THIS MATTERS
The advisory's whole logic is *see the risk early*. A dashboard turns scattered numbers
into a visual early-warning surface: a bar chart of occupancy vs. safe capacity instantly
separates calm zones from hotspots, and a status table exposes non-compliant organizers
before the event, not after. It teaches that a good visualization is itself a prevention tool.

## HOW TO BUILD
1. `pip install streamlit plotly pandas`.
2. Prepare `zones.csv` (`zone,footfall,capacity,exits_ready`) and `organizers.csv`
   (`organizer,festival,security_plan_submitted,exits_ready`).
3. Compute `occupancy = footfall / capacity`; color bars by risk band (>0.9 red, >0.7 amber).
4. Draw a Plotly grouped bar chart of footfall vs. capacity per zone.
5. Add a second Plotly figure: exit-readiness by zone (green/red).
6. List non-compliant organizers as a `st.dataframe` with a status column.

Key snippet:
```python
df["occupancy"] = df["footfall"] / df["capacity"].clip(lower=1)
colors = df["occupancy"].apply(lambda r: "#c0392b" if r > 0.9 else "#e67e22" if r > 0.7 else "#27ae60")
fig = px.bar(df, x="zone", y=["footfall", "capacity"], barmode="group")
st.plotly_chart(fig, use_container_width=True)
```

## WHEN TO USE IN PRODUCTION
Use it as the control-room or organizer-facing read-out during festival planning and on the
event day itself (refresh from a live feed). Great for briefing senior officers and for
post-festival review. Do **not** rely on it for life-safety alerts that need push
notifications or sub-second latency — Streamlit re-runs on interaction and is a read-out,
not an alerting bus. Skip it for one-off static reports where a PDF suffices.

## HOW IT HELPS STUDENTS
You learn data prep, deriving risk metrics, Plotly chart types, and Streamlit layout — the
standard data-app stack employers ask for — while telling a genuinely local, high-stakes
safety story.

## STARTER CODE
See `starter/main.py` for the Streamlit layout, deterministic demo data, both Plotly
figures, and `# TODO` markers for live ingestion and alerting.
