ui/_docs/00_problem/problem.md

# Problem Statement — Azaion UI

> Output of `/document` Step 6a. Retrospective problem definition synthesised
> from `_docs/02_document/architecture.md` (System Context, Components),
> component descriptions, system flows, and the Step 4.5 Architecture Vision.
> No README exists in the repo today (the workspace's tracked README is the
> parent suite's; the UI repo has only the autodev-generated `README.md`
> stub). All claims here trace to verified `_docs/02_document/` artifacts.

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

---

## What is this system?

Azaion UI is the **operator-facing browser** of the Azaion UAV operations
suite — a single-page React 19 application served by nginx as a static bundle
inside an ARM64 container. It is the **React rewrite of the front-end half**
of the legacy WPF stack (`Azaion.Annotator` + `Azaion.Dataset` +
`MapMatcher`); the heavyweight machinery (LibVLC playback, Cython sidecars,
SQLite outbox, per-app DI host, binary-split key-fragment loader handoff)
moved server-side into the parent suite (`suite/`) as separate services.

The UI's narrowed responsibility is to **render the suite's REST + SSE
contract beautifully and accessibly** — it carries no domain logic that
belongs on the server, no in-browser persistence beyond a single bearer
in memory and a `Secure HttpOnly` refresh cookie, and no Node.js runtime in
the production image.

## What problem does it solve?

Operators of UAV / aerial-imagery missions (military and defense use cases)
need a single browser surface to:

1. **Plan flights** — define waypoints, altitudes, aircraft, GPS-Denied
   parameters; consult wind data; visualise routes on a map.
2. **Capture and review media** — browse uploaded images and videos scoped
   to a flight; play video frame-accurately; tag bounding boxes manually or
   via AI inference.
3. **Run AI object detection** — synchronously on images today; asynchronously
   on video (target — not wired today, see `04_verification_log.md` F7).
4. **Curate datasets** — filter by class / status, validate annotations in
   bulk, view class-distribution analytics.
5. **Administer** the system — manage detection classes, users, aircraft,
   AI / GPS settings.
6. **Operate GPS-Denied positioning** — including a planned **Test Mode**
   that drives SITL simulation from a pre-recorded `.tlog` + video pair
   (`_docs/how_to_test.md`).

This UI replaces the WPF desktop applications; it is the **single browser
client** for all of the above use cases. Every action goes through the
suite's typed REST contract or SSE stream — the browser is treated as
untrusted, so the server is authoritative for every state transition.

## Who are the users?

- **Operator** (primary persona) — flies missions, reviews captured media,
  runs AI detect, curates datasets. The UI's default authenticated route
  (`/flights`) targets this persona. Bilingual UI is mandatory (Ukrainian
  + English).
- **Admin** (privileged operator) — adds detection classes, manages users
  and aircraft, configures AI / GPS settings. Lives at `/admin`. Today this
  route lacks a client-side role-gate (server-side RBAC is authoritative;
  the missing UI gate is a finding).
- **System integrator** — uses the GPS-Denied Test Mode and the Settings
  pages to validate end-to-end pipelines.

The UI does NOT have an end-customer / public-facing surface. It is internal
to authenticated operators.

## How does it work at a high level?

```mermaid
flowchart LR
  Operator[Operator browser] -->|HTTPS| Nginx[nginx<br/>static SPA + reverse-proxy]
  Nginx -->|/api/admin/*| Admin[admin/]
  Nginx -->|/api/flights/*| Flights[flights/]
  Nginx -->|/api/annotations/*| Ann[annotations/]
  Nginx -->|/api/detect/*| Detect[detect/]
  Nginx -->|/api/gps-denied-*/*| GPS[gps-denied-*/]
  Nginx -->|/api/resource/*| Resource[resource/]
  Nginx -->|/api/autopilot/*| Autopilot[autopilot/]
  Operator -->|HTTPS direct| OWM[OpenWeatherMap]
  Operator -->|HTTPS direct| OSM[OSM tile servers]
```

1. Operator hits the nginx host. nginx serves `dist/index.html` + chunks.
2. The SPA boots; `AuthContext` attempts a bootstrap refresh (currently
   broken — Step 4 fix candidate); on 401 the `ProtectedRoute` redirects
   to `/login`.
3. Login (`POST /api/admin/auth/login`) returns a bearer in the response
   body and sets a `Secure HttpOnly` refresh cookie.
4. Subsequent authenticated requests carry the bearer in the `Authorization`
   header. On 401, the `01_api-transport` layer issues `POST
   /api/admin/auth/refresh` with `credentials:'include'` and retries.
5. Page-level fetches go to the matching suite service; nginx strips the
   `/api/<service>/` prefix and reverse-proxies. Long-lived streams (live-GPS
   per flight, annotation-status events) come over SSE.
6. State is two React Contexts (`AuthContext`, `FlightContext`) plus
   page-local `useState`. No Redux, no Zustand, no TanStack Query
   (`ADR-004`, P4).

The dominant runtime pattern is **thin client over a typed REST contract** —
no business logic in the browser; the server is the authority for every
mutation.

## Cross-reference with README

The repo's tracked `README.md` is a placeholder (untracked at the time of
this analysis — see `git status`). The parent suite's docs (`suite/_docs/*`)
are the canonical product reference; the UI's own derived docs in
`_docs/02_document/` complement those.

If a user-facing README is created in a future cycle, it should mirror the
"What this system is" paragraph above and link to `_docs/02_document/architecture.md`
for the full technical view.

## What this system explicitly does NOT do

- **No in-browser persistence beyond bearer + i18n cache** — every reload
  re-fetches.
- **No SSR / no React Server Components** — `Dockerfile` + `nginx.conf` ship
  a static bundle (`ADR-001`, P2).
- **No WebSocket** — REST + SSE only (`ADR-002`, P1).
- **No localStorage / sessionStorage for tokens** — bearer is in memory;
  refresh is in HttpOnly cookie (`ADR-001` consequence, P3).
- **No SEO** — operator-only application.
- **No mobile-first design** — Header has a bottom-nav variant for ≥ 768 px;
  mobile is a P2 use-case (see `_docs/02_document/architecture.md` § 6 NFRs).
- **No port of three legacy WPF features**: WPF-era encrypted-creds
  command-line handoff (P8 — security infra moved server-side), Sound
  Detections (Step 4.5 decision — dropped), Drone Maintenance / "Аналіз
  стану БПЛА" (Step 4.5 decision — dropped).

## Open product questions (carried forward)

These are **not blocking** Step 6 retrospective extraction; they are recorded
in `_docs/02_document/architecture.md` § Architecture Vision "Open questions
/ drift signals". Phase B feature cycles will resolve them per task.

1. Async video detect (`F7`) wiring — when in Phase B does the SSE consumer
   ship?
2. `IsSeed` annotation visual — does the modern API still expose `isSeed`?
3. Camera-config side panel (GSD) — per-user, per-flight, or per-detect-job?
4. Status-bar clock + help-text-blink — port WPF UX or replace with toasts?
5. `mission-planner/` end-state — delete after parity port (preferred per
   Step 4.5 decision) or keep as continuously-vendored reference?