Section 5: One Envelope, Four Tables, One Index per Schema - Data Modeling

Executive Summary: Section 4 wrote the contracts; this section decides what they write to. An annotation becomes an immutable, versioned envelope with optional time and space anchors. Schemas are built from shared base types and change additively within a major version. Cassandra holds the truth in four tables, and the key (entity_id, schema_id, op_id, minute_bucket) turns a 3.3 GB hot-title partition into 5.5 MB ones. Elasticsearch is a derived index, one per schema major version.

The interviewer points at the API on the board. "Fine. What's actually on disk?"

Start with the reads. A GET by id names annotation_id. An editor's timeline names a title, a schema and a time range. Every query first asks which run is current. Everything else goes to the search index. Point and range reads peak at 5,000 QPS, search at 1,500 QPS.

The Annotation Envelope

Every annotation shares one outer shape. Here is one of char-detect v4's 1,100 segments on Night Heist:

{
  "annotation_id": "ann_5b81e0c2",
  "version": 1,
  "entity_id": "title:70451122",
  "schema": { "name": "character-appearance", "version": "2.3" },
  "producer": "char-detect",
  "op_id": "op_7Hq2",
  "temporal": { "start_ms": 2470000, "end_ms": 2512000 },
  "spatial": { "frame_ms": 2470000, "x": 0.62, "y": 0.18, "w": 0.14, "h": 0.22 },
  "data": { "character": "Lena Cruz", "confidence": 0.94 },
  "labels": ["character", "face"],
  "embedding_ref": null,
  "created_at": "2026-10-12T03:14:09Z",
  "created_by": "svc:char-detect"
}

temporal and spatial are optional: "contains violence" has neither, a subtitle line has only temporal. Coordinates are normalized to 0–1, so a box means the same thing on a 4K encode and a 480p one. data is free-form and schema-validated. The model version (v4) lives on the operation, so the scope stays char-detect across runs. The id is hash(op_id, producer_key), so a retried batch overwrites instead of duplicating. The average stored envelope is 1.3 KB.

Key Insight: Annotations are immutable. Identity is (annotation_id, version): a tagger editing their own annotation writes version 2, a delete writes a tombstone version 3, nothing changes in place. ML output is never edited; a correction is a separate human-layer annotation (Section 11). History comes free, and out-of-order delivery is harmless because the newer version wins in both stores. Netflix has described Marken's annotations the same way: immutable and versioned.

Quick check before moving on: