# Narsampet Festival Crowd Advisory API (FastAPI)

## PURPOSE
Warangal police issued an advance advisory urging people to stay extremely alert in
crowded markets and malls during Dasara and Diwali, and instructed festival organizers to
make mandatory advance security arrangements with emergency exits always ready. This
project builds a small FastAPI service that stores and serves those advisories and
crowd-density alerts to organizers and the public, so warnings can be issued *before* a
stampede risk materializes.

## WHY THIS MATTERS
The transcript's core idea is **advance warning as prevention**: warnings are issued
ahead of the festive rush specifically to avoid stampedes and tragic accidents. That is a
classic API design problem — publish structured advisories, expose them over HTTP, and let
downstream apps fan them out. You learn request validation, response schemas, and
serve-your-model boundaries.

## HOW TO BUILD
1. `pip install fastapi uvicorn pydantic` (locally; do not install during generation).
2. Define Pydantic models: `Advisory`, `ZoneDensity`, `OrganizerChecklist`.
3. Hold state in an in-memory dict keyed by zone name; later swap for SQLAlchemy.
4. Expose `GET /advisories`, `POST /advisories`, `GET /zones/{zone}/risk`.
5. Compute a simple risk score from density vs. safe capacity — deterministic stub
   stands in for any ML model.

Key snippet:
```python
@app.post("/advisories", response_model=Advisory)
def create_advisory(a: Advisory) -> Advisory:
    advisories.append(a)
    return a

@app.get("/zones/{zone}/risk")
def zone_risk(zone: str, people: int, capacity: int):
    ratio = people / max(capacity, 1)
    return {"zone": zone, "risk": "HIGH" if ratio > 0.9 else "OK"}
```

## WHEN TO USE IN PRODUCTION
Use it when a municipal/police cell must push advisories to multiple clients (SMS
gateways, apps, notice boards) and needs one authoritative source. Do **not** use it as a
real-time safety-critical evacuation system — a single in-process service has no
redundancy and cannot be the sole channel in a life-safety event. Also skip it when
advisories are one-off PDFs with no machine consumers.

## HOW IT HELPS STUDENTS
You practice the full web-service loop: schema design, validation, routing, and separating
a deterministic risk stub from a future model. It mirrors how government advisories become
APIs, and gives a portfolio-ready, end-to-end FastAPI app grounded in a real local news
story.

## STARTER CODE
See `starter/main.py` for the FastAPI app skeleton with in-memory stores and `# TODO`
markers for persistence and authentication.
