# West Godavari Mandal Rainfall Report API

## PURPOSE
This project builds a FastAPI service that ingests and serves the kind of rainfall
report described in the video: a district-wide bulletin where the Meteorological
Department records moderate rain across several mandals over a 24-hour window, with
the highest figure (24 mm) in Koyyalagudem mandal and other areas up to roughly 10 mm.
The API stores a per-mandal daily rainfall record and exposes endpoints to submit a
new reading, fetch a mandal's history, and get the district maximum for the day.

## WHY THIS MATTERS
The video shows how official local weather statistics are communicated: a named
district (West Godavari), named subdivisions (mandals like Koyyalagudem), a time
window ("over the past 24 hours"), and a peak value. Turning that narrative bulletin
into structured, queryable data is the first step toward any real flood, agriculture,
or irrigation monitoring system.

## HOW TO BUILD
Install FastAPI, Uvicorn and Pydantic. Define a Pydantic `RainfallReading` model with
mandal, millimeters and observed_at. Keep an in-memory store keyed by mandal (swap for
a database later). Add routes with FastAPI decorators and validate the district name
is West Godavari. Run it with `uvicorn starter.main:app --reload`.

Key snippet:

```python
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field

class RainfallReading(BaseModel):
    mandal: str
    millimeters: float = Field(ge=0.0, le=500.0)
    district: str = "West Godavari"

@app.post("/readings")
def add_reading(r: RainfallReading):
    store.setdefault(r.mandal, []).append(r)
    return {"status": "recorded", "mandal": r.mandal}
```

## WHEN TO USE IN PRODUCTION
Use it when a district office, agriculture extension, or newsroom needs a stable
HTTP contract for rainfall submissions and queries feeding dashboards or SMS alerts.
Do NOT use an in-memory store for real archives; move persistence to PostgreSQL. It
is overkill for a single static bulletin — a spreadsheet is enough there.

## HOW IT HELPS STUDENTS
Students practice schema validation, REST design, and separating verification from
storage — core backend skills — while working on a realistic civic-data domain.

## STARTER CODE
See `starter/main.py` for the runnable FastAPI skeleton with routes, a deterministic
seeded stub for an upstream weather feed, and `# TODO` markers for persistence and auth.
