# Strong Room CCTV Integration & Audit Service

## PURPOSE
A backend integration service (SQLAlchemy + httpx) that pulls live camera-health
data from each strong-room's NVR/camera management API, persists it in a relational
database, and writes an immutable access-audit log every time security status is
read or changed. It is the persistence and integration layer behind the SP's
24-hour surveillance order: it answers "was camera X at centre Y recording at time
T, and who queried that fact?".

## WHY THIS MATTERS
The transcript describes an operational order — cameras installed for constant
surveillance, armed police for full-scale protection. Sustaining that over months
requires durable state and an audit trail, not a spreadsheet. This project teaches
**service integration with real accountability**: idempotent upserts from an
external API, a normalised schema (centre → camera → health_sample), and append-only
audit records that survive dispute.

## HOW TO BUILD
1. Define SQLAlchemy models: `Centre`, `Camera`, `HealthSample`, and `AuditLog`.
   Index `HealthSample` on `(camera_id, sampled_at)`.
2. Use httpx with a timeout and retry/backoff to poll each NVR's `/cameras` endpoint.
3. Upsert cameras and append health samples idempotently (skip if the last sample is
   unchanged) so re-runs don't corrupt counts.
4. Write an `AuditLog` row for every status transition and every read of a
   compliance endpoint.

Key snippet:
```python
import httpx
from sqlalchemy.orm import Session

def sync_centre(db: Session, base_url: str) -> int:
    resp = httpx.get(f"{base_url}/cameras", timeout=5.0)
    resp.raise_for_status()
    n = 0
    for c in resp.json()["cameras"]:
        cam = upsert_camera(db, c)
        if needs_new_sample(db, cam, c["status"]):
            db.add(HealthSample(camera_id=cam.id, status=c["status"],
                                sampled_at=utcnow()))
            db.add(AuditLog(action="status_change", camera_id=cam.id,
                            detail=c["status"]))
            n += 1
    db.commit()
    return n
```

## WHEN TO USE IN PRODUCTION
Use it as the system of record when many sites must be polled and audited — election
strong rooms, treasury vaults, evidence lockers — especially where an access trail is
legally required. Do NOT use it to store video (metadata only) and do not point it at
untested third-party APIs without timeouts and idempotency, or you will double-count
and lose the trail.

## HOW IT HELPS STUDENTS
Students learn ORM schema design, idempotent sync, resilient HTTP clients, and audit
logging — the integration skills backend teams hire for.

## STARTER CODE
See `starter/main.py` for SQLAlchemy models, an httpx sync function with a
deterministic stub transport, audit logging, and `# TODO` markers.
