# Indiramma Housing Beneficiary Intake API (FastAPI)

## PURPOSE
A FastAPI service that receives Indiramma housing scheme applications from eligible poor
families in Telangana and returns an eligibility decision plus a queue token. The transcript
states the government wants "a home for every eligible poor family in Telangana" and has
"taken steps to select beneficiaries in a transparent manner." This API turns that promise
into code: an application endpoint, a rules engine, and an auditable decision log so no
house is allocated behind closed doors.

## WHY THIS MATTERS
Welfare schemes fail at the intake desk, not at the press conference. The video stresses
"no question of taking a step back in implementing welfare schemes, even if financial
difficulties arise." That means the system must keep accepting and recording applications
even when the sanction budget is short. This project teaches request validation, deterministic
business rules, priority queuing, and immutable audit trails — the parts of a welfare platform
that citizens actually experience.

## HOW TO BUILD
1. `pip install fastapi uvicorn pydantic` (student environment only).
2. Define a Pydantic model for applicants: name, Aadhaar hash, district, annual income,
   existing house flag, family size.
3. Implement `evaluate_eligibility()` as a pure function returning an enum + reason codes.
4. Expose `POST /apply`, `GET /applications/{token}`, `GET /queue/summary`.
5. Append every decision to an append-only audit list (swap for a DB later).

Key snippet:

```python
@app.post("/apply", response_model=IntakeResponse)
def apply(app: Applicant) -> IntakeResponse:
    decision = evaluate_eligibility(app)
    token = issue_token(app.district, decision)
    audit.append({"token": token, "decision": decision.status,
                  "reasons": decision.reasons, "ts": time.time()})
    return IntakeResponse(token=token, status=decision.status,
                          reasons=decision.reasons)
```

## WHEN TO USE IN PRODUCTION
Use it as the public intake tier behind a government portal, an SMS/IVR gateway, or a
village-level data-entry kiosk. It fits when rules are auditable and deterministic. Do NOT
use a stateless API alone when you need document verification, biometric matching, or
grievance escalation — those belong in downstream services. Never store raw Aadhaar; hash
and salt it.

## HOW IT HELPS STUDENTS
Students practise production API design: typed schemas, pure rule functions, idempotent
token issuing, structured audit logging, and FastAPI dependency injection. They learn why
"transparent selection" is an engineering property, not a slogan.

## STARTER CODE
See `starter/main.py` — a working FastAPI app with an in-memory store, rule engine,
deterministic stub for the state-registry lookup, and `# TODO` markers.
