# Indiramma Beneficiary Registry Service (SQLAlchemy + httpx)

## PURPOSE
A persistent service tier for Indiramma housing records: a SQLAlchemy schema for
applicants, sanctions, and handovers, plus an `httpx` client that syncs records with
the state housing portal. The transcript says the administration selects beneficiaries
"in a transparent manner and provide[s] housing as quickly as possible" — this project
is the system of record that makes both claims checkable, because every status change
is stored, timestamped, and reconcilable against the upstream registry.

## WHY THIS MATTERS
Welfare schemes lose public trust when local records and state records disagree.
Indiramma allocations flow through districts, but the citizen sees one status. A
registry with explicit state transitions (`application -> sanctioned -> under_construction
-> handed_over`) and an idempotent sync job means a family's queue position is the
same in every office. When "financial difficulties arise," the registry also shows
exactly which sanctions were deferred and why — a record that protects both the
citizen and the administrator.

## HOW TO BUILD
1. `pip install sqlalchemy httpx pydantic`.
2. Declare `Applicant`, `Sanction`, `Handover` models with a `status` transition log.
3. Build a session factory bound to SQLite for dev, Postgres for prod.
4. Write an `httpx.Client` wrapper with retry/backoff and a request idempotency key.
5. Implement `sync_district()`: fetch remote statuses, apply only forward transitions.
6. Add a reconciliation command that lists records that disagree with the portal.

Key snippet:

```python
def sync_district(session, client, district: str) -> dict:
    remote = client.get(f"/beneficiaries?district={district}").json()
    changed = 0
    for item in remote:
        row = session.get(Applicant, item["aadhaar_hash"])
        if row and STATUS_ORDER[item["status"]] > STATUS_ORDER[row.status]:
            row.status = item["status"]          # forward-only transition
            session.add(StatusChange(applicant_id=row.aadhaar_hash,
                                     to_status=item["status"]))
            changed += 1
    session.commit()
    return {"district": district, "updated": changed}
```

## WHEN TO USE IN PRODUCTION
Use it as the back-office registry behind the intake API and the dashboard, and as the
nightly reconciliation job against state systems. Use it when you need auditable state
history. Do NOT use an ORM service for high-volume streaming telemetry from construction
sites — that belongs in a time-series store. Do NOT let a sync job move records backwards;
always require an explicit human correction path.

## HOW IT HELPS STUDENTS
Students practise schema design with a real state machine, session lifecycle management,
idempotent HTTP integrations, retry policy, and reconciliation reporting — the skeleton of
any enterprise integration role.

## STARTER CODE
See `starter/main.py` — SQLAlchemy models, an httpx client with a deterministic stub
transport, forward-only sync logic, and `# TODO` markers.
