Riverview

RIVERVIEW

Applied Agentic AI and computer vision for traffic flow analysis and predictive modelling

Architecture

One camera, two local server processes, and a browser that talks to both of them directly. Everything here runs on one laptop.

The browser makes two independent local connections, not one proxied through the other: it loads the page shell from the Nitro server on :3000, then fetches every event, stat, and image directly from the FastAPI server on :8001. The two server processes never call each other — the only thing they share is the SQLite database and snapshots/ folder that detect_boats.py writes to. That's also why the backend has to accept browser requests from the dashboard's own local origin. The vision/OCR hop (amber, dashed) is the one optional, swappable step in the pipeline — everything else always runs.

Ports & processes

Running it — two terminals, one laptop

# Terminal 1 — backend
cd laptop/backend && source venv/bin/activate
python3 api.py

# Terminal 2 — frontend (already built)
cd laptop/frontend
npm run start

Then open http://localhost:3000/ — that's the dashboard. See the API quickstart below for the separate developer API on :8001.

Quickstart

A versioned, key-authed read API over Riverview's sighting data, under /api/v1/* on the same FastAPI process the dashboard already runs (http://127.0.0.1:8001).

Where things run

Two separate local processes, two separate addresses — don't mix them up:

They're on the same machine but different ports and, notably, different hostnames by convention: the dashboard is always referred to as localhost:3000, never 127.0.0.1:3000, matching the project README. Use 127.0.0.1 for the API as shown throughout this page.

Getting a key

Keys live locally, one key,label pair per line. Add a line yourself to issue a new key — no restart needed, the API rereads the file on every request. Delete a line to revoke one. Generate a key:

python3 -c "import secrets; print(secrets.token_hex(16))"

Then add it as a line, e.g. YOUR_API_KEY,my-laptop. The examples on this page use YOUR_API_KEY — swap in your own.

Your first call

curl http://127.0.0.1:8001/api/v1/stats \
  -H "X-API-Key: YOUR_API_KEY"

{"total_events": 214, "boat_count": 58, "person_count": 12, "manual_count": 3, "boat_passage_count": 41}

Every /api/v1/* route needs that same X-API-Key header. Missing or wrong key → 401. No keys configured at all → 503 (the error message tells you to add one).

Endpoints

Full parameter-by-parameter reference: API reference below, generated from the backend's OpenAPI spec. The interactive version (with "Try it out") is at http://127.0.0.1:8001/docs while the backend is running.

Pagination

limit (default 50, max 1000) and offset on /events, /boats, and /passages. Responses are bare JSON arrays — keep incrementing offset until a call returns fewer than limit results to know you've reached the end.

Errors

{"detail": "Missing or invalid X-API-Key header."}

Concepts

The generated reference tells you the shape of each response. This page explains what the data actually means, since that's what most confusion traces back to.

Events

An event is one processed camera frame (or one uploaded image). A frame with both a person and a boat in it is one event with two detections, not two — GET /api/v1/events groups rows this way, keyed by a shared timestamp.

Detections and their source

Every detection has a source: camera (the live ESP32 feed), upload (dropped into the dashboard's Upload tab), or manual (logged by a person, not YOLO-detected). All three run through the same pipeline — source just tells you how the image got in.

Boat analysis fields

When a boat is detected, it's optionally run through a vision-language model plus a dedicated OCR pass, producing:

Any of these can be null — either analysis wasn't enabled for that capture, or the model genuinely found nothing to report.

"Has marks" filtering

has_marks=true excludes more than empty values — vision models often answer with a full sentence ("No visible markings or text on the boat in the image provided") rather than a short "none," so the filter also excludes anything containing "no visible," plus a short exact-match list. It never counts a person-class detection as "having marks," even if that field happens to be populated on its row.

Boats — grouping repeat sightings

GET /api/v1/boats groups every boat detection with a real identifying_marks/ocr_text reading into one entry per distinct boat, by canonicalizing that text (lowercase, strip punctuation, collapse whitespace) into a signature. Crops too small to plausibly carry a reliable reading are excluded entirely rather than risking a false match. This mirrors the dashboard's own Track view, though it's a separate implementation kept close in behavior, not byte-identical.

Boat passages vs. raw detection counts

The camera pipeline logs a new boat-class detection roughly every 1-2 seconds while a vessel stays in frame, so a raw count of boat-class rows (get_stats()'s boat_count) substantially overcounts real boat traffic — one boat crossing frame can produce anywhere from a handful to dozens of rows.

GET /api/v1/passages and boat_passage_count on /api/v1/stats fix this by clustering boat detections into passages — one per real boat sighting — based on runs of closely-spaced timestamps whose bounding-box position steps in a consistent direction:

{
  "detection_ids": [611, 612, 613, 614],
  "start_timestamp": "2026-08-25T14:30:31",
  "end_timestamp": "2026-08-25T14:30:54",
  "event_count": 4,
  "direction": "rightward"
}

detection_ids are the raw rows stitched together; direction is rightward, leftward, or null for a single-detection passage. Two boats detected in the exact same frame are never merged into one passage, however close their positions — being in the same frame means they were seen simultaneously, so they can't be one boat sampled twice.

Confidence

confidence is the YOLO detection confidence (0–1) for camera/upload detections. Manual captures don't have one — stored as null in the database but returned as 1.0 here, since a manual log is a deliberate, fully-confident human observation, not an absence of information.

Changelog

Breaking changes get a new /v2 prefix, living alongside /v1 rather than replacing it. Additive changes — a new optional field, a new endpoint — land in the current version without a bump.

v1 — 2026-08-24

Initial release of the versioned, key-authed developer API, as a separate surface from the dashboard's own internal routes, which stay local-only and unchanged.

• GET /api/v1/events — filtered/searched/paginated detection events
• GET /api/v1/events/{timestamp} — single event lookup
• GET /api/v1/boats — boats grouped by identifying-marks signature (new — previously only available client-side in the dashboard's Track view)
• GET /api/v1/stats — summary counts
• X-API-Key header required on every /api/v1/* route, checked against your local key file

v1 — 2026-08-26 (additive)

Boat-passage stitching, fixing a monitor-agent finding that raw boat-class detection counts substantially overcount real boat traffic.

• GET /api/v1/stats — new boat_passage_count field: boat sightings clustered into passages, alongside the unchanged boat_count
• GET /api/v1/passages — new endpoint: the individual stitched passages behind boat_passage_count, paginated (new)

MCP server setup

Lets Claude query sightings, boats, and stats conversationally instead of you writing API calls by hand — a thin local wrapper over the developer API above.

1. Backend running

cd laptop/backend
source venv/bin/activate
python3 api.py

Leave this running — the MCP server has nothing to query without it.

2. Install the MCP server

cd laptop/mcp_server
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

3. Sanity check

CVP_API_KEY=YOUR_API_KEY python3 server.py --list-tools

- list_events: List detection events (one per processed frame, newest first).
- get_event: Get one event by its exact timestamp (as returned by list_events),
- list_boats: List distinct boats, grouped by a canonicalized identifying-marks/
- get_stats: Summary counts: total events, and counts by class (boat/person/manual).
- list_boat_passages: List boat sightings stitched into passages -- one per real boat
- get_last_run: Most recent finding's timestamp across every past monitor-agent run.
- record_finding: Record one monitor-agent finding, pending human approval.

If this fails, the backend isn't reachable or the key doesn't match a line in your local key file — fix that before wiring up Claude Desktop.

4. Wire it into Claude Desktop / Claude Code

{
  "mcpServers": {
    "river-watcher": {
      "command": "/absolute/path/to/laptop/mcp_server/venv/bin/python3",
      "args": ["/absolute/path/to/laptop/mcp_server/server.py"],
      "env": {
        "CVP_API_BASE": "http://127.0.0.1:8001/api/v1",
        "CVP_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Restart Claude Desktop (fully quit, not just close the window) — or start a new Claude Code session — after editing the config.

5. Worked example

Seven tools. Five are read-only over detection data: list_events, get_event, list_boats, get_stats, list_boat_passages. Two back the Agentic Monitor: get_last_run (read) and record_finding — the one write, which only appends to the separate findings log (see Tools reference). There's deliberately no tool to edit, delete, or upload detections — those stay dashboard-only.

Tools reference

Assumes the server from Server setup is already wired up. Every tool here is a thin wrapper over one call to the developer API above — same data, same pagination, same field meanings (see Concepts for what a field actually means). All tools are read-only against real detection data, except record_finding — a narrow write path for the Agentic Monitor's own append-only findings log, explained below.

Sighting & stats tools

list_events

list_events(class_filter="all", q="", has_marks=False, limit=50, offset=0)

Detection events (one per processed camera frame or upload), newest first. Wraps GET /api/v1/events.

get_event

get_event(timestamp: str)

One event by its exact timestamp (as returned by list_events), e.g. get_event("2026-08-21T10:05:00"). Wraps GET /api/v1/events/{timestamp}.

list_boats

list_boats(limit=50, offset=0)

Distinct boats, grouped by a canonicalized identifying-marks/OCR signature, most-recently-seen first. Wraps GET /api/v1/boats — see Concepts for how the signature is computed.

get_stats

get_stats()

Summary counts, including boat_passage_count (real boat sightings, track-stitched). Wraps GET /api/v1/stats.

{"total_events": 214, "boat_count": 58, "person_count": 12, "manual_count": 3, "boat_passage_count": 41}

Prefer boat_passage_count over boat_count for anything about real boat traffic — boat_count is raw per-frame detections.

list_boat_passages

list_boat_passages(limit=50, offset=0)

Boat sightings stitched into passages — one per real boat, not one per detected frame — most-recent first. Wraps GET /api/v1/passages.

{
  "detection_ids": [611, 612, 613, 614],
  "start_timestamp": "2026-08-25T14:30:31",
  "end_timestamp": "2026-08-25T14:30:54",
  "event_count": 4,
  "direction": "rightward"
}

Agentic Monitor tools (Phase 0)

Back the scheduled monitor agent — a fresh session each firing, with no memory of the last one. record_finding is the one write tool on this otherwise read-only server, deliberately narrow: it only ever appends a row to a separate agent_findings table and can never touch, edit, or delete a real detection row. A finding is always created status="pending" — a human approves or dismisses it on the Track page.

get_last_run

get_last_run()

The most recent finding's timestamp across every past run, or null if none has ever been recorded — how a fresh session knows where to pick up. Wraps GET /api/v1/findings/last.

{"timestamp": "2026-08-25T15:26:14"}

record_finding

record_finding(run_id, category, observation, evidence, proposed_action)

Records one finding from the current run, pending human approval. Wraps POST /api/v1/findings.