# IMD Weather Alert Ingestion Service

## PURPOSE
An integration service (SQLAlchemy + httpx) that periodically polls an India Meteorological Department style forecast feed for Bhadradri Kothagudem district, stores each bulletin as an alert record, deduplicates repeats, and exposes the latest advisories to downstream subscribers. It is the persistence and fan-out layer behind the news bulletin's promise: "light rains may occur in several places... farmers should be very alert."

## WHY THIS MATTERS
Real warnings are not one-off messages — they are records that must be received reliably, stored with provenance, and delivered to the right people. The transcript shows an official announcement flowing from IMD to officials to farmers; this project teaches the plumbing of that chain: authenticated fetch, resilient retries, idempotent storage, and audit-friendly rows.

## HOW TO BUILD
1. Define SQLAlchemy models `SourceFeed`, `Alert` (district, level, rain_mm, thunder, issued_at, source_url) with a uniqueness constraint on `(source_url, issued_at)` for idempotency.
2. Use httpx with timeouts and retry/backoff to poll a `--source` URL; map the JSON/plain-text bulletin into an `Alert`.
3. Upsert alerts by ignoring duplicates, then expose `subscribe`/`dispatch` hooks that push new alerts to registered farmers/offices.

```python
from sqlalchemy import create_engine, UniqueConstraint
from sqlalchemy.orm import declarative_base, Mapped, mapped_column

Base = declarative_base()

class Alert(Base):
    __tablename__ = "alerts"
    __table_args__ = (UniqueConstraint("source_url", "issued_at", name="uq_alert"),)
    id: Mapped[int] = mapped_column(primary_key=True)
    district: Mapped[str]
    level: Mapped[str]
    rain_mm: Mapped[float]
    issued_at: Mapped[str]
    source_url: Mapped[str]
```

## WHEN TO USE IN PRODUCTION
Use it as a scheduled ingestion worker (cron/Airflow) behind a district agriculture portal, or as middleware feeding SMS/app push to farmers. Do NOT use it as the source of truth for the forecast itself, for high-frequency nowcasting feeds, or where you lack authority to redistribute the agency's data — respect licensing and always credit IMD.

## HOW IT HELPS STUDENTS
Students learn ORM modelling, uniqueness/idempotency, HTTP client best practices (timeouts, retries), separating fetch from persistence, and designing for auditability. These are exactly the skills demanded by integration/auth and data-pipeline roles.

## STARTER CODE
See `starter/main.py` for SQLAlchemy models, an httpx poller with a deterministic stub, an idempotent upsert, and `# TODO` markers for auth headers and dispatch.
