# Suspect Remand & Custody Tracking Service with District Sync

## PURPOSE
A SQLAlchemy-backed service that records every arrest made in a kidnapping case and tracks
each suspect through custody: time of arrest, the police station holding them, the remand
date, and the court reference. When a case spans jurisdictions — as this one did, with the
victim recovered in Palnadu district while the FIR sat at a Vijayawada station — it pushes
signed custody events to the neighbouring district unit over httpx so both forces see the
same status instead of relying on phone calls.

## WHY THIS MATTERS
The transcript's closing fact is procedural and easy to under-rate: "the four suspects
involved in this kidnapping were also immediately arrested by the police and sent to
remand." Remand is where due-process discipline lives. Illegal or unrecorded custody is
what loses cases. This project teaches that arrest and remand are state machines with legal
deadlines, and that those deadlines must be enforced in code, not memory.

## HOW TO BUILD
1. Declare SQLAlchemy 2.0 models: `Case`, `Suspect`, `CustodyEvent` with proper FKs and a
   `custody_started_at` / `remand_due_at` pair.
2. Wrap writes in a session factory (`sessionmaker`) and one transaction per event.
3. Add a rule that flags any suspect approaching the statutory remand deadline.
4. Use httpx `Client` with a timeout and retry to POST custody events to a district
   endpoint; the endpoint is stubbed in tests via `httpx.MockTransport`.

```python
def file_remand(session, suspect_id, court_ref):
    suspect = session.get(Suspect, suspect_id)
    suspect.status = "remanded"
    session.add(CustodyEvent(suspect_id=suspect_id, kind="remand_filed", note=court_ref))
    session.commit()
    return suspect
```

## WHEN TO USE IN PRODUCTION
Use it for inter-district case coordination, prison/remand handoff ledgers and audit-ready
custody logs. Do NOT use it as a court record of itself, and never sync unredacted PII
between agencies without a legal data-sharing agreement.

## HOW IT HELPS STUDENTS
Students get real ORM modelling, transaction handling, compliance deadlines encoded as
tests, and resilient HTTP integration (timeouts, retries, idempotency keys) — the everyday
work of a backend or govtech engineer.

## STARTER CODE
`starter/main.py` provides models, a session factory, `arrest`/`file_remand`/`sync_case`,
an httpx client with retry stub and `# TODO` markers for Alembic migrations.
