ui/_docs/00_problem/input_data/data_parameters.md

Data Parameters — Azaion UI

Output of /document Step 6d. The Azaion UI is a thin client over a typed REST + SSE contract; it carries no database. "Input data" therefore means the data shapes the SPA consumes (REST response payloads, SSE event payloads, env config). All claims trace to _docs/02_document/data_model.md, architecture.md § 4–5, and per-component descriptions.

Status: synthesised-from-verified-docs (Step 6d — /document) Date: 2026-05-10

---

Categories of input data

The SPA consumes four categories:

1. Typed REST entities — see _docs/02_document/data_model.md for the full ER map; key shapes summarised below.
2. SSE event payloads — live-gps, annotation-status, planned detect-stream.
3. Configuration / environment variables — runtime config injected at build time or via env.
4. Static assets — translation bundles, icons, design tokens (compiled into the bundle).

---

1. Typed REST entities (defined in src/types/index.ts)

Every entity below mirrors the suite's REST contract. Values listed here match the suite spec, which is the source of truth per principle P9. Where the UI's current TypeScript enum drifts from the spec, the row notes the drift and the Step 4 fix.

Auth

Entity	Fields	Source
AuthUser	id, email, name, role, permissions: string[], aircraftId?	02_auth; admin/ service
LoginRequest	{ email, password }	POST /api/admin/auth/login body
LoginResponse	{ bearer, user: AuthUser } (refresh cookie set server-side)	POST /api/admin/auth/login 200

Flights

Entity	Fields	Source
Flight	id, name, aircraftId, startDate?, endDate?, description?	flights/ service
Waypoint	Spec: { Geopoint: { Lat, Lon, MGRS }, Source, Objective, OrderNum, Height }. UI today: { name, latitude, longitude, order } — drift, finding #20 / Step 4 fix	05_flights; flights/ service
Aircraft	id, name, model, isDefault, serialNumber?	flights/ (read+write); 08_admin mutation
LiveGpsEvent (SSE)	{ flightId, lat, lon, alt, heading, speed, ts }	createSSE('/api/flights/${id}/live-gps'); F13

Annotations + Media

Entity	Fields	Source
Media	id, flightId, mediaType: MediaType, mediaStatus: MediaStatus, filename, waypointId?, videoTime?, thumbnail?	annotations/ service
MediaType enum	Spec: None=0, Image=1, Video=2. UI: same.	00_foundation; P9
MediaStatus enum	Spec: must include None, Confirmed, Error plus the existing New, AiProcessing, AiProcessed, ManualCreated. UI today: only New=0 / AiProcessing=1 / AiProcessed=2 / ManualCreated=3 — drift, Step 4 fix	00_foundation; finding
AnnotationListItem	id, mediaId, videoTime, status: AnnotationStatus, source: AnnotationSource, detections: Detection[], isSeed?: boolean	annotations/
AnnotationStatus enum	Spec: None=0, Created=10, Edited=20, Validated=30, Deleted=40. UI today: Created=0, Edited=1, Validated=2 — drift, Step 4 fix per P9	00_foundation; 04_verification_log.md
AnnotationSource enum	AI=0, Manual=1 (matches spec)	00_foundation
Detection	{ classNum: number, x, y, w, h: number, affiliation: Affiliation, combatReadiness: CombatReadiness, confidence?: number } (normalised pixel coords)	06_annotations
Affiliation enum	Spec: must include None plus Unknown, Friendly, Hostile. UI today: Unknown=0, Friendly=1, Hostile=2 — drift, Step 4 fix	finding
CombatReadiness enum	Spec: must include Unknown plus NotReady, Ready. UI today: NotReady=0, Ready=1 — drift, Step 4 fix	finding
DetectionClass	{ id, name, color, photoMode, maxSizeM }	08_admin (write) + annotations/ (read)
Annotation save body	Required (per finding #32): Source, WaypointId, videoTime, plus mediaId, detections, status. UI today: missing Source and WaypointId; uses time instead of videoTime — Step 4 fix	06_annotations/AnnotationsPage.tsx
AnnotationStatusEvent (SSE)	{ annotationId, mediaId, oldStatus, newStatus, ts }	createSSE('/api/annotations/annotations/events'); F14

Dataset

Entity	Fields	Source
DatasetItem	id, mediaId, classNum, status: AnnotationStatus, thumbnail, isSeed?: boolean, isSplit?: boolean (parent-suite-doc fix applied for isSplit)	07_dataset; annotations/
ClassDistributionItem	{ classNum, label, color, count }	annotations/
Bulk-validate body	{ ids: number[], targetStatus: AnnotationStatus.Validated }	POST /api/annotations/dataset/bulk-status

Settings + Admin

Entity	Fields	Source
SystemSettings	as defined per 09_settings/SettingsPage.tsx (settings keys per the suite spec)	annotations/ (/api/annotations/settings/system)
DirectorySettings	per SettingsPage directory tab	annotations/ (/api/annotations/settings/directories)
CameraSettings	per SettingsPage camera tab	annotations/
UserSettings	selectedFlightId?: number, panelWidths?: { ... }, plus other per-user UI state	annotations/ (/api/annotations/settings/user)
User	id, email, role, isActive, createdAt?	admin/

Pagination

Entity	Shape	Source
PaginatedResponse<T>	{ items: T[], totalCount: number, page: number, pageSize: number }	shared envelope used by every list endpoint

---

2. SSE event payloads

Stream	URL	Payload shape	Where consumed
Live-GPS per flight (F13)	GET /api/flights/${flightId}/live-gps?token=${bearer}	LiveGpsEvent (see above)	src/features/flights/FlightsPage.tsx:67
Annotation-status events (F14)	GET /api/annotations/annotations/events?token=${bearer}	AnnotationStatusEvent	src/features/annotations/AnnotationsSidebar.tsx:25
Async detect progress (F7)	GET /api/detect/stream/${jobId}?token=${bearer} — target-only, NOT wired today	{ jobId, progress: 0..1, detections?: Detection[], status, ts } (anticipated)	not consumed today; planned per 04_verification_log.md F7

Bearer goes in the query string (?token=...) per ADR-008 — EventSource cannot send headers. Refresh-rotation breaks live SSE; reconnect is missing today (Step 8 hardening per architecture.md § Architecture Vision).

---

3. Configuration / environment variables

Variable	Where read	Type	Default	Source
VITE_OPENWEATHERMAP_API_KEY	(target — Step 4 fix) mission-planner/src/utils/flightPlanUtils.ts	string (secret)	currently hardcoded '335799082893fad97fa36118b131f919' (must rotate)	P10 violation, Step 4 fix
VITE_SATELLITE_TILE_URL	mission-planner Leaflet TileLayer	URL	none (unset breaks satellite imagery)	mission-planner only today
AZAION_REVISION	stamped into the production image at build time	string (commit SHA)	$CI_COMMIT_SHA from CI	Dockerfile; .woodpecker/build-arm.yml
REGISTRY_HOST	CI registry push	string	per pipeline secret	.woodpecker/build-arm.yml
i18next.lng	src/i18n/i18n.ts	language code	hardcoded 'en' (Step 4 fix — should resolve from detector)	i18n.ts; AC-13
nginx upstream hosts	nginx.conf	hostnames per service	docker-compose service names	nginx.conf

The SPA bundle MUST NOT carry secrets at build time — except OpenWeatherMap once it is moved to .env (per P10 the proper long-term answer is to proxy the OWM call through flights/ so no key reaches the browser; the .env move is the interim Step 4 testability fix).

---

4. Static assets

Asset	Location	Notes
Translation bundles	src/i18n/en.json, src/i18n/ua.json	English + Ukrainian; key parity is mandatory (AC-12)
Design tokens	src/index.css (az-bg, az-text, az-orange, az-success, az-danger, az-primary, ...)	Tailwind 4; ADR-005
Map icons	src/features/flights/mapIcons.ts	defaultIcon CDN URL pinned to leaflet@1.7.1 (drift — finding)
Aircraft / waypoint icons	bundled SVG / PNG under src/features/flights/icons/* (mission-planner port-source still has the larger set)	05_flights
Detection-class colors	src/features/annotations/classColors.ts (logically owned by 11_class-colors)	file-move pending (P11 / module-layout Verification Needed)

---

5. Data flow summary

1. Plan flight — UI fetches aircrafts from flights/; submits flight + waypoints; receives the persisted flight (today: delete-then-recreate waypoint cycle, finding #19; lossy POST shape, finding #20).
2. Capture media — out-of-band via the loader / annotations services; the UI surfaces uploaded items via MediaList polling.
3. Annotate — operator edits → POST /api/annotations/annotations; F14 SSE pushes other-user status changes (admin-wide stream, client-side filtered).
4. AI Detect (sync image) — POST /api/detect/${id} returns inline detections. Used for both image and video today (silent UX hazard for long videos — F7 to ship in Phase B).
5. AI Detect (async video — target) — POST /api/detect/video/${id} returns a job ID → SSE on /api/detect/stream/${jobId} streams progress. Long videos require X-Refresh-Token header per _docs/10_auth.md.
6. Curate dataset — UI queries annotations/ with status filters; bulk-validate transitions to AnnotationStatus.Validated; class-distribution chart loads from /api/annotations/dataset/class-distribution.
7. Settings — system / directory / camera saves go to annotations/; aircraft default-toggle goes to flights/ (cross-service mutation, accepted).
8. GPS-Denied Test Mode (target — F12) — .tlog + video upload to gps-denied-desktop/; SITL drives gps-denied-onboard/; results render back through flights/ GPS-Denied tab.

Full sequence diagrams: _docs/02_document/system-flows.md.