# P1 — Polling Station Readiness Inspection API (FastAPI)

## PURPOSE
This project builds a small FastAPI service that records and verifies the readiness of
polling stations ahead of election day, mirroring the real inspection described in the
video: the Additional Commissioner personally checked the 18 polling stations at
Chandrampalem High School in the Madhurawada zone for drinking water, continuous power,
and ramps for elderly and disabled voters. The API lets field officers file a facility
checklist per station, flags any station that fails a mandatory facility, and returns a
zone-level readiness summary so officials can act before voters arrive.

## WHY THIS MATTERS
The transcript shows election machinery performing a grassroots-level readiness audit and
issuing strict orders that water, power, and ramps be "perfectly prepared." That is
exactly a data-capture and compliance problem. This project teaches how to turn a paper
inspection into structured, queryable, enforceable records — the backbone of any
government readiness workflow.

## HOW TO BUILD
1. Create a virtualenv and install the pinned deps in `requirements.txt`.
2. Define Pydantic models for a `Station` and an `Inspection` (water, power, ramp booleans
   plus inspector name and timestamp).
3. Store records in an in-memory dict keyed by station id (swap for Postgres later).
4. Add endpoints: `POST /inspections`, `GET /stations/{id}`, `GET /zones/{zone}/readiness`.
5. Run `uvicorn starter.main:app --reload`.

Key snippet:
```python
@app.post("/inspections", response_model=Inspection)
def file_inspection(insp: Inspection):
    required = insp.water_ok and insp.power_ok and insp.ramp_ok
    store[insp.station_id] = insp
    return insp.model_copy(update={"ready": required})
```

## WHEN TO USE IN PRODUCTION
Use this pattern when multiple field officers must report against a fixed checklist and a
control room needs a live readiness view — election logistics, hospital inspections,
school safety audits. Do NOT use an in-memory dict for real deployments (data is lost on
restart); do NOT use this when a full off-the-shelf form/BI tool already covers the need,
or when writes must be formally audited and signed — add auth and an append-only log first.

## HOW IT HELPS STUDENTS
Students learn FastAPI routing, Pydantic validation, REST design, and translating a real
governance process into a testable service. It is a realistic first backend portfolio piece.

## STARTER CODE
See `starter/main.py` for a runnable skeleton with the models, in-memory store, and the
three core endpoints already wired, plus `# TODO` markers for persistence and auth.
