Skip to navigation
Get started

Architecture

How the edge device, REST API, and dashboard work together.
View as Markdown

Cargovision is made of three services with two deliberately separate data channels.

ServiceRole
Edge AI serviceRuns at the gate. Reads RTSP camera streams, runs YOLO detection and OCR, groups detections into scan sessions, and pushes results to the API.
REST API (api.cargovision.app)The central data layer. Authenticates users and devices, grades scan results, stores containers, and serves them to clients.
Web dashboard (cargovision.app)The operator experience: live monitoring, inspection history, review queues, reports, and administration.
HTTPS + X-API-Key/v1/edge/containers/* HTTPS + JWT/v1/* HTTPS + JWT/v1/* WebSocketannotated video RTSP cameras Edge AI service REST APIapi.cargovision.app Inspection records Web dashboard Mobile app

Channel 1: structured inspection data

The edge device sends results to the REST API over HTTPS with an API key. Writes are per scan session, not per frame: the edge accumulates detections across frames and sends one request when the session completes.

  1. OCR reads a container number from a camera frame.
  2. The number must stay stable across several frames before it is accepted.
  3. Defect and category scans run for the same container session.
  4. The edge sends POST /v1/edge/containers/identify, then POST /v1/edge/containers/{containerNumber}/scans/defect and .../scans/category.
  5. The API grades the raw detections, updates the container, and makes the result available to the dashboard and reports.

The edge sends raw detections only: class name, confidence, and bounding box. Severity, structural integrity, and the AI decision are always computed by the API. See Inspection lifecycle.

Channel 2: live video

Annotated video frames travel directly from the edge device to the dashboard over WebSocket. The REST API does not relay video, and the REST API and its SDKs have no video endpoints.

Manual uploads

When no edge device is running, operators can upload images through the dashboard. Those requests go to the JWT-authenticated POST /v1/containers/{id}/scans/* endpoints, and the API calls the AI service on the operator’s behalf. Edge ingestion remains the primary production path.

Versioning

All REST routes are served under /v1, which leaves room for a future API version to run alongside it. The changelog records contract changes.