> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cargovision.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cargovision.app/_mcp/server.

# Architecture

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

| Service                               | Role                                                                                                                                           |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Edge AI service**                   | Runs 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.                                      |

```mermaid
flowchart TB
  CAM[RTSP cameras] --> EDGE[Edge AI service]
  EDGE -- "HTTPS + X-API-Key<br />/v1/edge/containers/*" --> API[REST API<br />api.cargovision.app]
  API --> DB[(Inspection records)]
  WEB[Web dashboard] -- "HTTPS + JWT<br />/v1/*" --> API
  MOBILE[Mobile app] -- "HTTPS + JWT<br />/v1/*" --> API
  EDGE -- "WebSocket<br />annotated video" --> WEB
```

## 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](/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](/changelog) records contract changes.