# Glossary

**Status**: confirmed-by-user 2026-05-14.

System-wide terminology for `Azaion.Annotations`. Generic CS / industry terms (HTTP, JWT mechanics, REST, etc.) are excluded — only project-specific or domain-specific terms are listed. Each entry cites the doc or source file that establishes it.

---

**Annotation** — Hash-keyed record carrying detections, status, source, user, and time, attached to a media row. Central object of the service. *source: `data_model.md`, `modules/annotations-service.md`.*

**Annotation event** — SSE payload (`AnnotationEventDto`) describing a lifecycle change broadcast to UI subscribers. *source: `modules/sse-realtime.md`, `DTOs/AnnotationEventDto.cs`.*

**AnnotationSource** — Wire enum: `AI = 0`, `Manual = 1`. *source: `Enums/AnnotationSource.cs`.*

**AnnotationStatus** — Wire enum: `None = 0`, `Created = 10`, `Edited = 20`, `Validated = 30`, `Deleted = 40`. Soft-delete uses value 40 (per ADR-009). *source: `Enums/AnnotationStatus.cs`.*

**Annotator UI** — Operator-facing client of `01 Annotations REST` + SSE. Active editing surface. *source: `components/01_annotations-rest/description.md`.*

**Bulk status** — Multi-id status update via `POST /dataset/bulk-status` carrying `BulkStatusRequest { AnnotationIds, Status }`. *source: `Controllers/DatasetController.cs:34`.*

**Business transaction** — The lifecycle-level transactional boundary planned per ADR-008: DB rows + outbox commit atomically; FS writes and SSE publish run post-commit using the outbox row as the durable promise. *source: `architecture.md` ADR-008.*

**Camera settings** — Per-camera calibration (`altitude`, `focal_length`, `sensor_width`) used by detection geometry. *source: `data_model.md`, `Database/Entities/CameraSettings.cs`.*

**Combat readiness** — Wire enum on a detection (`CombatReadiness`). *source: `Enums/CombatReadiness.cs`, `modules/wire-enums.md`.*

**Dataset Explorer** — Read-heavy UI exposed under `/dataset` (policy `DATASET`). *source: `components/04_dataset/description.md`, suite `09_dataset_explorer.md`.*

**Detection** — Bounding box (`center_x/y, width, height`) + class number + label + affiliation + combat readiness, child of an annotation. *source: `data_model.md`, `Database/Entities/Detection.cs`.*

**Detection class** — Row in `detection_classes` (id, name, short_name, color, max_size_m, photo_mode). 19 rows seeded by the migrator; becoming admin-managed per RB-06. *source: `data_model.md`, `Database/DatabaseMigrator.cs`.*

**Directory settings** — DB-driven filesystem roots (`videos_dir`, `images_dir`, `labels_dir`, `thumbnails_dir`, `results_dir`, `gps_sat_dir`, `gps_route_dir`). Consumed via `PathResolver`. RB-01 will add `deleted_dir` for soft-delete relocation. *source: `data_model.md`, `Database/DatabaseMigrator.cs`, `modules/common-infrastructure.md`.*

**Failsafe outbox** — `annotations_queue_records` table; the durable bridge between local writes and the RabbitMQ stream. Drained by `FailsafeProducer`. *source: `architecture.md` ADR-003, `modules/rabbitmq-stream-sync.md`.*

**Flight** — *Deprecated synonym for Mission.* The codebase currently uses `FlightId` (DTOs and service queries) but will rename to `MissionId` per RB-07 to align with the suite spec. *source: `00_discovery.md` drift list, ADR-012.*

**JWT policies** — Authorization claims `ANN`, `DATASET`, `ADM` checked by `[Authorize(Policy = ...)]` on controllers. *source: `modules/auth-identity.md`, `Auth/JwtExtensions.cs`.*

**Media** — Uploaded image / video reference, waypoint-scoped, written via `MediaController`. *source: `data_model.md`, `components/03_media/description.md`.*

**MessagePack** — Wire encoding for outbox messages on the RabbitMQ stream (`AnnotationQueueMessage`, `AnnotationBulkQueueMessage`). Gzip-compressed at the producer. *source: `modules/rabbitmq-stream-sync.md`, `Services/FailsafeProducer.cs`.*

**Mission** — *Canonical domain term* per the suite spec — the logical grouping that the codebase currently calls "Flight" and that physically backs onto `media.waypoint_id`. The code → suite alignment is RB-07 / ADR-012; the suite remains canonical. *source: `suite/_docs/01_annotations.md`, `00_discovery.md`.*

**PathResolver** — DI singleton that lazy-loads filesystem roots from `directory_settings` and exposes per-annotation paths (image / label / thumbnail / result). Calls `Reset()` after directory updates. *source: `modules/common-infrastructure.md`, `Services/PathResolver.cs`.*

**QueueOperation** — Outbox enum: `Created = 0`, `Validated = 1`, `Deleted = 2`. RB-01 may add `Updated` for `UpdateAnnotation` semantics. *source: `Enums/QueueOperation.cs`.*

**RabbitMQ Stream `azaion-annotations`** — Durable export channel consumed by the admin sync worker and the AI training pipeline. Default port `5552`. *source: `architecture.md` ADR-003, `Program.cs:43`.*

**Refresh token** — Long-lived credential issued and rotated by the **admin** service. Annotations is a verifier only — it neither mints nor refreshes tokens. Long-running callers (e.g. the detections service) refresh against admin's `POST /token/refresh` and pass the resulting ES256 access token to annotations. *source: `modules/auth-identity.md`.*

**Silent detection** — *Deprecated.* Boolean flag on `system_settings` that gated outbox enqueue during development debugging. Scheduled for removal per ADR-010 / RB-02 — the suite e2e harness covers this need now. *source: `architecture.md` ADR-010.*

**Soft-delete** — `DeleteAnnotation` semantics agreed on 2026-05-14: status flips to `AnnotationStatus.Deleted = 40`, the annotation row stays, and image / label / thumbnail files relocate to `deleted_dir`. RB-01 implements this; today's code is hard-delete. *source: `architecture.md` ADR-009 / RB-01.*

**SSE (Server-Sent Events)** — `text/event-stream` channel on `GET /annotations/events` carrying `AnnotationEventDto` payloads. In-process, per-instance; no cross-pod fan-out. *source: `modules/sse-realtime.md`, `Controllers/AnnotationsController.cs`.*

**System settings** — Singleton-ish service-config row (`thumbnail_*`, `generate_annotated_image`, etc.). *source: `data_model.md`.*

**Thumbnail** — Per-annotation small image at `thumbnails_dir/{id}.jpg`. **Not produced by `CreateAnnotation`** — read-only via `PhysicalFile`; populated out-of-band today. *source: `system-flows.md` Flow F1, F2.*

**Transactional outbox** — Pattern adopted in ADR-008: a queue table populated inside a DB transaction, drained asynchronously by a background worker (`FailsafeProducer`), used to bridge local commits to a remote stream durably. *source: `architecture.md` ADR-003, ADR-008.*

**User settings** — Per-user UI prefs (selected flight / mission, panel widths). Unique on `user_id`. *source: `data_model.md`, `Database/Entities/UserSettings.cs`.*

**Waypoint** — UUID associated with media uploads, used for mission-scoped grouping. Physical foreign key under the logical "Mission" concept. *source: `Database/Entities/Media.cs`.*

**World B** — Internal label for the agreed lifecycle-observability stance: every annotation mutation publishes SSE and enqueues the outbox, not just `Create`. *source: `architecture.md` ADR-009.*

**YOLO label** — Plain-text format used in `{id}.txt` files: one detection per line, fields `class cx cy w h` (normalized box). *source: `Services/AnnotationService.cs:243–249`, `modules/annotations-service.md`.*