# Weather Bulletin Ingestion Service (SQLAlchemy + httpx)

## PURPOSE
A small integration service that pulls the Meteorological Department's district
rainfall bulletin over HTTP with httpx and persists it into a relational database
with SQLAlchemy. It targets exactly the shape of the video's report: a district
(West Godavari), a set of mandals, and a 24-hour rainfall figure per mandal, with
Koyyalagudem at the 24 mm peak. The service deduplicates repeated bulletins so the
same day's numbers are not double-counted.

## WHY THIS MATTERS
Local news gives you a fact once; production systems need that fact stored, keyed,
and repeatable. This project is about the unglamorous connective tissue — fetching
from an unreliable upstream, validating the payload, and writing idempotently — which
is where most real integration bugs live.

## HOW TO BUILD
Define `Mandal` and `RainfallReading` models with a unique constraint on
`(mandal_id, observed_date)` so re-ingestion is safe. Use `httpx.Client` for the
fetch, check the status code, and parse JSON into Pydantic objects. Wrap the write in
a session with an upsert: query for an existing row, update it, otherwise insert.

Key snippet:

```python
import httpx
from sqlalchemy.orm import Session

def ingest(client: httpx.Client, session: Session, url: str, observed_date: str) -> int:
    resp = client.get(url, timeout=10.0)
    resp.raise_for_status()
    payload = resp.json()
    for row in payload.get("mandals", []):
        existing = (session.query(RainfallReading)
                    .filter_by(observed_date=observed_date, mandal=row["mandal"])
                    .one_or_none())
        if existing:
            existing.millimeters = row["millimeters"]
        else:
            session.add(RainfallReading(observed_date=observed_date, **row))
    session.commit()
    return len(payload.get("mandals", []))
```

## WHEN TO USE IN PRODUCTION
Run it on a schedule (cron, APScheduler, Airflow) to build a historical rainfall
archive for irrigation and crop advisories. Add retry-with-backoff and an API key.
Do NOT use it for real-time flood warning, where a 24-hour batch lag is too slow.
Do NOT poll an upstream endpoint you have no permission to use.

## HOW IT HELPS STUDENTS
Students practice ORM modelling, unique constraints for idempotency, HTTP timeouts,
and error handling — the practical core of a backend data-integration job.

## STARTER CODE
See `starter/main.py` for the SQLAlchemy models, an httpx fetch with a deterministic
stub fallback, an idempotent upsert, and `# TODO` markers for retries and migrations.
