# Azaion UI — Glossary

**Status**: confirmed-by-user
**Date**: 2026-05-10

> Output of `/document` Step 4.5. Terms are grounded in the verified module
> (`modules/*.md`) and component (`components/*/description.md`) docs. Generic
> CS / web-platform terms are intentionally omitted. Each entry: one-line
> definition + source reference.

## A

**401-retry path**: the working bearer-refresh path inside `api/client.ts:44` — `POST /api/admin/auth/refresh` with `credentials:'include'`, fired automatically on any 401 from an authenticated fetch. Distinct from the broken bootstrap refresh (see *Bootstrap refresh*). *source: `_docs/02_document/04_verification_log.md` §2a, F2*

**Admin**: privileged operator persona. CRUD detection classes (add + delete + **edit** — edit re-introduced per Step 4.5 decision), users, AI/GPS settings. *source: `components/08_admin/description.md`*

**Affiliation**: friend / foe / civilian classification on a bbox. UI tokens (`AFFILIATION_COLORS`) exist but are dead today (finding #14). On-wire numeric values follow the suite spec — see `_docs/02_document/data_model.md` §enum-drift. *source: `components/06_annotations/description.md`*

**Aircraft**: drone hardware identity used by flights; `isDefault` toggle is the only mutation surfaced in the UI today. *source: `components/05_flights/description.md`, `components/08_admin/description.md`*

**Annotation**: bounding box + class + status (`Created` / `Edited` / `Validated`) tied to a media file at a given videoTime. The save endpoint is `POST /api/annotations/annotations` (doubly-prefixed). *source: `components/06_annotations/description.md`, `04_verification_log.md` F5*

**AnnotationStatus**: numeric enum `Created` / `Edited` / `Validated`. Suite spec is authoritative; the UI's TypeScript enum carries inline comments mapping each integer to its meaning. *source: `src/types/index.ts`, `04_verification_log.md` enum drift*

**Annotator (legacy)**: the WPF window (`Azaion.Annotator`) the React `06_annotations` component replaces. Used as a behavioral reference for keyboard shortcuts, time-window overlays, AI-detect UX. *source: `_docs/legacy/wpf-era.md` §3, `suite/annotations-research`*

**ARM-first**: production target is ARM64 edge devices (operator laptops, OrangePi, Jetson). CI builds ARM64 only today. *source: `.woodpecker/build-arm.yml`, `_docs/legacy/wpf-era.md` §1*

**Azaion**: project codename. Appears in legacy namespace (`Azaion.Annotator`, `Azaion.Dataset`), Tailwind design tokens (`az-bg`, `az-orange`, `az-panel`, etc.), and parent suite repo name. *source: `src/index.css`, `_docs/legacy/wpf-era.md`*

## B

**Bbox**: x, y, w, h coordinates of a detection rectangle in normalised pixels. *source: `components/06_annotations/description.md` (`CanvasEditor`)*

**Bearer auto-refresh**: the umbrella term for keeping the user's bearer token fresh. Two distinct paths exist in code (Step 4 finding) — see *401-retry path* and *Bootstrap refresh*. *source: `04_verification_log.md` §2a*

**Bearer token**: short-lived JWT held in **memory only**; never written to localStorage / sessionStorage. Refreshed via the HttpOnly *Refresh cookie*. *source: `src/auth/AuthContext.tsx`*

**Bootstrap refresh**: the broken bearer-refresh path inside `AuthContext.tsx:24` — `GET /api/admin/auth/refresh` without `credentials:'include'`. Step 4 fix candidate. *source: `04_verification_log.md` §2a, F2*

**Bulk-validate**: the `POST /api/annotations/dataset/bulk-status` action that transitions selected dataset items to `AnnotationStatus.Validated`. UI button is wired (`DatasetPage.tsx:142-146`); the `[V]` keyboard shortcut is missing. *source: `components/07_dataset/description.md` §6b*

## C

**CanvasEditor**: bounding-box draw / 8-handle resize / Ctrl-multi-select widget. Owned by `06_annotations`; `07_dataset` imports it directly (cross-feature edge — see baseline scan). *source: `components/06_annotations/description.md`*

**Class colors / classColors**: central color + text mapping for detection classes. Lifted into its own component (`11_class-colors`) at Step 2. *source: `components/11_class-colors/description.md`*

**Class Distribution chart**: Dataset Explorer's third tab — horizontal bars per `DetectionClass`, bar tinted with the class color. Implemented (`DatasetPage.tsx:151`, `loadDistribution()`). *source: `components/07_dataset/description.md` §6b*

**ClassNum / classId**: integer key of a `DetectionClass` (0..N-1). Note: `0` collides with the "all classes" sentinel in some filter UIs (finding #9). *source: `components/03_shared-ui/description.md` (`DetectionClasses`)*

**CombatReadiness**: ready / damaged / destroyed tag on a bbox. Surfaced like Affiliation, currently dormant in UI. Suite spec is source of truth; types file carries inline numeric-meaning comments. *source: `components/06_annotations/description.md`, `src/types/index.ts`*

**ConfirmDialog**: shared UI primitive for destructive-action confirmation. Reused across `05_flights`, `06_annotations`, `08_admin`, `07_dataset`. *source: `components/03_shared-ui/description.md`*

## D

**DatasetItem**: paged list shape returned by `GET /api/annotations/dataset`; carries thumbnail, classNum, status, isSeed?, isSplit?. *source: `components/07_dataset/description.md`*

**DetectionClass**: catalog entry `{id, name, color, photoMode, maxSizeM}`. The domain vocabulary for AI detection. Read via `GET /api/annotations/classes`; mutated via `POST /api/admin/classes` (add) + `PATCH /api/admin/classes/{id}` (**edit — to be re-introduced** per Step 4.5 decision) + `DELETE /api/admin/classes/{id}`. *source: `components/03_shared-ui/description.md` (`DetectionClasses`), `components/08_admin/description.md`*

**DetectionClasses (UI control)**: vertical strip widget rendering the catalog of classes; reused by `06_annotations` and `07_dataset`. Same control name as the WPF era for migration clarity. *source: `components/03_shared-ui/description.md`*

**Drone Maintenance (legacy)**: WPF feature ("Аналіз стану БПЛА"). **Dropped** per Step 4.5 decision; not ported. *source: `_docs/02_document/01_legacy_coverage_gaps.md`*

## E

**EventSource / SSE**: the only realtime channel. Used for live-GPS telemetry (F13), annotation-status events (F14), and the planned async-detect stream (F7). No WebSocket. *source: `src/api/sse.ts`*

## F

**FlightContext**: cross-cutting React Context that holds the flight list and the currently-selected flight. One of two cross-cutting contexts (the other is `AuthContext`); everything else is local state. *source: `components/03_shared-ui/description.md`*

**Flight**: a sortie + its waypoints + altitude profile + aircraft. `selectedFlightId` persists as a `UserSettings` field via `PUT /api/annotations/settings/user`, NOT via a dedicated `/api/flights/select` endpoint. *source: `components/05_flights/description.md`, `04_verification_log.md` F3*

## G

**GPS-Denied**: positioning workflow for flights without GPS — uses on-board IMU + visual matching against a pre-loaded reference. Sub-feature of `05_flights`. Includes the planned **Test Mode** (see below). *source: `components/05_flights/description.md`*

**GSD (Ground Sample Distance)**: meters-per-pixel computed from altitude + focal length + sensor size. Surfaced in the camera-config side panel (currently missing — finding #17). *source: `components/06_annotations/description.md` finding #17*

## I

**IsSeed**: per-annotation flag (legacy WPF concept) marking ground-truth seeds; visual port — 8 px IndianRed border on thumbnails — is unverified against current API. Open question deferred to a future task cycle. *source: `components/07_dataset/description.md` §6b*

## M

**Media**: an image or video file uploaded to a flight. `mediaType=1` is a magic literal in current code (finding #5/#10) pending a typed enum. *source: `components/06_annotations/description.md` (`MediaList`)*

**MediaStatus**: numeric enum on a media file. Suite spec is source of truth; UI types file carries inline numeric-meaning comments. *source: `src/types/index.ts`*

**Mission Planner (mission-planner/ tree)**: React 18 + MUI 5 port-source codebase living at the repo root. **Not deployed.** Treated as a behavioral reference for `05_flights` (the React 19 + Tailwind target). Convergence plan per Step 4.5 decision: flag at Step 2, spec at Step 3, port across Phase B cycles, delete the tree in the final cycle. *source: `components/05_flights/description.md`, `flows/existing-code.md`*

## N

**nginx (deployment runtime)**: serves the static `dist/` bundle and reverse-proxies `/api/<service>/*` to the matching suite service. Multi-stage Dockerfile output; ARM64 base image. *source: `Dockerfile`, `nginx.conf`*

## O

**Operator**: primary user persona. Flies missions, reviews annotations, runs AI detect. *source: `components/05_flights/description.md`, `components/06_annotations/description.md`*

**OpenWeatherMap**: external HTTP API consumed directly by the SPA for wind data in flight planning. API key currently hardcoded in `flightPlanUtils.ts:60` — **moving to `.env`** per Step 4.5 decision (Step 4 testability fix candidate). *source: `mission-planner/src/utils/flightPlanUtils.ts:60`*

## P

**Phase A / Phase B (autodev existing-code flow)**: Phase A = one-time baseline (Steps 1–8, Document → Refactor); Phase B = feature cycle (Steps 9–17, loops). Mission-planner convergence happens in Phase B per Step 4.5 decision. *source: `.cursor/skills/autodev/flows/existing-code.md`*

**PhotoMode**: drawing modality of a detection class — `Regular` (offset `0`), `Winter` (snow, offset `+20`), `Night` (offset `+40`). Carried both as the explicit `DetectionClass.photoMode` field and as the offset that produces *yoloId* (`yoloId = classId + photoModeOffset`). The `DetectionClasses` widget renders a three-button switcher (Sunny / Snowflake / Moon) and filters the class list to the active mode. *source: `components/11_class-colors/description.md`; `modules/src__components__DetectionClasses.md`; `data_model.md` enum table*

**ProtectedRoute**: route wrapper that redirects unauthenticated users to `/login`. Owns the gate between public (`/login`) and authenticated routes. *source: `components/02_auth/description.md`*

## R

**React Context (state-management approach)**: two contexts only — `AuthContext` and `FlightContext`. **Non-negotiable**: no Redux, no Zustand, no TanStack Query. Caching is in component state. *source: `src/auth/AuthContext.tsx`, `src/components/FlightContext.tsx`*

**Refresh cookie**: HttpOnly Secure cookie issued by `/api/admin/auth/refresh`. Carries the long-lived refresh token; never accessible to JavaScript. *source: `components/02_auth/description.md`*

**Resizable panel**: paneled UI surfaces (`AnnotationsPage` left/right, `DatasetPage` left) whose widths are typed in `UserSettings` and **persisted** per Step 4.5 decision. Hook is `useResizablePanel`; today the hook reads but does not write back (finding #11) — Step 4 fix. *source: `src/hooks/useResizablePanel.ts`, `components/00_foundation/description.md`*

## S

**Selected flight**: see *Flight*. Persisted via `PUT /api/annotations/settings/user` (NOT `/api/flights/select`). *source: `04_verification_log.md` F3*

**Selected media**: the currently-open media item in `06_annotations` / `07_dataset`. Page-local state, not in any context. *source: `components/06_annotations/description.md`*

**SITL (Software In The Loop)**: SITL = pre-recorded `.tlog` + video pair fed to the on-board service to validate GPS-Denied positioning end-to-end without a real flight. Used by Test Mode (F12). *source: `_docs/how_to_test.md`, `components/05_flights/description.md`*

**Sound Detections (legacy)**: WPF feature showing detections derived from audio analysis. **Dropped** per Step 4.5 decision; not ported. *source: `_docs/02_document/01_legacy_coverage_gaps.md`*

**Static bundle**: the only build artifact. nginx serves `dist/` and proxies `/api/<service>/*`. **Non-negotiable**: zero UI runtime, no SSR, no React Server Components. *source: `Dockerfile`, `nginx.conf`*

**Suite (parent meta-repo)**: `suite/` — contains the UI (this repo as a submodule), backend services, and the read-only `annotations-research` detached-head reference. *source: `_docs/legacy/wpf-era.md` §0*

## T

**Test Mode (GPS-Denied)**: planned end-to-end testing workflow inside `05_flights/GPS-Denied`. Operator uploads a `.tlog` + synced video; the system feeds them to the on-board service via SITL. *source: `_docs/how_to_test.md`, `components/05_flights/description.md`*

**tlog**: MAVLink telemetry log. One of two file inputs to GPS-Denied Test Mode (the other is the synced video). *source: `_docs/how_to_test.md`*

## U

**User**: admin-managed account `{id, email, role, isActive}`. Mutations via `/api/admin/users/*`. *source: `components/08_admin/description.md`*

**UserSettings**: per-user preferences entity persisted by the `annotations/` service. Carries `selectedFlightId`, panel widths, and other UI state. **Endpoint**: `/api/annotations/settings/user` (corrected at Step 4 — was incorrectly drafted as `admin/settings`). *source: `04_verification_log.md` §2a*

## V

**Validated** (annotation status): the terminal status of the AnnotationStatus enum. Synonyms in informal comments include "approved" — **prefer "Validated"** to match the typed enum. *source: `src/types/index.ts`*

## W

**Waypoint**: lat/lon/alt point in a flight; edit cycle is delete-then-recreate today (finding #19), pending API support for in-place updates. *source: `components/05_flights/description.md`*

**Woodpecker CI**: the CI runner. Pipeline at `.woodpecker/build-arm.yml`; builds + pushes `${REGISTRY_HOST}/azaion/ui:${branch}-arm`. No test step today — added in Step 5 of the autodev flow. *source: `.woodpecker/build-arm.yml`*

**WPF era**: legacy reference period — the C# / WPF stack (`Azaion.Annotator` + `Azaion.Dataset` + `MapMatcher`) the React port replaces. Documented in `_docs/legacy/wpf-era.md`. *source: `_docs/legacy/wpf-era.md`*

## Y

**yoloId**: `classId + photoModeOffset` — the on-wire detection-class identifier consumed by the Yolo backbone. Mapping owned by `11_class-colors`. *source: `components/11_class-colors/description.md`*

## Synonym / drift pairs (canonical → variants)

> When two terms appear interchangeably in code or comments, the **canonical**
> form below is the one to prefer. Tools / docs / commits should converge on it.

| Canonical | Variants seen | Where |
|-----------|---------------|-------|
| **Flight** | "mission" | mission-planner/ tree + some legacy comments |
| **Annotation** / **Annotator** (component, page) | (no drift) | — |
| **Annotator (legacy WPF)** | (no drift) | `_docs/legacy/wpf-era.md` only |
| **PhotoMode** | "modality" | a few module-doc summaries |
| **classNum** | "classId" | the two are used interchangeably; classNum dominates code |
| **Validated** (AnnotationStatus) | "approved" | informal comments |
| **mission-planner/ tree** | "Mission Planner port-source", "MUI port" | various component docs |