> 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.

# Inspection lifecycle

Each physical container is one inspection record, identified by its ISO 6346 container number (for example `MSCU1234566`). Edge endpoints address containers by this number. Dashboard endpoints address them by the record `id`, or by number through `GET /v1/containers/by-number/{containerNumber}`.

## Container statuses

```mermaid
stateDiagram-v2
  [*] --> IDENTIFIED
  IDENTIFIED --> VALIDATED
  VALIDATED --> INSPECTING
  INSPECTING --> ANALYZED
  ANALYZED --> CLEARED
  CLEARED --> RELEASED
  ANALYZED --> FLAGGED
  FLAGGED --> UNDER_REVIEW
  UNDER_REVIEW --> CLEARED: APPROVE
  UNDER_REVIEW --> HELD: REJECT or HOLD
```

| Status         | Meaning                                                                                  |
| -------------- | ---------------------------------------------------------------------------------------- |
| `IDENTIFIED`   | OCR read and validated the container number.                                             |
| `VALIDATED`    | A cargo manifest is attached and validated.                                              |
| `INSPECTING`   | A scan is in progress.                                                                   |
| `ANALYZED`     | A finalized defect scan has been graded and an AI decision recorded.                     |
| `FLAGGED`      | Set automatically only when a dangerous-goods scan reports a `HIGH` or `EXTREME` threat. |
| `UNDER_REVIEW` | Escalated for supervisor review.                                                         |
| `CLEARED`      | Approved, either by the AI decision or by a reviewer.                                    |
| `HELD`         | A reviewer rejected or held the container.                                               |
| `RELEASED`     | Released from the inspection point.                                                      |

> **Note**
>
> Defects never set `FLAGGED` on their own. A defect scan records an AI decision of `FLAGGED_DEFECT`, and a person decides what happens next through escalation and manual review.

## Defect grading

Edge devices send raw detections only: `class_name`, `confidence`, and `box`. The API maps every detection class to a product defect class and severity using the `container-defect-taxonomy-v1` taxonomy. Any severity the device sends is ignored.

| Defect class             | Report label                          | Severity   | Example detector classes                         |
| ------------------------ | ------------------------------------- | ---------- | ------------------------------------------------ |
| `CRACK`                  | Crack / structural breach             | `CRITICAL` | `crack`, `hole`, `puncture`, `structural_damage` |
| `DENT`                   | Dent                                  | `HIGH`     | `dent`, `minor_dent`                             |
| `RUST_CORROSION`         | Rust / corrosion                      | `HIGH`     | `rust`, `severe_rust`, `corrosion`               |
| `DOOR_DAMAGE`            | Door damage                           | `HIGH`     | `door_damage`, `door_broken`, `door_dent`        |
| `SEAL_BROKEN`            | Seal broken                           | `HIGH`     | `seal_broken`, `broken_seal`, `seal_damage`      |
| `NO_DEFECT`              | No defect                             | `LOW`      | `no_defect`, `normal`, `clear`                   |
| `DIAGNOSTIC_UNSUPPORTED` | Diagnostic / unsupported defect label | `LOW`      | Any class not listed above                       |

Only reportable detections count toward the defect summary. `NO_DEFECT` and unsupported classes are stored for diagnostics but are not treated as defects.

### Structural integrity

The defect scan's `structuralIntegrity` is derived from the reportable detections:

| Value         | Rule                                                                   |
| ------------- | ---------------------------------------------------------------------- |
| `COMPROMISED` | At least one `CRITICAL` detection                                      |
| `ACCEPTABLE`  | At least one `HIGH` detection and no `CRITICAL` detections             |
| `GOOD`        | No `CRITICAL` or `HIGH` detections                                     |
| `UNKNOWN`     | Not computed; appears on scans uploaded manually through the dashboard |

## AI decision

Every finalized edge defect scan records an `aiDecision` on the container:

| `aiDecision.status` | When                                                                                            |
| ------------------- | ----------------------------------------------------------------------------------------------- |
| `CLEARED`           | No reportable defects were detected                                                             |
| `FLAGGED_DEFECT`    | One or more reportable defects were detected; the decision includes reasons and recommendations |

Dashboard statistics also group other flag reasons: `FLAGGED_ILLEGAL`, `FLAGGED_MISMATCH`, and `FLAGGED_MULTIPLE`. Category scans compare detected cargo with the attached manifest when one exists.

## Manual review

People make the final call on flagged containers.

#### Escalate

Any signed-in user can escalate a container with `POST /v1/containers/{id}/escalate`. The container moves to `UNDER_REVIEW`, and supervisors are notified in the app and by email.

#### Work the queue

Supervisors and admins list pending work with `GET /v1/escalations`.

#### Decide

A supervisor or admin submits `PUT /v1/containers/{id}/manual-review` with a `decision` of `APPROVE`, `REJECT`, or `HOLD` and optional `notes`. `APPROVE` moves the container to `CLEARED`; `REJECT` and `HOLD` move it to `HELD`. The AI decision is marked as manually overridden.

Every review and escalation is written to the audit log, which admins can read at `GET /v1/admin/audit-log`.