# P4 — Inspector Assignment & Facility Sync Service (SQLAlchemy + httpx)

## PURPOSE
A backend service that tracks which official is assigned to inspect which polling station
and keeps a local database in sync with a state election-portal API. In the video the
Additional Commissioner Satyaveni personally inspected the 18 stations at Chandrampalem
High School in the Madhurawada zone, then issued orders on drinking water, power, and
ramps. This project models the same chain: assign officers, record findings, and push each
station's readiness status upstream — and pull the canonical station list back down — so
the field and the portal never disagree.

## WHY THIS MATTERS
Inspection data only helps if it reaches the authority that can act. A sync service with a
durable database is what turns scattered observations into a governance record, and what
lets a control room re-run a sweep tomorrow without re-keying everything.

## HOW TO BUILD
1. Install deps from `requirements.txt`.
2. Define SQLAlchemy models: `Station`, `Officer`, `Assignment`, `FacilityFinding`.
3. Add a repository layer with `create_assignment()` and `record_finding()`.
4. Use `httpx.Client` (with a timeout and retry) to `POST` readiness upstream and `GET`
   the station list; wrap in try/except so a portal outage never blocks the field.
5. Drive it from `python starter/main.py`, which seeds one station and prints sync result.

Key snippet:
```python
def sync_readiness(client, station):
    payload = {"station_id": station.id, "ready": station.is_ready()}
    try:
        r = client.post("/readiness", json=payload, timeout=5.0)
        r.raise_for_status()
        return r.status_code
    except httpx.HTTPError as exc:      # offline-tolerant by design
        return f"queued: {exc.__class__.__name__}"
```

## WHEN TO USE IN PRODUCTION
Use when multiple agencies share station data, when offline field capture must reconcile
later, or when an internal compliance DB feeds an external portal — inspections, asset
audits, health checks. Do NOT make an external API the source of truth for your own
records; the local DB should win. Do NOT implement retries without idempotency keys, or
you will double-post findings.

## HOW IT HELPS STUDENTS
Students learn ORM modelling, session management, resilient HTTP integration, and the
offline-first sync pattern that every serious backend eventually needs.

## STARTER CODE
`starter/main.py` wires the models, an in-memory SQLite engine, and a deterministic
httpx call stub, with `# TODO` markers for migrations, auth, and retry logic.
