# Kakinada Grievance Escalation Service

## PURPOSE
A SQLAlchemy-backed service that stores pothole grievances for the main road from
Kumbhabhishekam Port in Kakinada towards the tidal area and escalates them when
they are not acted on. It is the accountability engine behind the transcript's
closing line: locals urging officials to repair the road "before any loss of life
occurs." Each ticket carries a deadline; an httpx client posts escalation notices
to an upstream authority endpoint when the deadline passes.

## WHY THIS MATTERS
Filming a pothole creates attention, not repair. The missing piece is a system that
remembers, tracks a resolution deadline and pushes a reminder to the responsible
authority. This project teaches durable persistence, SLA modelling and outbound
integration — the components that turn a complaint into a tracked obligation.

## HOW TO BUILD
Use SQLAlchemy for the ORM and httpx for the outbound escalation call.
1. `pip install sqlalchemy httpx`
2. Define `Grievance` (segment, depth, reports, created_at, sla_due, status).
3. Add an SLA policy: severity 5 gets 24h, severity 3 gets 72h, else 7 days.
4. Write `find_overdue(session, now)` and `escalate(client, grievance)`.
5. Wire a small `main()` that opens a SQLite session, seeds rows and escalates.

Key escalation call:

```python
resp = client.post(
    ESCALATION_ENDPOINT,
    json={"grievance_id": g.id, "authority": g.authority, "overdue_hours": hours},
    timeout=10.0,
)
resp.raise_for_status()
g.status = "escalated"
```

## WHEN TO USE IN PRODUCTION
Use it when a civic body or NGO needs auditable complaint tracking with real
deadlines and integration to an official portal or SMS gateway. Do NOT use it as a
public-facing app without adding auth, rate limiting and a PII review — grievance
data includes reporter details. It assumes a reachable authority endpoint; when
none exists, run it in "dry-run" mode that only writes audit rows.

## HOW IT HELPS STUDENTS
Students learn schema and ORM design, time-based policy logic, idempotent outbound
integration, and how to write a service that survives restarts. They see why
deadlines matter in software and how to keep an audit trail.

## STARTER CODE
See `starter/main.py` — SQLAlchemy models, an SLA policy function, a seeded SQLite
session, and an httpx escalation call with `# TODO` markers for retries and
dry-run mode.
