# Annotations (REST & files)

## 1. High-Level Overview

**Purpose:** HTTP API for annotation CRUD, status, listing, and serving **annotation image / thumbnail** bytes — the surface described in `suite/_docs/01_annotations.md` §1–6 (excluding the SSE stream).

**Architectural pattern:** Layered API — controller → application service → database + filesystem.

**Upstream dependencies:** Platform (DB, auth, paths), Media (annotation create may reference existing `MediaId`).

**Downstream consumers:** Annotator UI, Detections pipeline (HTTP POST annotations), Dataset (read-only overlap on entities).

## 2. Internal interfaces

Primary application API: `AnnotationService` — create/update/status/delete/query/get-by-id; uses `PathResolver`, `AppDataConnection`, hashing, label files, thumbnails, and triggers **real-time publish** (calls into `AnnotationEventService`) and **queue enqueue** (via failsafe path — see component 02).

Controller: `AnnotationsController` — **REST and file routes**; the `GET …/events` SSE action is **specified and operated** from the **Annotations realtime & sync** component (same source file, split responsibility for docs).

### Representative HTTP

| Area | Routes (policy `ANN`) |
|------|------------------------|
| CRUD | `POST/PUT/PATCH/DELETE/GET` under `/annotations` |
| Files | `GET /annotations/{id}/thumbnail`, `GET /annotations/{id}/image` |

## 3. External API specification

See `01_annotations.md` §1–6; confirm drift notes in `00_discovery.md` (JWT user id, `FlightId` vs suite `missionId`).

## 4. Data access patterns

Heavy use of `annotations`, `detection`, `media` joins for list filters; writes cascade detections on update.

## 5. Implementation notes

- Annotation id from image hash when bytes provided; else copy from existing media path.
- `TimeSpan` persisted as ticks on `Annotation`.

## 6. Dependency graph (relative to other components)

**Imports from:** Platform, Media (logical). **Consumed by:** Dataset (read), UI, external Detections service.

## 7. Modules included

`annotations-service` (module doc); **shared file** `AnnotationsController.cs` with component 02 for SSE action only.