Data Model

Four things matter to a consuming system: the program that defines an inspection, the program run that executes it, the part identity the run is recorded against, and the quality report it produces. Everything is reachable from a run_id.

Program and program run#

A program is run many times; each program run executes it once against a single part and is identified forever by its run_id. A polled program run moves through pending → running → finalizing → exactly one of completed | failed | cancelled. Treat only those last three as terminal — finalizing is the window after the last step where checks are aggregated and the ProgramCompleted event is dispatched. A failed program run carries error_message and, when a step caused it, error_step_index.

Part identity: serial number and revision#

A part is identified by its serial_number (null if none was captured). Cheetah does not store parts as separate records — identity travels on the program run. When the same serial number is inspected again, the new program run is automatically assigned the next revision; distinct revisions are distinct inspections of one physical part, typically after rework.

The quality report#

Only a completed program run produces one. It carries the QC outcome (passed), every quality check evaluated — each with name, status, value, threshold, and delta — and any defects found. It is delivered in the ProgramCompleted event and fetchable later by run_id.

Lifecycle events#

Events are data about a program run — each carries the run_id, identity fields, and timestamps, so you can record it without a follow-up call. One ProgramStarted, then exactly one terminal event. Meaning: Program Lifecycle Events. Exact payloads: event reference.