# Kakinada Port Road Pothole Report API

## PURPOSE
A FastAPI service that lets commuters, workers and locals report potholes on the
main road running from Kumbhabhishekam Port in Kakinada towards the tidal area.
The video shows that large potholes on this route have become a major obstacle to
traffic, forcing hundreds of two-wheeler workers heading to nearby industries to
face accidents. This project turns those scattered complaints into structured,
trackable reports with severity scores and a status workflow.

## WHY THIS MATTERS
Local news clips like this one are the raw signal citizens need to convert into
accountable action. The transcript does not describe any software — it describes a
gap: residents "urging officials to immediately repair the road." This project
teaches how to model that gap as an API: intake, validation, severity
classification, and a repair-status lifecycle, so a civic body can act on evidence
instead of anecdotes.

## HOW TO BUILD
Use FastAPI with Pydantic models for validation and an in-memory store first.
1. `pip install fastapi uvicorn pydantic`
2. Model a report with location, severity, hazard type and reporter role.
3. Add a deterministic severity rule (e.g. pothole depth + two-wheeler share).
4. Expose `POST /reports`, `GET /reports`, `PATCH /reports/{id}/status`.
5. Run `uvicorn starter.main:app --reload`.

Key idea — deterministic severity scoring instead of an LLM call:

```python
def score_severity(depth_cm: float, two_wheeler_traffic_pct: float) -> int:
    """Return 1..5 from measurable inputs. No model, fully reproducible."""
    raw = (depth_cm / 4.0) + (two_wheeler_traffic_pct / 25.0)
    return max(1, min(5, round(raw)))
```

## WHEN TO USE IN PRODUCTION
Use it as the intake layer for a municipal grievance portal, a road-safety app, or
a district-collector escalation dashboard where reports must be auditabie and
routed. Do NOT use it when you need real GPS map rendering or offline field
capture — pair it with a mobile client and a Postgres/SQLAlchemy store. It is not a
replacement for an official complaint register with legal standing.

## HOW IT HELPS STUDENTS
Students learn HTTP contract design, Pydantic validation, status lifecycle
modelling, and how to convert a news observation into a shippable service. They
practise deterministic business rules before reaching for AI, and gain familiarity
with the API layer that every production civic system needs.

## STARTER CODE
See `starter/main.py` — a runnable FastAPI skeleton with endpoints, an in-memory
store, deterministic severity scoring and `# TODO` markers for persistence and
authority routing.
