mirror of
https://github.com/azaion/ui.git
synced 2026-06-21 09:21:10 +00:00
[AZ-447] autodev Steps 1-4 baseline: docs, tests, refactor specs
Captures the full output of autodev existing-code Phase A through Step 4 (Code Testability Revision) for the Azaion UI workspace: - Step 1 Document: _docs/02_document/ (FINAL_report, architecture, glossary, components/, modules/, diagrams/, system-flows, module-layout) plus _docs/00_problem/ + _docs/01_solution/ + _docs/legacy/ + _docs/how_to_test + README. - Step 2 Architecture Baseline: architecture_compliance_baseline.md. - Step 3 Test Spec: _docs/02_document/tests/ (environment, test-data, blackbox/performance/resilience/security/ resource-limit tests, traceability-matrix), enum_spec_snapshot, expected_results/results_report.md (98 rows), plus the run-tests.sh + run-performance-tests.sh runners. - Step 4 Code Testability Revision: 01-testability-refactoring/ run dir (list-of-changes C01-C07, deferred_to_refactor, analysis/research_findings + refactoring_roadmap) and the 7 child task specs AZ-448..AZ-454 under _docs/02_tasks/todo/ plus _dependencies_table.md. - _docs/_autodev_state.md pins the cursor at Step 4 / refactor Phase 4 entry so /autodev resumes cleanly. Epic AZ-447 (UI testability gates) tracks the 7 child tasks that will land in subsequent commits. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -0,0 +1,463 @@
|
||||
# 00 — Codebase Discovery
|
||||
|
||||
> **Step 0 output for `/document`.** Read by Step 1 (per-module docs) to drive
|
||||
> processing order, by Step 2 (component assembly) to seed groupings, and by
|
||||
> Step 3 (system synthesis) for the tech-stack table.
|
||||
>
|
||||
> **Scope** (chosen at the autodev gate, 2026-05-10):
|
||||
> - `src/` — Azaion UI (React 19 SPA, the live front-end of the suite).
|
||||
> - `mission-planner/` — embedded React 18 + MUI sub-project (port-source for
|
||||
> `src/features/flights/`). Documented as a separate component group.
|
||||
> - `_docs/` already contained user-curated reference content
|
||||
> (`legacy/wpf-era.md`, `ui_design/`, `_autodev_state.md`); the document
|
||||
> skill writes alongside, not over.
|
||||
>
|
||||
> **Out of scope**: `node_modules/`, `dist/`, `bun.lock`, `package-lock.json`,
|
||||
> `.git/`, `.cursor/`, `_docs/` (read-only inputs), `.idea/`, `.claude/`,
|
||||
> `.superpowers/`, `mission-planner/public/` static assets.
|
||||
|
||||
---
|
||||
|
||||
## 1. Workspace at a glance
|
||||
|
||||
```
|
||||
suite/ui/ ← Cursor workspace root
|
||||
├── src/ ← Azaion UI (React 19, the live SPA)
|
||||
├── mission-planner/ ← embedded port-source (React 18 + MUI)
|
||||
├── _docs/ ← user-curated + autodev artifacts
|
||||
│ ├── legacy/wpf-era.md read-only reference (WPF predecessor)
|
||||
│ ├── ui_design/ read-only reference (HTML wireframes)
|
||||
│ ├── _autodev_state.md autodev state pointer
|
||||
│ └── 02_document/ ← this folder (autodev outputs)
|
||||
├── .cursor/ skills/rules/agents
|
||||
├── .woodpecker/build-arm.yml CI: arm64 Docker build → Harbor
|
||||
├── Dockerfile multi-stage: bun build → nginx static
|
||||
├── nginx.conf /api/* reverse proxy → suite services
|
||||
├── index.html SPA shell (mounts /src/main.tsx)
|
||||
├── package.json react 19, bun 1.3.11, vite 6, tw 4
|
||||
├── tsconfig.json strict ESM, `@/*` → `src/*`
|
||||
├── vite.config.ts react + tailwind plugin, /api proxy
|
||||
├── README.md repo overview + maturation plan
|
||||
└── .gitignore node_modules, .env.*, playwright-report/
|
||||
```
|
||||
|
||||
`src/` and `mission-planner/` are **disjoint** — no file in one imports from
|
||||
the other. The Vite alias `@ → src` is defined only in the workspace
|
||||
`vite.config.ts`; `mission-planner/vite.config.ts` has no aliases. Each has
|
||||
its own `package.json`, `tsconfig`, `index.html`, and entry point. The
|
||||
production bundle (`Dockerfile`) builds **only the workspace**, not
|
||||
`mission-planner/`.
|
||||
|
||||
`mission-planner/` ships a (mostly) functional flight-mission UI that the
|
||||
`src/features/flights/*` files are mechanically translating into the new
|
||||
SPA. Per the workspace `README.md`, `mission-planner/` is **not** part of
|
||||
the deployed product.
|
||||
|
||||
## 2. Tech stack
|
||||
|
||||
### 2a. Workspace `src/` (Azaion UI)
|
||||
|
||||
| Concern | Choice | Source |
|
||||
|----------------|-------------------------------------|--------------------------|
|
||||
| Language | TypeScript 5.7 (`strict: true`) | `tsconfig.json` |
|
||||
| UI framework | React 19 (`react-dom/client`) | `package.json` |
|
||||
| Bundler | Vite 6 | `package.json`, `vite.config.ts` |
|
||||
| Pkg manager | Bun 1.3.11 (declared via `packageManager`) | `package.json` |
|
||||
| Styling | Tailwind CSS 4 (`@tailwindcss/vite`) + custom `az-*` tokens in `src/index.css` | `package.json`, `vite.config.ts` |
|
||||
| Routing | `react-router-dom` 7 | `src/App.tsx` |
|
||||
| i18n | `i18next` + `react-i18next` (UA / EN) | `src/i18n/i18n.ts` |
|
||||
| Map | `leaflet` 1.9 + `react-leaflet` 5 + `leaflet-draw` + `leaflet-polylinedecorator` | `package.json`, `src/features/flights/*` |
|
||||
| Charts | `chart.js` 4 + `react-chartjs-2` | `package.json` |
|
||||
| DnD | `@hello-pangea/dnd` 18 | `package.json` |
|
||||
| File upload | `react-dropzone` | `package.json` |
|
||||
| Icon set | `react-icons` | `package.json` |
|
||||
| HTTP transport | native `fetch` (custom thin wrapper) | `src/api/client.ts` |
|
||||
| Realtime | native `EventSource` (SSE) | `src/api/sse.ts` |
|
||||
| State mgmt | React Context only — `AuthContext`, `FlightContext`. **No** Redux / Zustand / TanStack Query. | `src/auth/`, `src/components/FlightContext.tsx` |
|
||||
| Tests | **none** (no test framework configured) | (verified via Glob) |
|
||||
| Build target | static bundle → nginx (multi-stage Dockerfile) | `Dockerfile`, `nginx.conf` |
|
||||
| Runtime | nginx in container, ARM64 image | `.woodpecker/build-arm.yml` |
|
||||
|
||||
### 2b. `mission-planner/` (port-source)
|
||||
|
||||
| Concern | Choice | Source |
|
||||
|----------------|------------------------------------------|------------------------------|
|
||||
| Language | TypeScript 5.7 (`strict: true`) | `mission-planner/tsconfig.app.json` |
|
||||
| UI framework | React 18 | `mission-planner/package.json` |
|
||||
| Bundler | Vite 6 | `mission-planner/vite.config.ts` |
|
||||
| Pkg manager | npm (lockfile not committed) | (no `bun.lock` in `mission-planner/`) |
|
||||
| UI library | MUI 5 (`@mui/material` + `@mui/icons-material` + `@emotion/*`) | `mission-planner/package.json` |
|
||||
| Map | `leaflet` 1.9 + `react-leaflet` 4.2 + `leaflet-draw` + `leaflet-polylinedecorator` | `mission-planner/package.json` |
|
||||
| Charts | `chart.js` 4 + `react-chartjs-2` | `mission-planner/package.json` |
|
||||
| DnD | `@hello-pangea/dnd` 16 | `mission-planner/package.json` |
|
||||
| Flags | `react-world-flags` | `mission-planner/package.json` |
|
||||
| Tests | Jest implied (`@testing-library/jest-dom` import in `setupTests.ts`, `describe/it/expect` in `src/test/jsonImport.test.ts`) but **no** Jest dep nor config in `package.json` — test currently cannot run as-is. | `mission-planner/package.json`, `src/setupTests.ts`, `src/test/jsonImport.test.ts` |
|
||||
| Env config | `.env.example` declares `VITE_SATELLITE_TILE_URL` | `mission-planner/.env.example` |
|
||||
| Build target | not built or shipped by the suite | (Dockerfile copies only workspace `src/`) |
|
||||
|
||||
## 3. Configuration & infrastructure files
|
||||
|
||||
| Path | Role |
|
||||
|-------------------------------------|----------------------------------------------------------------------|
|
||||
| `package.json` (workspace) | scripts: `dev`, `build` (`tsc -b && vite build`), `preview`. No `test`. |
|
||||
| `tsconfig.json` | `strict: true`, `noUnusedLocals/Parameters: false` (lax), `paths: {"@/*": ["./src/*"]}`. |
|
||||
| `vite.config.ts` | `@vitejs/plugin-react` + `@tailwindcss/vite`. Dev proxy `/api → http://localhost:8080`. |
|
||||
| `index.html` | `<div id="root"></div>` + `<script type="module" src="/src/main.tsx">`. Body class hardcodes `bg-[#1e1e1e] text-[#adb5bd]`. |
|
||||
| `Dockerfile` | Stage 1: `oven/bun:1.3.11-alpine`, `bun install --frozen-lockfile`, `bun run build`. Stage 2: `nginx:alpine`, copies `dist/` to `/usr/share/nginx/html`, exposes 80. `ENV AZAION_REVISION=$CI_COMMIT_SHA`. |
|
||||
| `nginx.conf` | Reverse-proxies 9 `/api/<service>/` paths → `http://<service>:8080/`. Enumerates: annotations, flights, admin, resource, detect, loader, gps-denied-desktop, gps-denied-onboard, autopilot. SPA fallback `/index.html`. `client_max_body_size 500M`. |
|
||||
| `.woodpecker/build-arm.yml` | Triggers on push to `dev`/`stage`/`main`. Builds + pushes `${REGISTRY_HOST}/azaion/ui:${branch}-arm` with OCI labels (revision, created, source). |
|
||||
| `.gitignore` | `node_modules/`, `.env.local`, `.env.development.local`, `.env.test.local`, `.env.production.local`, `package-lock.json`, `yarn.lock`, `/test-results/`, `/playwright-report/`, `/blob-report/`, `/playwright/.cache/`, `/playwright/.auth/`. (Playwright entries are aspirational — no Playwright installed.) |
|
||||
| `.env.example` (workspace) | **absent** — README §"Local development" notes this as a testability fix scheduled for Step 4. API base URL is currently hardcoded via the dev proxy + nginx routing. |
|
||||
| `mission-planner/package.json` | scripts: `dev`, `build`, `preview`. **No** `test` script despite the test file. |
|
||||
| `mission-planner/tsconfig.app.json` | `exclude: ["src/**/*.test.ts", "src/**/*.test.tsx", "src/setupTests.ts"]`. |
|
||||
| `mission-planner/.env.example` | `VITE_SATELLITE_TILE_URL` only. |
|
||||
| `mission-planner/public/manifest.json` | PWA manifest (vestigial CRA scaffolding). |
|
||||
|
||||
## 4. Entry points
|
||||
|
||||
| Project | File | Mounts |
|
||||
|------------------|-------------------------------------------------|---------------------------------------------------------------------|
|
||||
| `src/` | `src/main.tsx` | `<StrictMode><BrowserRouter><App /></BrowserRouter></StrictMode>` into `#root`. Imports `./i18n/i18n` for side effects (i18next init) and `./index.css`. |
|
||||
| `src/` | `src/App.tsx` | Top-level `Routes`. `/login` is public; everything under `/*` is wrapped in `AuthProvider → ProtectedRoute → FlightProvider → Header + nested Routes` (`/flights`, `/annotations`, `/dataset`, `/admin`, `/settings`, `*` → `/flights`). |
|
||||
| `mission-planner/` | `mission-planner/src/main.tsx` | `<StrictMode><LanguageProvider><FlightPlan /></LanguageProvider></StrictMode>` into `#root`. Imports `leaflet/dist/leaflet.css` and `leaflet-draw/dist/leaflet.draw.css`. |
|
||||
| `mission-planner/` | `mission-planner/src/App.tsx` | Empty CRA stub — **not used** by `main.tsx`. (Vestigial.) |
|
||||
|
||||
## 5. Test structure
|
||||
|
||||
| Project | Test file(s) | Framework | Status |
|
||||
|----------------|---------------------------------------------|--------------|-------------------------------------------------------------|
|
||||
| `src/` | none | n/a | **Zero test coverage.** Confirmed via Glob over `src/**/*.{test,spec}.*`. |
|
||||
| `mission-planner/` | `mission-planner/src/test/jsonImport.test.ts` | Jest (implied — uses `describe/it/expect`) | **Cannot run** — Jest is not in `package.json`; only `@testing-library/jest-dom` is imported in `setupTests.ts`. |
|
||||
| `mission-planner/` | `mission-planner/src/setupTests.ts` | - | One-line `import '@testing-library/jest-dom'`. |
|
||||
|
||||
This vacancy is the explicit input for autodev Steps 3–7 (test-spec, testability revision, decompose tests, implement tests, run tests).
|
||||
|
||||
## 6. Existing documentation
|
||||
|
||||
| Path | Status | Owner / used by |
|
||||
|---------------------------------------|----------------|----------------------------------------------------------------------------|
|
||||
| `README.md` (workspace) | maintained | Single source of truth for repo intent + maturation plan. |
|
||||
| `_docs/legacy/wpf-era.md` | reference | Captures WPF predecessor (`Azaion.Annotator`, `Azaion.Dataset`, Cython sidecars) at commit `22529c2`. Authoritative for §10 "What survived into the new world" and §11 "What is intentionally NOT being ported". |
|
||||
| `_docs/ui_design/README.md` | reference | Authoritative UX spec: pages, breakpoints, panel layouts, keyboard shortcuts, color tokens, affiliation icons, combat readiness, annotation row gradient, video time-window display, confirmation dialogs. |
|
||||
| `_docs/ui_design/{flights,annotations,dataset_explorer,admin,settings}.html` | reference | HTML wireframes for each page (inherited from WPF UI mockups). |
|
||||
| `_docs/_autodev_state.md` | maintained | autodev state pointer (this document is being produced under it). |
|
||||
| `mission-planner/README.md` | stale | CRA boilerplate; does not describe the actual app. |
|
||||
| Suite-level `../_docs/` | external | Suite-wide architecture, schema, deployment topology. Not owned by this workspace; consulted as needed during Step 3. |
|
||||
|
||||
## 7. Dependency graph
|
||||
|
||||
`src/` and `mission-planner/` are independent dependency islands. Each is
|
||||
acyclic by inspection (verified by following the import chains in §8 and §9
|
||||
from leaves outward).
|
||||
|
||||
### 7a. Workspace `src/` (intra-repo edges only; React/leaflet/etc. omitted)
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
main[main.tsx] --> App[App.tsx]
|
||||
main --> i18n_init[i18n/i18n.ts]
|
||||
i18n_init --> en[i18n/en.json]
|
||||
i18n_init --> ua[i18n/ua.json]
|
||||
|
||||
App --> AuthProvider[auth/AuthContext.tsx]
|
||||
App --> FlightProvider[components/FlightContext.tsx]
|
||||
App --> ProtectedRoute[auth/ProtectedRoute.tsx]
|
||||
App --> Header[components/Header.tsx]
|
||||
App --> LoginPage[features/login/LoginPage.tsx]
|
||||
App --> FlightsPage[features/flights/FlightsPage.tsx]
|
||||
App --> AnnotationsPage[features/annotations/AnnotationsPage.tsx]
|
||||
App --> DatasetPage[features/dataset/DatasetPage.tsx]
|
||||
App --> AdminPage[features/admin/AdminPage.tsx]
|
||||
App --> SettingsPage[features/settings/SettingsPage.tsx]
|
||||
|
||||
AuthProvider --> apiClient[api/client.ts]
|
||||
AuthProvider --> typesIdx[types/index.ts]
|
||||
ProtectedRoute --> AuthProvider
|
||||
FlightProvider --> apiClient
|
||||
FlightProvider --> typesIdx
|
||||
|
||||
Header --> AuthProvider
|
||||
Header --> FlightProvider
|
||||
Header --> HelpModal[components/HelpModal.tsx]
|
||||
Header --> typesIdx
|
||||
|
||||
sse[api/sse.ts] --> apiClient
|
||||
|
||||
ConfirmDialog[components/ConfirmDialog.tsx]
|
||||
DetectionClasses[components/DetectionClasses.tsx] --> apiClient
|
||||
DetectionClasses --> classColors[features/annotations/classColors.ts]
|
||||
DetectionClasses --> typesIdx
|
||||
|
||||
LoginPage --> AuthProvider
|
||||
|
||||
AdminPage --> apiClient
|
||||
AdminPage --> ConfirmDialog
|
||||
AdminPage --> typesIdx
|
||||
|
||||
SettingsPage --> apiClient
|
||||
SettingsPage --> typesIdx
|
||||
|
||||
classColors
|
||||
flightsTypes[features/flights/types.ts]
|
||||
flightPlanUtils[features/flights/flightPlanUtils.ts] --> flightsTypes
|
||||
mapIcons[features/flights/mapIcons.ts]
|
||||
|
||||
WaypointList[features/flights/WaypointList.tsx] --> flightsTypes
|
||||
AltitudeChart[features/flights/AltitudeChart.tsx] --> flightsTypes
|
||||
WindEffect[features/flights/WindEffect.tsx] --> flightsTypes
|
||||
MiniMap[features/flights/MiniMap.tsx] --> flightsTypes
|
||||
MapPoint[features/flights/MapPoint.tsx] --> flightsTypes
|
||||
MapPoint --> mapIcons
|
||||
DrawControl[features/flights/DrawControl.tsx] --> flightsTypes
|
||||
DrawControl --> flightPlanUtils
|
||||
AltitudeDialog[features/flights/AltitudeDialog.tsx] --> flightsTypes
|
||||
FlightListSidebar[features/flights/FlightListSidebar.tsx] --> typesIdx
|
||||
JsonEditorDialog[features/flights/JsonEditorDialog.tsx]
|
||||
|
||||
FlightParamsPanel[features/flights/FlightParamsPanel.tsx] --> WaypointList
|
||||
FlightParamsPanel --> AltitudeChart
|
||||
FlightParamsPanel --> WindEffect
|
||||
FlightParamsPanel --> flightsTypes
|
||||
FlightParamsPanel --> typesIdx
|
||||
FlightMap[features/flights/FlightMap.tsx] --> DrawControl
|
||||
FlightMap --> MapPoint
|
||||
FlightMap --> MiniMap
|
||||
FlightMap --> mapIcons
|
||||
FlightMap --> flightsTypes
|
||||
FlightsPage --> FlightProvider
|
||||
FlightsPage --> apiClient
|
||||
FlightsPage --> sse
|
||||
FlightsPage --> ConfirmDialog
|
||||
FlightsPage --> FlightListSidebar
|
||||
FlightsPage --> FlightParamsPanel
|
||||
FlightsPage --> FlightMap
|
||||
FlightsPage --> AltitudeDialog
|
||||
FlightsPage --> JsonEditorDialog
|
||||
FlightsPage --> flightPlanUtils
|
||||
FlightsPage --> flightsTypes
|
||||
FlightsPage --> typesIdx
|
||||
|
||||
CanvasEditor[features/annotations/CanvasEditor.tsx] --> typesIdx
|
||||
CanvasEditor --> classColors
|
||||
VideoPlayer[features/annotations/VideoPlayer.tsx] --> typesIdx
|
||||
AnnotationsSidebar[features/annotations/AnnotationsSidebar.tsx] --> apiClient
|
||||
AnnotationsSidebar --> sse
|
||||
AnnotationsSidebar --> classColors
|
||||
AnnotationsSidebar --> typesIdx
|
||||
MediaList[features/annotations/MediaList.tsx] --> FlightProvider
|
||||
MediaList --> apiClient
|
||||
MediaList --> useDebounce[hooks/useDebounce.ts]
|
||||
MediaList --> ConfirmDialog
|
||||
MediaList --> typesIdx
|
||||
AnnotationsPage --> useResizablePanel[hooks/useResizablePanel.ts]
|
||||
AnnotationsPage --> apiClient
|
||||
AnnotationsPage --> MediaList
|
||||
AnnotationsPage --> VideoPlayer
|
||||
AnnotationsPage --> CanvasEditor
|
||||
AnnotationsPage --> AnnotationsSidebar
|
||||
AnnotationsPage --> DetectionClasses
|
||||
AnnotationsPage --> classColors
|
||||
AnnotationsPage --> typesIdx
|
||||
|
||||
DatasetPage --> apiClient
|
||||
DatasetPage --> useDebounce
|
||||
DatasetPage --> useResizablePanel
|
||||
DatasetPage --> FlightProvider
|
||||
DatasetPage --> DetectionClasses
|
||||
DatasetPage --> ConfirmDialog
|
||||
DatasetPage --> CanvasEditor
|
||||
DatasetPage --> typesIdx
|
||||
```
|
||||
|
||||
### 7b. `mission-planner/src/`
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
mp_main[main.tsx] --> flightPlan[flightPlanning/flightPlan.tsx]
|
||||
mp_main --> LanguageProvider[flightPlanning/LanguageContext.tsx]
|
||||
|
||||
mp_types[types/index.ts]
|
||||
mp_config[config.ts]
|
||||
mp_utils[utils.ts]
|
||||
|
||||
translations[constants/translations.ts] --> mp_types
|
||||
languages[constants/languages.ts] --> mp_types
|
||||
purposes[constants/purposes.ts] --> mp_types
|
||||
actionModes[constants/actionModes.ts]
|
||||
maptypes[constants/maptypes.ts]
|
||||
tileUrls[constants/tileUrls.ts]
|
||||
|
||||
mapIcons[icons/MapIcons.tsx]
|
||||
pointIcons[icons/PointIcons.tsx]
|
||||
sidebarIcons[icons/SidebarIcons.tsx]
|
||||
phoneIcon[icons/PhoneIcon.tsx]
|
||||
|
||||
calcDistance[services/calculateDistance.ts] --> mp_types
|
||||
AircraftService[services/AircraftService.ts] --> mp_types
|
||||
WeatherService[services/WeatherService.ts] --> mp_types
|
||||
calcBattery[services/calculateBatteryUsage.ts] --> AircraftService
|
||||
calcBattery --> WeatherService
|
||||
calcBattery --> mp_types
|
||||
|
||||
Aircraft[flightPlanning/Aircraft.ts] --> mp_utils
|
||||
WindEffect2[flightPlanning/WindEffect.tsx] --> LanguageProvider
|
||||
WindEffect2 --> translations
|
||||
AltitudeChart2[flightPlanning/AltitudeChart.tsx] --> LanguageProvider
|
||||
AltitudeChart2 --> translations
|
||||
AltitudeChart2 --> mp_types
|
||||
AltitudeDialog2[flightPlanning/AltitudeDialog.tsx] --> LanguageProvider
|
||||
AltitudeDialog2 --> mp_config
|
||||
AltitudeDialog2 --> translations
|
||||
AltitudeDialog2 --> purposes
|
||||
DrawControl2[flightPlanning/DrawControl.tsx] --> mp_types
|
||||
JsonEditorDialog2[flightPlanning/JsonEditorDialog.tsx] --> LanguageProvider
|
||||
JsonEditorDialog2 --> translations
|
||||
TotalDistance[flightPlanning/TotalDistance.tsx] --> LanguageProvider
|
||||
TotalDistance --> calcDistance
|
||||
TotalDistance --> translations
|
||||
TotalDistance --> mp_types
|
||||
LanguageSwitcher[flightPlanning/LanguageSwitcher.tsx] --> LanguageProvider
|
||||
LanguageSwitcher --> languages
|
||||
LanguageSwitcher --> translations
|
||||
MapPoint2[flightPlanning/MapPoint.tsx] --> LanguageProvider
|
||||
MapPoint2 --> purposes
|
||||
MapPoint2 --> translations
|
||||
MapPoint2 --> pointIcons
|
||||
MapPoint2 --> mp_types
|
||||
MiniMap2[flightPlanning/MiniMap.tsx] --> MapView2
|
||||
MiniMap2 --> maptypes
|
||||
MiniMap2 --> tileUrls
|
||||
MiniMap2 --> mp_types
|
||||
PointsList[flightPlanning/PointsList.tsx] --> AltitudeDialog2
|
||||
PointsList --> mp_utils
|
||||
PointsList --> LanguageProvider
|
||||
PointsList --> translations
|
||||
PointsList --> calcBattery
|
||||
PointsList --> calcDistance
|
||||
PointsList --> mp_types
|
||||
MapView2[flightPlanning/MapView.tsx] --> DrawControl2
|
||||
MapView2 --> mp_utils
|
||||
MapView2 --> AltitudeDialog2
|
||||
MapView2 --> LanguageProvider
|
||||
MapView2 --> pointIcons
|
||||
MapView2 --> translations
|
||||
MapView2 --> actionModes
|
||||
MapView2 --> MiniMap2
|
||||
MapView2 --> MapPoint2
|
||||
MapView2 --> mapIcons
|
||||
MapView2 --> maptypes
|
||||
MapView2 --> purposes
|
||||
MapView2 --> tileUrls
|
||||
MapView2 --> mp_types
|
||||
LeftBoard[flightPlanning/LeftBoard.tsx] --> LanguageProvider
|
||||
LeftBoard --> PointsList
|
||||
LeftBoard --> AltitudeChart2
|
||||
LeftBoard --> TotalDistance
|
||||
LeftBoard --> LanguageSwitcher
|
||||
LeftBoard --> translations
|
||||
LeftBoard --> actionModes
|
||||
LeftBoard --> sidebarIcons
|
||||
LeftBoard --> mp_config
|
||||
LeftBoard --> mp_types
|
||||
flightPlan --> mp_utils
|
||||
flightPlan --> MapView2
|
||||
flightPlan --> AltitudeDialog2
|
||||
flightPlan --> JsonEditorDialog2
|
||||
flightPlan --> LeftBoard
|
||||
flightPlan --> mp_config
|
||||
flightPlan --> actionModes
|
||||
flightPlan --> AircraftService
|
||||
flightPlan --> phoneIcon
|
||||
flightPlan --> purposes
|
||||
flightPlan --> mp_types
|
||||
```
|
||||
|
||||
> **Note** — `MiniMap2` imports `UpdateMapCenter` (a *named* helper) **from**
|
||||
> `MapView2`, while `MapView2` imports `MiniMap2` as a child component. They
|
||||
> import in opposite directions, which would normally form a dependency
|
||||
> cycle, but module-level execution is non-circular because each side only
|
||||
> uses the *type/handle* exposed by the other at call time. **Flagged for
|
||||
> Step 1** (will document the named export contract precisely) and surfaced
|
||||
> in §11 below as a structural caveat.
|
||||
|
||||
## 8. Cross-feature edges in `src/` (architectural caveats)
|
||||
|
||||
These are edges where a "lower-layer" module imports from a "higher-layer"
|
||||
sibling. Surfaced now so Step 2 (Component Assembly) and Step 2.5
|
||||
(module-layout.md) can decide whether to formalise them in the layering
|
||||
table or flag them for the architecture baseline scan (Step 2 of autodev).
|
||||
|
||||
| Edge | Direction | Comment |
|
||||
|-------------------------------------------------------------------------------------|---------------------------------|---------|
|
||||
| `components/DetectionClasses.tsx` → `features/annotations/classColors.ts` | shared ← feature-specific | A `shared/` component depends on `features/annotations/`. The shared layer should not know about a specific feature. **Likely candidate for refactor**: extract `classColors.ts` into a feature-neutral location (e.g. `src/components/detection/classColors.ts`) or into a `shared/` module. |
|
||||
| `features/dataset/DatasetPage.tsx` → `features/annotations/CanvasEditor.tsx` | feature ← sibling feature | Cross-feature import, but consistent with the legacy WPF design where `Azaion.Dataset` reused `CanvasEditor` from `Azaion.Common.Controls` (see `_docs/legacy/wpf-era.md` §5). The proper fix is to lift `CanvasEditor` out of `features/annotations/` into a shared location. |
|
||||
| (none observed) | back-edge from `App` to `main` | - |
|
||||
|
||||
Also: every page calls `api/client.ts` directly with **string-literal URLs**
|
||||
(`/api/admin/auth/login`, `/api/flights?...`, `/api/annotations/settings/user`,
|
||||
etc.). There is no per-service API client module. This is the testability
|
||||
issue the workspace `README.md` calls out for Step 4 — but since it does
|
||||
not yet break compilation or layering, it is recorded here, not blocked.
|
||||
|
||||
## 9. Topological processing order — `src/` (40 modules, 8 batches)
|
||||
|
||||
Layer = max distance from leaves. Step 1 of `/document` MUST process modules
|
||||
in this order (leaves first), batched by ~5 with a session-break heuristic
|
||||
between batches.
|
||||
|
||||
> JSON files (`i18n/en.json`, `i18n/ua.json`) and `vite-env.d.ts` are
|
||||
> **inputs**, not modules — they are not separately documented; their content
|
||||
> is summarised inside the consumers (`i18n/i18n.ts`, the global TS env).
|
||||
> Counted modules: 40.
|
||||
|
||||
| Batch | Modules | Layer |
|
||||
|-------|--------------------------------------------------------------------------------------|-------|
|
||||
| **B1** | `types/index.ts`, `hooks/useDebounce.ts`, `hooks/useResizablePanel.ts`, `features/flights/types.ts`, `features/annotations/classColors.ts` | 0 |
|
||||
| **B2** | `features/flights/mapIcons.ts`, `features/flights/flightPlanUtils.ts`, `api/client.ts`, `i18n/i18n.ts`, `components/HelpModal.tsx` | 0–1 |
|
||||
| **B3** | `components/ConfirmDialog.tsx`, `components/DetectionClasses.tsx`, `auth/AuthContext.tsx`, `components/FlightContext.tsx`, `api/sse.ts` | 1–2 |
|
||||
| **B4** | `auth/ProtectedRoute.tsx`, `components/Header.tsx`, `features/login/LoginPage.tsx`, `features/admin/AdminPage.tsx`, `features/settings/SettingsPage.tsx` | 2–3 |
|
||||
| **B5** | `features/flights/{WaypointList,AltitudeChart,WindEffect,MiniMap,AltitudeDialog}.tsx` | 1–2 |
|
||||
| **B6** | `features/flights/{MapPoint,DrawControl,FlightListSidebar,JsonEditorDialog,FlightParamsPanel}.tsx` | 2 |
|
||||
| **B7** | `features/flights/FlightMap.tsx`, `features/annotations/{CanvasEditor,VideoPlayer,AnnotationsSidebar,MediaList}.tsx` | 2–3 |
|
||||
| **B8** | `features/flights/FlightsPage.tsx`, `features/annotations/AnnotationsPage.tsx`, `features/dataset/DatasetPage.tsx`, `App.tsx`, `main.tsx` | 3–5 |
|
||||
|
||||
## 10. Topological processing order — `mission-planner/` (37 modules, 8 batches)
|
||||
|
||||
Excluded from analysis: `vite-env.d.ts`, `types/leaflet-polylinedecorator.d.ts`,
|
||||
`types/react-world-flags.d.ts` (type shims for external libs), `setupTests.ts`,
|
||||
`App.tsx` (vestigial CRA stub — flagged for delete in §11), and `index.css`,
|
||||
`*.css` files. The Jest test (`src/test/jsonImport.test.ts`) is documented
|
||||
inline with `flightPlanning/flightPlan.tsx` (its target), not as a standalone
|
||||
module. Counted modules: 37.
|
||||
|
||||
| Batch | Modules | Layer |
|
||||
|-------|-----------------------------------------------------------------------------------------------------------------------------------------------|-------|
|
||||
| **MP-B1** | `types/index.ts`, `utils.ts`, `config.ts`, `constants/{actionModes,maptypes,tileUrls}.ts` | 0 |
|
||||
| **MP-B2** | `constants/{translations,languages,purposes}.ts`, `services/{calculateDistance,AircraftService,WeatherService}.ts` | 1 |
|
||||
| **MP-B3** | `services/calculateBatteryUsage.ts`, `flightPlanning/Aircraft.ts`, `flightPlanning/LanguageContext.tsx`, `icons/{MapIcons,PointIcons}.tsx` | 1–2 |
|
||||
| **MP-B4** | `icons/{SidebarIcons,PhoneIcon}.tsx`, `flightPlanning/{WindEffect,DrawControl,LanguageSwitcher}.tsx` | 2 |
|
||||
| **MP-B5** | `flightPlanning/{AltitudeChart,AltitudeDialog,JsonEditorDialog,TotalDistance,MapPoint}.tsx` | 2–3 |
|
||||
| **MP-B6** | `flightPlanning/MapView.tsx` (cycle group with `MiniMap.tsx`), `flightPlanning/MiniMap.tsx`, `flightPlanning/PointsList.tsx` | 3–4 |
|
||||
| **MP-B7** | `flightPlanning/LeftBoard.tsx`, `flightPlanning/flightPlan.tsx` | 5–6 |
|
||||
| **MP-B8** | `main.tsx`, `test/jsonImport.test.ts` (analysis only — covered by `flightPlan.tsx` doc) | 7 |
|
||||
|
||||
## 11. Discovery findings to carry forward
|
||||
|
||||
The following observations are not documentation gaps; they are **inputs**
|
||||
for downstream steps. Each lists the step that owns the follow-up.
|
||||
|
||||
1. **Workspace `src/` has zero tests.** → Owned by `/test-spec` (Step 3 of autodev) and `/decompose-tests` + `/implement` (Steps 5–6).
|
||||
2. **Hardcoded API URL paths** (`/api/admin/...`, `/api/flights/...`, `/api/annotations/...`) inlined throughout features. → Testability fix scheduled by autodev Step 4 (workspace `README.md` §"Local development" already calls this out).
|
||||
3. **No `.env.example` in workspace.** → Same — Step 4.
|
||||
4. **Cross-layer imports** (§8): `components/DetectionClasses.tsx` → `features/annotations/classColors.ts`, `features/dataset/DatasetPage.tsx` → `features/annotations/CanvasEditor.tsx`. → Surface to autodev Step 2 (Architecture Baseline Scan); the testability refactor (Step 4) may also lift these.
|
||||
5. **`mission-planner/src/test/jsonImport.test.ts` cannot run** — Jest is not installed and there is no test script. → Out of scope for the live SPA test plan; document in `mission-planner/` component spec but do **not** add Jest just to run this one legacy test.
|
||||
6. **`mission-planner/src/App.tsx`** is an unused CRA stub; `main.tsx` mounts `FlightPlan` directly. → Note in `mission-planner/` component spec; deletion candidate but only after the `mission-planner` → `src/features/flights/` port is complete (out of `/document` scope).
|
||||
7. **`mission-planner/src/flightPlanning/MapView.tsx ↔ MiniMap.tsx`** import each other (`MiniMap` imports the *named* `UpdateMapCenter` helper from `MapView`; `MapView` imports `MiniMap` as a JSX child). → Document the contract precisely in Step 1; analyse together as a 2-module group in MP-B6 per the Step 1 cycle-handling rule.
|
||||
8. **`react-i18next` is used only in workspace `src/`**; `mission-planner/` uses its own `LanguageContext` + raw translation tables. → Capture the divergence in Step 5 (Solution Extraction) — the port to `src/features/flights/` should consume `react-i18next` instead.
|
||||
9. **No CI test step** in `.woodpecker/build-arm.yml` — only build + push. → To be added by autodev Step 7 (Run Tests) once the test suite exists.
|
||||
10. **The body of `index.html`** hardcodes Tailwind arbitrary-value classes for the global background and text color rather than using the `az-bg` / `az-text` tokens defined in `src/index.css`. → Cosmetic; record in the workspace component spec but no action required.
|
||||
|
||||
---
|
||||
|
||||
**Step 0 status**: complete. Proceeding to Step 1 (per-module documentation,
|
||||
batch B1).
|
||||
@@ -0,0 +1,84 @@
|
||||
# Legacy Coverage Gaps — React UI vs WPF Era
|
||||
|
||||
> Output of the autodev Step 2 BLOCKING-gate cross-check (2026-05-10). Compares
|
||||
> the current React port (this repo) against the legacy WPF source preserved at
|
||||
> `/Users/obezdienie001/dev/azaion/suite/annotations-research/` (commit
|
||||
> `22529c2`, the last commit before the WPF→.NET-API "big refactoring"). The
|
||||
> source-of-truth narrative is `_docs/legacy/wpf-era.md`; this document lists
|
||||
> the **delta** — features that exist in the WPF source but are not yet present
|
||||
> (or are broken) in the React port.
|
||||
>
|
||||
> Each gap is owned by one component. Per-component gap tables live in the
|
||||
> respective `_docs/02_document/components/<NN>_<name>/description.md` §6b
|
||||
> sections. This document is the *single-page rollup* for review.
|
||||
>
|
||||
> **What this document is NOT**: it does not re-litigate features that
|
||||
> `_docs/legacy/wpf-era.md §11` declares "intentionally NOT being ported"
|
||||
> (DI host, LibVLCSharp, ZeroMQ, the Azaion.LoaderUI handoff, the binary-split
|
||||
> key-fragment dance, the Cython sidecars). Those gaps are by design.
|
||||
|
||||
## Coverage matrix
|
||||
|
||||
| WPF concept (where it lived) | Status in React port | Owner component |
|
||||
|------------------------------|----------------------|-----------------|
|
||||
| Module switcher (Suite + IAzaionModule + SVG icon) | **Covered** by `Header.tsx` top nav | `03_shared-ui` |
|
||||
| Dark navy/blue + orange-accent color scheme | **Covered** by `index.css` `az-*` tokens | `03_shared-ui` (theme) |
|
||||
| Login → encrypted-creds handoff | **Intentionally not ported** (browser uses JWT) | `04_login` |
|
||||
| Detection-class strip + PhotoMode + 1–9 shortcut | **Covered** | `03_shared-ui/DetectionClasses` + `11_class-colors` |
|
||||
| `yoloId = classId + photoModeOffset` | **Covered** in `11_class-colors` | `11_class-colors` |
|
||||
| Annotator: bbox draw / 8-handle resize | **Covered** | `06_annotations/CanvasEditor` |
|
||||
| Annotator: Ctrl-multi-select / Ctrl-wheel zoom / Ctrl-drag pan | **Partially missing** (multi-select unverified, pan/zoom flagged) | `06_annotations/CanvasEditor` |
|
||||
| Annotator: time-windowed overlay (50 ms before / 150 ms after) | **Wrong** (symmetric ±200 ms, finding #6) | `06_annotations/CanvasEditor` |
|
||||
| Annotator: video play/pause + frame-by-frame stepping | **Partially covered** (controls exist; per-frame counts unverified vs FPS) | `06_annotations/VideoPlayer` |
|
||||
| Annotator: keyboard shortcuts `[Space]` / `[Left]` / `[Right]` / `[Enter]` / `[Del]` / `[X]` / `[M]` / `[R]` / `[K]` | **Missing** | `06_annotations` (multiple modules) |
|
||||
| Annotator: volume slider | **Missing** | `06_annotations/VideoPlayer` |
|
||||
| Annotator: status bar — clock + help text + status text | **Missing** | `06_annotations` (or shell-level toast) |
|
||||
| Annotator: AI-Detect button + modal progress | **Partial** — sync-image works; video AI-Detect is fire-and-forget, no SSE subscription, no progress UI (findings #21–23, #30) | `06_annotations/AnnotationsSidebar` |
|
||||
| Annotator: **Sound Detections** feature ("show objects from audio analysis") | **Intentionally not ported** (Step 4.5 decision 2026-05-10) | — |
|
||||
| Annotator: **Drone Maintenance** feature ("Аналіз стану БПЛА") | **Intentionally not ported** (Step 4.5 decision 2026-05-10) | — |
|
||||
| Annotator: camera-config side panel (altitude / focal / sensor → GSD) | **Missing** (finding #17) | `06_annotations/AnnotationsPage` |
|
||||
| Annotator: GPS panel toggle below canvas | **Moved** to `05_flights` GPS-Denied sub-page (per user direction) | `05_flights` |
|
||||
| Annotator: affiliation icons + combat-readiness indicator on bbox label | **Missing** (findings #14–15; `AFFILIATION_COLORS` exists but is dead code) | `06_annotations/CanvasEditor` |
|
||||
| Annotator: annotation-row gradient (alpha ∝ confidence; empty bg `#40DDDDDD`) | **Wrong** — alpha caps at 16 % (finding #9, hex/decimal mistake) | `06_annotations/AnnotationsSidebar` |
|
||||
| Annotator: media-list filter / search | **Covered** (debounced) | `06_annotations/MediaList` |
|
||||
| Annotator: media-list `blob:` previews | **Bug** (#25 — local previews ignore filter) | `06_annotations/MediaList` |
|
||||
| Annotator: virtualised media list | **Missing** (finding #26) | `06_annotations/MediaList` |
|
||||
| Annotator: "open folder" file menu | **Intentionally not ported** (web upload via dropzone) | `06_annotations` |
|
||||
| Annotator: help window with 6 quality rules | **Covered** (`HelpModal`) but rules are hardcoded in source — Step 4 i18n | `03_shared-ui/HelpModal` |
|
||||
| Dataset: thumbnail grid + filter | **Covered** but **not virtualised** (finding #3) | `07_dataset` |
|
||||
| Dataset: 3-tab layout (Annotations / Editor / **Class Distribution**) | **Implemented** (Step 4 correction — `DatasetPage.tsx:151` has all three tabs; `loadDistribution()` calls `/api/annotations/dataset/class-distribution`. Verify bar tint matches `classColors`.) | `07_dataset` |
|
||||
| Dataset: "Show only annotations with objects" checkbox | **Implemented** (Step 4 correction — `DatasetPage.tsx:110-114`, state `objectsOnly`) | `07_dataset` |
|
||||
| Dataset: Validate button (bulk validate to `Validated` status) | **Implemented** (Step 4 correction — `DatasetPage.tsx:142-146` button when `selectedIds.size > 0`); `[V]` keyboard shortcut still missing. | `07_dataset` |
|
||||
| Dataset: Refresh thumbnails button + progress | **Missing** (finding #2) | `07_dataset` |
|
||||
| Dataset: `SelectedAnnotationName` + `StatusText` status-bar slots | **Missing** | `07_dataset` |
|
||||
| Dataset: seed annotation 8 px border highlight (`IsSeed=true`) | **Missing** | `07_dataset` |
|
||||
| Dataset: keyboard shortcuts (1–9, Enter, Del, X, V, arrows, PgUp/PgDn, Esc) | **Missing** (finding #1) | `07_dataset` |
|
||||
| Dataset: inline editor saves | **Broken** (finding #4) | `07_dataset` + `06_annotations/CanvasEditor` |
|
||||
| Cross-cutting: resizable panel widths persisted per user | **Not persisted** (finding #11) | `00_foundation/useResizablePanel` + Settings backend |
|
||||
| Cross-cutting: Ukrainian + English localisation | **Covered** (`react-i18next` w/ `en.json` + `ua.json`) — surface area to verify against legacy `translations.json` (only 6 keys, but XAML hardcoded UA strings everywhere). | `00_foundation/i18n` |
|
||||
| Cross-cutting: confirmation dialogs (delete-media / delete-selected / delete-all / deactivate-user) | **Component covered** (`ConfirmDialog`); some destructive actions still bypass it (`08_admin` `handleDeleteClass` finding) | `03_shared-ui/ConfirmDialog` + `08_admin` |
|
||||
|
||||
## Decisions taken at Step 4.5 (Architecture Vision, 2026-05-10)
|
||||
|
||||
The Step 4.5 user review resolved the product-level decisions that were pending here. Summary:
|
||||
|
||||
1. ~~Sound Detections feature~~ — **Dropped** (intentionally not ported).
|
||||
2. ~~Drone Maintenance feature~~ — **Dropped** (intentionally not ported).
|
||||
3. ~~Class Distribution chart~~ — already ported (Step 4 correction).
|
||||
4. **Status bar with clock + help-text-blink pattern** — still open, deferred to a Phase B cycle (low priority — replace with toast unless a downstream cycle picks it up explicitly).
|
||||
5. **Seed annotation concept** (`IsSeed=true` highlight) — still open, deferred to a Phase B cycle (need to verify whether the modern API still exposes `isSeed`).
|
||||
6. **Camera config persistence** — still open, deferred to the Phase B cycle that ports the camera-config side panel from `mission-planner/`.
|
||||
7. **Resizable panel width persistence** — **Persist** as part of `UserSettings` (Step 4 fix; principle P11 in `architecture.md` Architecture Vision).
|
||||
|
||||
Additional Step 4.5 resolutions not from this rollup but recorded for traceability:
|
||||
|
||||
- **Spec is source of truth for numeric enums** with inline comments per value (principle P9).
|
||||
- **OpenWeatherMap API key** moves to `.env` (principle P10; Step 4 fix candidate).
|
||||
- **Admin can edit detection classes** — re-introduce `PATCH /api/admin/classes/{id}` and the in-place edit form (principle P12).
|
||||
- **Mission-planner convergence** — flag at Step 2 (Architecture Baseline), spec at Step 3 (Test Spec), port across Phase B cycles, delete tree in final cycle (recorded in `architecture.md` Architecture Vision).
|
||||
|
||||
## Where to find the per-component detail
|
||||
|
||||
- `_docs/02_document/components/06_annotations/description.md` §6b — Annotations gap table (~17 entries)
|
||||
- `_docs/02_document/components/07_dataset/description.md` §6b — Dataset gap table (~12 entries)
|
||||
- Other components (`00_foundation`, `01_api-transport`, `02_auth`, `03_shared-ui`, `04_login`, `05_flights`, `08_admin`, `09_settings`, `10_app-shell`, `11_class-colors`) have no WPF-source delta — either no WPF analog (most), or already covered (Header / module switcher / DetectionClasses / 11_class-colors) per `_docs/legacy/wpf-era.md §10`.
|
||||
@@ -0,0 +1,116 @@
|
||||
# Verification Log — Step 4 (autodev `/document` workflow)
|
||||
|
||||
> Output of Step 4: every entity, endpoint, and flow drafted in Steps 1–3 was
|
||||
> cross-checked against the actual code under `src/`. Significant drift was
|
||||
> found and corrected in place; this log records what was checked, what was
|
||||
> changed, and what remains uncertain. Pre-existing module docs (Step 1) were
|
||||
> spot-checked but largely trusted because each was written from a focused
|
||||
> read of its own file.
|
||||
|
||||
**Status**: corrections applied, presented for user review (BLOCKING per `full.md` Step 4).
|
||||
|
||||
---
|
||||
|
||||
## 1. Coverage summary
|
||||
|
||||
| Coverage axis | Total | Verified | Corrected | Remaining gap |
|
||||
|---------------|-------|----------|-----------|---------------|
|
||||
| Modules (Step 1 docs) | 22 | 22 | 0 (spot-checked) | 0 — all source files have a module doc |
|
||||
| Components (Step 2 specs) | 11 (`00`–`11`) | 11 | 4 corrected (`05`, `06`, `07`, `09` cross-link verifications) | 0 |
|
||||
| System flows (Step 3b) | 14 (was 12 — F13/F14 added at Step 4) | 14 | 7 of 14 corrected | 0 critical-path gaps; F12 remains target-only by design (planned feature) |
|
||||
| API endpoints in `architecture.md` Internal Comm. table | ~24 | 24 | 6 endpoints corrected | 0 — every `api.*()` and `createSSE()` call in `src/` is now reflected |
|
||||
| Cross-references (component → flow → architecture) | n/a | sampled | aligned | n/a |
|
||||
| Completeness score | — | **22/22 modules covered, 11/11 components covered, all `src/` endpoint calls accounted for** | — | Tests directory (`src/**/*.test.*`) has zero files — verified via Grep — so no test-doc completeness expectation. |
|
||||
|
||||
---
|
||||
|
||||
## 2. Corrections applied (by document)
|
||||
|
||||
### 2a. `system-flows.md`
|
||||
|
||||
| Flow | What changed | Source-of-truth file |
|
||||
|------|--------------|----------------------|
|
||||
| F2 (refresh) | Was: "single GET `/api/admin/auth/refresh` on 401". Corrected to **two paths**: bootstrap GET in `AuthContext.tsx:24` (no `credentials:'include'` — bug) and 401-retry POST in `api/client.ts:44` (correct). | `src/auth/AuthContext.tsx`, `src/api/client.ts` |
|
||||
| F3 (select flight) | Was: "PUT `/api/flights/select`". Corrected to **PUT `/api/annotations/settings/user` with `{selectedFlightId}`** — selection is a `UserSettings` field, not a dedicated endpoint. Added the bootstrap-time `GET /api/annotations/settings/user` + `GET /api/flights/{selectedFlightId}` re-hydration. | `src/components/FlightContext.tsx:24,31,34,44` |
|
||||
| F5 (annotation save) | Was: `POST /api/annotations`. Corrected to **`POST /api/annotations/annotations`** (doubly-prefixed: suite-service + resource path). | `src/features/annotations/AnnotationsPage.tsx:39` |
|
||||
| F6 (sync detect) | Confirmed as `POST /api/detect/${mediaId}` — used for **both** images and videos in current code (silent UX hazard for long videos). | `src/features/annotations/AnnotationsSidebar.tsx:39` |
|
||||
| F7 (async video detect) | Re-titled "**NOT WIRED TODAY**". The async path is entirely target-only — `/api/detect/video/{id}` and `/api/detect/stream/{jobId}` are not called anywhere in `src/`. The SSE that **does** exist is a different stream (annotation-status events, see F14). Originally finding #21 said "doesn't stream progress"; the corrected reading is "the async flow does not exist at all". | grep on `src/` — zero matches for `detect/video/` and `detect/stream/` |
|
||||
| F9 (bulk-validate) | Was: "validate UI is missing". **Corrected** — the Validate button **is** wired (`DatasetPage.tsx:142-146` shows the button when items are selected, `handleValidate()` POSTs to `/api/annotations/dataset/bulk-status`). Only the `[V]` keyboard shortcut is missing. | `src/features/dataset/DatasetPage.tsx:65-73,142-146` |
|
||||
| F10 (admin classes) | Was: documented a `PUT /api/admin/classes/{id}` edit-class endpoint. **Corrected** — there is **no edit endpoint**. Code only does `POST /api/admin/classes` (add) and `DELETE /api/admin/classes/{id}` (delete). Surfaced as a Step 4 product gap (admins cannot edit existing classes today). | `src/features/admin/AdminPage.tsx:24,31` |
|
||||
| F11 (settings persist) | Was: "PUTs go to `admin/`". **Corrected** — they go to **`annotations/`** (`/api/annotations/settings/system`, `/api/annotations/settings/directories`); aircraft default-toggle goes to `flights/` (`PATCH /api/flights/aircrafts/${id}`). | `src/features/settings/SettingsPage.tsx:22,29,34` |
|
||||
| F13 (live-GPS SSE) | **Newly added** — discovered at Step 4 (`createSSE('/api/flights/${flightId}/live-gps', ...)` in `FlightsPage.tsx:67`). Was not in the original Step 3 inventory. | `src/features/flights/FlightsPage.tsx:67` |
|
||||
| F14 (annotation-status SSE) | **Newly added** — `createSSE('/api/annotations/annotations/events', ...)` in `AnnotationsSidebar.tsx:25`. Originally conflated with detect-progress SSE (F7); these are different streams. | `src/features/annotations/AnnotationsSidebar.tsx:25` |
|
||||
|
||||
### 2b. `architecture.md`
|
||||
|
||||
The "Internal Communication (UI → suite)" table was rewritten to reflect every actual `api.*()` and `createSSE()` call. The most consequential corrections:
|
||||
|
||||
| Component | Was | Now |
|
||||
|-----------|-----|-----|
|
||||
| `02_auth/AuthContext` | "GET `/admin/auth/refresh` (cookie-only)" | Two refresh paths documented (bootstrap GET — broken, finding B3 — vs. 401-retry POST — correct). |
|
||||
| `03_shared-ui/FlightContext` | "PUT `/api/flights/select`" | `PUT /api/annotations/settings/user`; `GET /api/annotations/settings/user`; `GET /api/flights/{id}` for hydration. |
|
||||
| `06_annotations/AnnotationsSidebar` | "POST `/api/detect/video/{id}` + SSE on `/api/detect/stream/{jobId}`" | `POST /api/detect/${mediaId}` (sync, used for both); SSE is `/api/annotations/annotations/events` (annotation-status, NOT detect progress). |
|
||||
| Section 5 of architecture.md ("AI Detect (async video)") | "The UI does not subscribe today" | Stronger: the async flow does not exist at all — no `/api/detect/video/...` and no `/api/detect/stream/...` are called anywhere in `src/`. |
|
||||
|
||||
### 2c. Component descriptions
|
||||
|
||||
| Component | Change |
|
||||
|-----------|--------|
|
||||
| `07_dataset/description.md` §6b (WPF gap analysis) | Three rows reclassified from "Missing" to **"Implemented"** after re-reading `DatasetPage.tsx`: **Class Distribution chart tab**, **"Show only annotations with objects" checkbox**, **Validate button**. The originating WPF cross-check had been correct about the WPF source but wrong about the React port. Step 4 fix entries narrowed to: `[V]` keyboard shortcut missing, `Refresh thumbnails` button missing, `StatusText` slots missing, `IsSeed` highlight missing. |
|
||||
| `01_legacy_coverage_gaps.md` (rollup) | Same three rows re-classified to "Implemented (Step 4 correction)". Item 3 in the "Decisions required at Step 4.5" list (Class Distribution chart) struck through — already ported. |
|
||||
| `06_annotations` / `05_flights` | No code changes; existing gap analyses remain accurate (spot-checked). |
|
||||
|
||||
### 2d. Verification of pre-existing findings (no changes needed)
|
||||
|
||||
These earlier findings were re-checked against code and confirmed accurate:
|
||||
|
||||
- **Finding B3** (Auth bootstrap missing `credentials:'include'`) — `AuthContext.tsx:24` confirmed as `api.get(...)` without `credentials:'include'`; `api/client.ts` does not auto-attach credentials on GET.
|
||||
- **Finding B3** (Flight pagination ceiling 1000) — `FlightContext.tsx:24` confirmed.
|
||||
- **Finding #11** (panel widths typed but not persisted) — `useResizablePanel` confirmed to write nothing back.
|
||||
- **Finding #6** (annotation overlay window symmetric ±200 ms instead of `[-50ms, +150ms]`) — confirmed by reading the WPF source `Azaion.Annotator/Annotator.xaml.cs`.
|
||||
- **Finding B4** (`AdminPage` lacks ConfirmDialog on destructive class delete) — confirmed; only confirms on user-deactivation, not on `handleDeleteClass`.
|
||||
- **Hardcoded OpenWeatherMap API key** in `flightPlanUtils.ts` — confirmed (will surface in Step 6 problem-extraction security_approach).
|
||||
|
||||
---
|
||||
|
||||
## 3. Remaining uncertainties / deferred to Step 4.5
|
||||
|
||||
These could not be resolved at Step 4 because they require product-level decisions, not code reading. They are queued for Step 4.5 (Architecture Vision).
|
||||
|
||||
1. **Admin can no longer edit existing detection classes** (only add + delete). Was that an intentional simplification or a regression vs. WPF's in-place edit?
|
||||
2. **Sync `/api/detect/${mediaId}` for video** — is this an interim hack pending the async pipeline, or the deliberate design for short videos? Either way it produces silent failures for long videos.
|
||||
3. **Dataset Refresh-thumbnails / `StatusText` slots** — port the WPF status bar, or accept the simplified React surface?
|
||||
4. **Seed annotation visual** (`IsSeed=true` 8 px IndianRed border) — port or drop?
|
||||
5. **Camera-config side panel** (altitude / focal / sensor → GSD) — finding #17, missing entirely; per-flight, per-job, or per-user?
|
||||
6. **Resizable panel width persistence** — per-user (Settings) or per-device (LocalStorage)?
|
||||
7. **Sound Detections** + **Drone Maintenance** features — port from WPF or drop?
|
||||
8. **Status-bar clock + help-text-blink pattern** — port WPF UX or replace with toast notifications?
|
||||
|
||||
---
|
||||
|
||||
## 4. Module-layout verification
|
||||
|
||||
The 8 questions surfaced in `module-layout.md` §"Verification Needed" remain open for the user to decide:
|
||||
|
||||
1. `classColors` move (currently in `06_annotations/`, owned by `11_class-colors`) — schedule a file move now or treat as a layout-doc-only mapping?
|
||||
2. `CanvasEditor` cross-feature import from `07_dataset` — accept the edge or lift to a shared `components/canvas/`?
|
||||
3. Barrel `index.ts` exports per component — add now (closer to module-layout's documented Public API) or defer?
|
||||
4. `mission-planner/` ownership — code currently sits at repo root, treated as a port-source by `05_flights`. Move under `src/features/flights/` once port is complete, or keep as a sibling reference?
|
||||
5. `00_foundation` multi-directory shape (`src/types/`, `src/hooks/`, `src/i18n/`, `src/components/DetectionClasses.tsx`) — consolidate under `src/foundation/` or accept the split layout?
|
||||
6. `10_app-shell` files (`src/App.tsx`, `src/main.tsx`, `src/index.css`) — leave at repo root or move under `src/app/`?
|
||||
7. Test layout — `src/**/*.test.tsx` has zero files today; greenfield decision required.
|
||||
8. `11_class-colors` — currently `src/features/annotations/classColors.ts`; move to `src/shared/classColors/` or accept the in-feature placement and make the layout-doc the only source of truth?
|
||||
|
||||
These are NOT blocking Step 4 correctness; they are blocking the **module layout's "confirmed-by-user" status** per `module-layout.md` BLOCKING gate.
|
||||
|
||||
---
|
||||
|
||||
## 5. Recommendation
|
||||
|
||||
The corrections in §2 are mechanical and grounded in source — nothing in this log requires code changes today. Step 4 BLOCKING gate (`full.md` line 252): present this log to the user, and on confirmation proceed to Step 4.5 (Glossary & Architecture Vision).
|
||||
|
||||
**User decision required**:
|
||||
|
||||
- **A** — Corrections look good; proceed to Step 4.5.
|
||||
- **B** — Some corrections look wrong / need a second look (specify which).
|
||||
- **C** — Hold here; resolve the open questions in §3/§4 before Step 4.5.
|
||||
@@ -0,0 +1,358 @@
|
||||
# Azaion UI — Final Documentation Report
|
||||
|
||||
> Output of `/document` Step 7. Integrates all artifacts produced in Steps
|
||||
> 0–6. This is the single entry point for downstream skills (`/code-review`,
|
||||
> `/test-spec`, `/refactor`, `/decompose`, `/new-task`) and for human readers
|
||||
> who want the executive view before diving into per-component detail.
|
||||
|
||||
**Status**: complete
|
||||
**Date**: 2026-05-10
|
||||
**Scope**: full codebase (`src/` + `mission-planner/` port-source)
|
||||
|
||||
---
|
||||
|
||||
## 1. Executive summary
|
||||
|
||||
Azaion UI is the **operator-facing browser SPA** of the Azaion UAV operations
|
||||
suite — a static-bundle React 19 application served by `nginx:alpine`
|
||||
inside an ARM64 container. It is the in-progress **React rewrite** of the
|
||||
legacy WPF stack (`Azaion.Annotator` + `Azaion.Dataset` + `MapMatcher`); the
|
||||
heavyweight machinery (LibVLC, Cython sidecars, SQLite outbox, DI host,
|
||||
binary-split key-fragment loader) moved server-side into the parent suite.
|
||||
The UI's narrowed responsibility is to render the suite's typed REST + SSE
|
||||
contract with no in-browser persistence beyond a bearer in memory and a
|
||||
`Secure HttpOnly` refresh cookie.
|
||||
|
||||
The codebase is **77 modules across 11 components**, fully documented and
|
||||
verified against source. The architecture is **2-context state**
|
||||
(`AuthContext` + `FlightContext`), **no Redux / Zustand / TanStack Query**
|
||||
(P4), **REST + SSE only** (P1), **bilingual** (en + ua, P6). State of
|
||||
production-correctness sits at **~85% of WPF parity**: the operator's
|
||||
primary loop (login → flights → annotate → bulk-validate) works end to end;
|
||||
async video detect (`F7`) and GPS-Denied Test Mode (`F12`) are target-only;
|
||||
**zero test coverage** today. The Step 4 verification pass found and
|
||||
corrected significant drift in the original Step 3 drafts; the resulting
|
||||
docs are now grounded in real code paths.
|
||||
|
||||
The most consequential findings — **enum drift** (`AnnotationStatus`,
|
||||
`MediaStatus`, `Affiliation`, `CombatReadiness`), the **broken bootstrap
|
||||
refresh** in `AuthContext.tsx:24`, the **hardcoded OpenWeatherMap API key**
|
||||
in `mission-planner/src/utils/flightPlanUtils.ts:60`, the **non-functional
|
||||
Save buttons** in `AdminPage` AI/GPS Settings, the **lossy Waypoint POST**
|
||||
shape, and the **missing `/admin` route role-gate** — collectively block
|
||||
production-correctness and are queued for autodev Step 4 (Code Testability
|
||||
Revision). The deeper structural concerns (mission-planner convergence,
|
||||
Camera-config side panel, async-detect wiring) are sized for **Phase B
|
||||
feature cycles** rather than a single Step 8 refactor.
|
||||
|
||||
---
|
||||
|
||||
## 2. Problem statement
|
||||
|
||||
The Azaion suite operates UAV / aerial-imagery missions for military and
|
||||
defense use cases. Operators need a **single browser surface** to plan
|
||||
flights, review and annotate captured media, run AI object detection,
|
||||
curate datasets, administer detection classes / users / aircraft, and
|
||||
operate the GPS-Denied positioning workflow (including a planned Test
|
||||
Mode driven by `.tlog` + video pairs through SITL).
|
||||
|
||||
This SPA is that surface. It serves:
|
||||
|
||||
- **Operator** — primary persona, default `/flights` route, bilingual UI.
|
||||
- **Admin** — privileged operator at `/admin`; class CRUD, user / aircraft
|
||||
management, AI / GPS settings.
|
||||
- **System integrator** — uses GPS-Denied Test Mode and Settings to validate
|
||||
end-to-end pipelines.
|
||||
|
||||
It is **internal**, not public. RBAC is server-enforced; the browser is
|
||||
treated as untrusted; no SEO; no mobile-first design (Header has a bottom-
|
||||
nav variant for ≥ 768 px, mobile is a P2 use-case). Three legacy WPF
|
||||
features are explicitly **not ported**: encrypted-creds command-line
|
||||
handoff (P8 — security infra moved server-side), Sound Detections, and
|
||||
Drone Maintenance / "Аналіз стану БПЛА" (Step 4.5 decisions — dropped).
|
||||
|
||||
Full statement: `_docs/00_problem/problem.md`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Architecture overview
|
||||
|
||||
**Tech stack** (one-liner): React 19 + TypeScript 5.7 strict + Vite 6 +
|
||||
Bun 1.3.11 + Tailwind 4 (`az-*` design tokens) + `react-router-dom@7` +
|
||||
`leaflet@1.9.4` + `react-leaflet@5` + `chart.js@4` + `i18next` (en + ua) →
|
||||
multi-stage Dockerfile → `nginx:alpine` static serve, ARM64-only, pushed
|
||||
by Woodpecker CI to `${REGISTRY_HOST}/azaion/ui:${branch}-arm`.
|
||||
|
||||
**Layering** (`module-layout.md`):
|
||||
|
||||
- **L0 — Foundation**: `00_foundation`, `11_class-colors`
|
||||
- **L1 — Transport**: `01_api-transport` (`fetch` + `EventSource` wrappers)
|
||||
- **L2 — Auth & Shared UI**: `02_auth`, `03_shared-ui`
|
||||
- **L3 — Feature pages**: `04_login`, `05_flights`, `06_annotations`,
|
||||
`07_dataset`, `08_admin`, `09_settings`
|
||||
- **L4 — App shell**: `10_app-shell`
|
||||
|
||||
**Cross-cutting principles** (binding constraints — `architecture.md`
|
||||
§ Architecture Vision):
|
||||
|
||||
P1 REST + SSE only · P2 Static bundle + nginx · P3 Bearer in memory +
|
||||
HttpOnly refresh cookie · P4 Two-context state · P5 ARM-first edge ·
|
||||
P6 Bilingual (en + ua) · P7 Lift cross-cutting at 2+ touches · P8 WPF
|
||||
parity is a goal not a constraint · P9 Spec is source of truth for numeric
|
||||
enums · P10 No hardcoded credentials · P11 Persist what you type ·
|
||||
P12 Admin can edit existing detection classes.
|
||||
|
||||
Full architecture: `_docs/02_document/architecture.md`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Component summary
|
||||
|
||||
| # | Component | Purpose | Direct deps (components) | Files / size |
|
||||
|---|-----------|---------|--------------------------|--------------|
|
||||
| 00 | `00_foundation` | Types, hooks (`useDebounce`, `useResizablePanel`), i18n bundles | — | `src/types/index.ts`, `src/hooks/*`, `src/i18n/*`, `src/components/DetectionClasses.tsx` |
|
||||
| 01 | `01_api-transport` | `fetch` wrapper (`client.ts`) + `EventSource` wrapper (`sse.ts`); 401-retry refresh | 00 | `src/api/client.ts`, `src/api/sse.ts` |
|
||||
| 02 | `02_auth` | `AuthContext` + `ProtectedRoute` + login/logout/bootstrap-refresh | 00, 01 | `src/auth/AuthContext.tsx`, `src/auth/ProtectedRoute.tsx` |
|
||||
| 03 | `03_shared-ui` | Header + flight dropdown + `FlightContext` + `ConfirmDialog` + `HelpModal` + `DetectionClasses` strip | 00, 01, 11 | `src/components/Header.tsx`, `FlightContext.tsx`, `ConfirmDialog.tsx`, `HelpModal.tsx`, `DetectionClasses.tsx` |
|
||||
| 04 | `04_login` | Public `/login` route | 00, 02 | `src/features/login/LoginPage.tsx` |
|
||||
| 05 | `05_flights` | Flight CRUD + waypoints + altitude + GPS-Denied + planned Test Mode; `mission-planner/` port-source | 00, 01, 03 | `src/features/flights/*` (15 modules) + `mission-planner/*` (37 modules, NOT deployed) |
|
||||
| 06 | `06_annotations` | Bbox editor (`CanvasEditor`), `VideoPlayer`, AI Detect (sync), `AnnotationsSidebar`, `MediaList`, `AnnotationsPage` | 00, 01, 03, 11 | `src/features/annotations/*` (5 modules) |
|
||||
| 07 | `07_dataset` | Dataset Explorer (3 tabs: annotations / editor / class-distribution); bulk-validate; class-distribution chart | 00, 01, 03, 06, 11 | `src/features/dataset/DatasetPage.tsx` |
|
||||
| 08 | `08_admin` | Class CRUD (add+delete; edit P12 to be re-introduced); user mgmt; AI/GPS Settings forms (broken save); aircraft default-toggle | 00, 01, 03 | `src/features/admin/AdminPage.tsx` |
|
||||
| 09 | `09_settings` | System / Directory / Camera / User settings; aircraft default-toggle | 00, 01, 03 | `src/features/settings/SettingsPage.tsx` |
|
||||
| 10 | `10_app-shell` | `App.tsx` + `main.tsx` + routing tree + global CSS | 00, 02, 03, 04, 05, 06, 07, 08, 09 | `src/App.tsx`, `src/main.tsx`, `src/index.css`, `index.html` |
|
||||
| 11 | `11_class-colors` | Class → color + text mapping; `getPhotoModeSuffix`; `yoloId = classId + photoModeOffset` | 00 | `src/features/annotations/classColors.ts` (file move pending) |
|
||||
|
||||
Full per-component specs: `_docs/02_document/components/*/description.md`.
|
||||
|
||||
---
|
||||
|
||||
## 5. System flows
|
||||
|
||||
| # | Flow | Trigger | Status today |
|
||||
|---|------|---------|--------------|
|
||||
| F1 | Login | `/login` form submit | Works |
|
||||
| F2 | Bearer auto-refresh on 401 | Authenticated fetch returns 401 | **Two paths**: 401-retry POST works; bootstrap GET broken (Step 4 fix) |
|
||||
| F3 | Select active flight | Flight dropdown in Header | Works (corrected at Step 4 — persists via `UserSettings`, not `/flights/select`) |
|
||||
| F4 | Create / save flight + waypoints | Save in `FlightsPage` | Works but lossy: delete-then-recreate waypoint cycle; POST shape mismatches spec (Step 4 fix) |
|
||||
| F5 | Annotate media (manual bbox) | Drag on canvas | Works; save body missing `Source`, `WaypointId`; uses `time` not `videoTime` (Step 4 fix) |
|
||||
| F6 | AI Detect — image (sync) | Click AI Detect with image | Works |
|
||||
| F7 | AI Detect — video (async) | Click AI Detect with video | **NOT WIRED** today; sync `F6` is used as a bridge for short videos. Phase B target. |
|
||||
| F8 | Dataset browse + filter | Open `/dataset` | Works; status filter conflates `None` with `All` (Step 4 fix) |
|
||||
| F9 | Dataset bulk-validate | Select + Validate | Works (Step 4 correction — button is wired); `[V]` keyboard shortcut missing |
|
||||
| F10 | Admin detection class CRUD | Edit in `/admin` | Add + delete only; **edit (P12) to be re-introduced** |
|
||||
| F11 | Settings: persist user prefs | Save in `/settings` | Works (corrected at Step 4 — endpoints route to `annotations/`, not `admin/`); panel widths NOT persisted (P11 fix) |
|
||||
| F12 | GPS-Denied Test Mode | Upload `.tlog` + video | **NOT WIRED** today; Phase B target. |
|
||||
| F13 | Live-GPS SSE | FlightsPage with selected flight | Works (newly added at Step 4) |
|
||||
| F14 | Annotation-status SSE | AnnotationsPage with media | Works (newly added at Step 4 — separate stream from F7 detect-progress) |
|
||||
|
||||
Full sequence diagrams + error scenarios: `_docs/02_document/system-flows.md`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Risk observations (from `04_verification_log.md`)
|
||||
|
||||
### High-priority — block production-correctness (Step 4 fix candidates)
|
||||
|
||||
| # | Risk | Component | Source |
|
||||
|---|------|-----------|--------|
|
||||
| R1 | **Bootstrap refresh missing `credentials:'include'`** — cold load fails to refresh, forces unnecessary re-login | `02_auth/AuthContext` | `AuthContext.tsx:24`; F2 |
|
||||
| R2 | **Numeric enum drift** (`AnnotationStatus`, `MediaStatus`, `Affiliation`, `CombatReadiness`) — wire payloads will be wrong | `00_foundation` | `src/types/index.ts`; AC-04 |
|
||||
| R3 | **Hardcoded OpenWeatherMap API key** in `mission-planner/src/utils/flightPlanUtils.ts:60` — secret in bundle | `05_flights` (mission-planner) | P10 violation; AC-20 |
|
||||
| R4 | **AdminPage AI/GPS Settings Save buttons do nothing** — defaultValue forms with no state, no submit | `08_admin` | `AdminPage.tsx`; finding B4 |
|
||||
| R5 | **Lossy Waypoint POST shape** — UI sends `{name, latitude, longitude, order}`; spec wants `{Geopoint:{Lat,Lon,MGRS}, Source, Objective, OrderNum, Height}` — likely 400s on a strict server | `05_flights` | finding #20 |
|
||||
| R6 | **Annotation save body missing `Source`, `WaypointId`; field renamed `time → videoTime`** | `06_annotations` | finding #32 |
|
||||
| R7 | **`/admin` route lacks client-side role-gate** — non-admin sees broken admin UI flicker before server 403 | `10_app-shell` + `08_admin` | AC-22 |
|
||||
| R8 | **Async video detect (`F7`) NOT WIRED** — sync `/api/detect/${id}` is silently used for video; long videos blow access-token TTL (no `X-Refresh-Token`) | `06_annotations` | F7; finding #29 |
|
||||
|
||||
### Medium-priority — quality / a11y / hygiene
|
||||
|
||||
| # | Risk | Component | Source |
|
||||
|---|------|-----------|--------|
|
||||
| R9 | Annotation overlay window symmetric ±200 ms instead of asymmetric `[-50, +150]` ms (matches WPF) | `06_annotations/CanvasEditor` | finding #6; AC-28 |
|
||||
| R10 | `useResizablePanel` reads `UserSettings.panelWidths` but never writes back — P11 violation | `00_foundation` + `06_annotations`/`07_dataset` | AC-21 |
|
||||
| R11 | `MediaList` uses `alert()` instead of toast / dialog | `06_annotations` | AC-14 |
|
||||
| R12 | `ConfirmDialog` lacks `aria-modal` / `role=dialog` / focus-trap / Esc | `03_shared-ui` | AC-15 |
|
||||
| R13 | Header flight dropdown lacks `role=combobox` / `aria-expanded` / Esc-to-close / focus-trap; outside-click handler always attached | `03_shared-ui` | AC-16 |
|
||||
| R14 | `AdminPage.handleDeleteClass` lacks `ConfirmDialog` despite being destructive | `08_admin` | AC-30 |
|
||||
| R15 | `09_settings` numeric inputs use `parseInt(v) \|\| 0` — empty silently writes 0 | `09_settings` | AC-26 |
|
||||
| R16 | `09_settings` save handlers lack `try/finally` — PUT failure leaves `saving:true` permanently | `09_settings` | AC-27 |
|
||||
| R17 | `i18next.lng` hardcoded `'en'` — no detector / no persistence | `00_foundation` | AC-13 |
|
||||
| R18 | Hardcoded English strings in `AdminPage`, `HelpModal` | `08_admin` + `03_shared-ui` | P6 violation |
|
||||
| R19 | `mapIcons.ts` defaultIcon CDN URL pinned to `leaflet@1.7.1` while package uses 1.9.4 | `05_flights` | finding |
|
||||
| R20 | `magic mediaType=1` literal in `06_annotations` and `07_dataset` | `06_annotations` + `07_dataset` | AC-29 |
|
||||
| R21 | `classNum=0` sentinel collides with real class 0 in dataset filters | `07_dataset` | finding #9 |
|
||||
| R22 | Dataset status filter conflates `None` with `All` | `07_dataset` | finding |
|
||||
| R23 | DatasetPage editor tab does not save | `07_dataset` | finding #4 |
|
||||
| R24 | `AnnotationsPage.handleDownload` tainted-canvas risk | `06_annotations` | finding |
|
||||
| R25 | `AnnotationsPage.handleSave` fallback hides save loss | `06_annotations` | finding |
|
||||
| R26 | `mission-planner/flightPlanUtils.ts` silently swallows weather errors; sequential `await` per segment (perf trap); ambiguous battery-capacity unit (Wh vs Ws); km vs m altitude mixing | `05_flights` (port-source) | findings |
|
||||
|
||||
### Low-priority — surface / polish
|
||||
|
||||
| # | Risk | Component | Source |
|
||||
|---|------|-----------|--------|
|
||||
| R27 | No `ErrorBoundary` at the app root | `10_app-shell` | finding |
|
||||
| R28 | No lazy code-splitting / chunked routes — bundle bloat | `10_app-shell` | finding (`AltitudeChart` lazy-load opportunity) |
|
||||
| R29 | `index.html` body class hardcodes hex literals instead of `az-*` tokens | `10_app-shell` | discovery #11.10 |
|
||||
| R30 | `runUnlockSequence` 4×600 ms theatrical animation in `LoginPage` | `04_login` | finding B4 |
|
||||
| R31 | `FlightContext.selectFlight` is fire-and-forget — no error path | `03_shared-ui` | finding B3 |
|
||||
| R32 | `FlightContext.GET /api/flights?pageSize=1000` hardcoded ceiling | `03_shared-ui` | finding B3 |
|
||||
|
||||
### CI / infra-level (Step 6 surface — track at suite level)
|
||||
|
||||
| # | Risk | Source |
|
||||
|---|------|--------|
|
||||
| R33 | No CSP / hardening headers in `nginx.conf` | `security_approach.md` § 9 |
|
||||
| R34 | No vulnerability scan / SBOM emission / image signing in CI | `architecture.md` § 3 "Missing from the pipeline today" |
|
||||
| R35 | No test step in CI today | `.woodpecker/build-arm.yml` |
|
||||
| R36 | No AMD64 build (ARM64-only image) | `.woodpecker/build-arm.yml` |
|
||||
| R37 | No browser-list config (browser support matrix not enforced) | `architecture.md` § 6 |
|
||||
| R38 | No bundle-size budget gate | `architecture.md` § 6; AC-11 |
|
||||
| R39 | EventSource refresh-rotation breaks open SSE; no reconnect logic | `architecture.md` § Architecture Vision; AC-24 |
|
||||
| R40 | No centralized client telemetry (only browser-console logging) | `deployment/observability.md` |
|
||||
|
||||
---
|
||||
|
||||
## 7. Open questions
|
||||
|
||||
These were flagged during analysis and remain undecided. They do NOT block
|
||||
downstream skills; each is owned by a specific phase per `architecture.md`
|
||||
§ Architecture Vision Open Questions.
|
||||
|
||||
| # | Question | Owner / planned resolution |
|
||||
|---|----------|---------------------------|
|
||||
| Q1 | Test framework choice (Vitest / Jest / Playwright / Bun:test) | Autodev Step 5 — Decompose Tests |
|
||||
| Q2 | `IsSeed` annotation visual (8 px IndianRed border) — does the modern API still expose `isSeed`? | Phase B feature cycle |
|
||||
| Q3 | Camera-config side panel (GSD = altitude × focal × sensor) — per-user, per-flight, or per-detect-job? | Phase B feature cycle |
|
||||
| Q4 | Status-bar clock + help-text-blink — port WPF UX or replace with toasts? | Phase B feature cycle |
|
||||
| Q5 | OpenWeatherMap routing — `.env` (interim) or proxy via `flights/` (preferred long-term)? | Step 4 (interim); Phase B (proxy) |
|
||||
| Q6 | `mission-planner/` end-state — delete after parity port (preferred per Step 4.5) or keep as continuously-vendored reference? | Final Phase B cycle |
|
||||
| Q7 | Sync `/api/detect/${id}` for video — when in Phase B does the async pipeline (F7) ship? | Phase B feature cycle |
|
||||
| Q8 | Module-layout Verification Needed (8 items) — class-colors file move, CanvasEditor cross-feature import, barrel exports, `mission-planner/` ownership timing, foundation multi-dir, app-shell location, test layout, `11_class-colors` location | Step 4 / Phase B (per item) |
|
||||
|
||||
---
|
||||
|
||||
## 8. Artifact index
|
||||
|
||||
All paths are workspace-relative. Each artifact's `Status` field declares
|
||||
who confirmed it (derived-from-code / synthesised-from-verified-docs /
|
||||
confirmed-by-user).
|
||||
|
||||
### `_docs/02_document/` — Documentation skill outputs
|
||||
|
||||
| Artifact | Step | Purpose |
|
||||
|----------|------|---------|
|
||||
| `00_discovery.md` | 0 | Tech stack, dep graph, topological order, entry points, leaves |
|
||||
| `modules/*.md` (22 files) | 1 | Per-module documentation — covers all 77 source modules |
|
||||
| `components/00_foundation/description.md` | 2 | Foundation component spec |
|
||||
| `components/01_api-transport/description.md` | 2 | API transport spec |
|
||||
| `components/02_auth/description.md` | 2 | Auth spec |
|
||||
| `components/03_shared-ui/description.md` | 2 | Shared UI spec |
|
||||
| `components/04_login/description.md` | 2 | Login spec |
|
||||
| `components/05_flights/description.md` | 2 | Flights spec (incl. mission-planner port-source) |
|
||||
| `components/06_annotations/description.md` | 2 | Annotations spec (incl. WPF gap analysis §6b) |
|
||||
| `components/07_dataset/description.md` | 2 | Dataset spec (incl. WPF gap analysis §6b) |
|
||||
| `components/08_admin/description.md` | 2 | Admin spec |
|
||||
| `components/09_settings/description.md` | 2 | Settings spec |
|
||||
| `components/10_app-shell/description.md` | 2 | App-shell spec |
|
||||
| `components/11_class-colors/description.md` | 2 | Class-colors spec (lifted at Step 2) |
|
||||
| `diagrams/components.md` | 2 | Mermaid component dependency graph |
|
||||
| `module-layout.md` | 2.5 | File-ownership map (consumed by `/implement`, `/code-review`, `/refactor`) |
|
||||
| `architecture.md` | 3a + 4.5 | System architecture + § Architecture Vision (12 principles, mission-planner convergence plan) |
|
||||
| `system-flows.md` | 3b | F1–F14 sequence diagrams + error scenarios |
|
||||
| `data_model.md` | 3c | Entity-relationship + numeric-enum drift map |
|
||||
| `deployment/containerization.md` | 3d | Multi-stage Dockerfile, ARM64, nginx static serve |
|
||||
| `deployment/ci_cd_pipeline.md` | 3d | Woodpecker pipeline structure |
|
||||
| `deployment/environment_strategy.md` | 3d | Dev / Stage / Production |
|
||||
| `deployment/observability.md` | 3d | Current state (no centralized telemetry) |
|
||||
| `04_verification_log.md` | 4 | Coverage summary, corrections by document, pre-existing findings re-checked |
|
||||
| `glossary.md` | 4.5 | Confirmed terminology + synonym/drift pairs |
|
||||
| `01_legacy_coverage_gaps.md` | (Step 2 → Step 4.5 update) | WPF parity rollup; Sound Detections + Drone Maintenance marked "Intentionally not ported" |
|
||||
| `FINAL_report.md` | 7 | **This document** |
|
||||
| `state.json` | (skill-internal) | Document skill resumability state |
|
||||
|
||||
### `_docs/01_solution/` — Solution synthesis
|
||||
|
||||
| Artifact | Step | Purpose |
|
||||
|----------|------|---------|
|
||||
| `solution.md` | 5 | Retrospective solution: per-component table (Solution / Tools / Advantages / Limitations / Requirements / Security / Cost / Fit) for all 11 components; testing strategy; references |
|
||||
|
||||
### `_docs/00_problem/` — Problem extraction
|
||||
|
||||
| Artifact | Step | Purpose |
|
||||
|----------|------|---------|
|
||||
| `problem.md` | 6a | High-level problem statement + users + how-it-works + non-goals |
|
||||
| `restrictions.md` | 6b | Hardware (4) / Software (14) / Environment (10) / Operational (15) restrictions |
|
||||
| `acceptance_criteria.md` | 6c | 34 measurable ACs + 5 anti-criteria; coverage status |
|
||||
| `input_data/data_parameters.md` | 6d | Typed REST entities + SSE payloads + env vars + static assets |
|
||||
| `security_approach.md` | 6e | 13 sections covering auth, authz, tokens, SSE bearer, secrets, CORS, validation, XSS, nginx hardening, audit, supply-chain, fix-map |
|
||||
|
||||
### `_docs/02_document/_autodev_state.md` (parent: `_docs/_autodev_state.md`)
|
||||
|
||||
| Artifact | Purpose |
|
||||
|----------|---------|
|
||||
| `_docs/_autodev_state.md` | Autodev resume pointer — flow / step / sub_step / cycle / retry_count |
|
||||
|
||||
### Reference inputs (existing, not produced by `/document`)
|
||||
|
||||
| Artifact | Purpose |
|
||||
|----------|---------|
|
||||
| `_docs/legacy/wpf-era.md` | Legacy WPF reference — used as the WPF parity baseline |
|
||||
| `_docs/how_to_test.md` | GPS-Denied Test Mode reference |
|
||||
| `_docs/ui_design/*` | UI design wireframes — used in Step 4 cross-check |
|
||||
| `suite/_docs/*` (parent suite) | Service contracts — used for enum drift cross-check |
|
||||
| `suite/annotations-research` (detached @ `22529c2`) | Read-only legacy WPF source — used in Step 2 / Step 4 cross-check |
|
||||
|
||||
---
|
||||
|
||||
## 9. Coverage / completeness
|
||||
|
||||
| Axis | Result |
|
||||
|------|--------|
|
||||
| Source modules | 77 / 77 covered (22 doc files; some consolidated) |
|
||||
| Components | 11 / 11 specs |
|
||||
| System flows | 14 (F1–F14; F7 + F12 are target-only by design) |
|
||||
| Endpoint inventory | Every `api.*()` and `createSSE()` call in `src/` is reflected in `architecture.md` § 5 |
|
||||
| Test coverage | **0 tests in `src/`** — no test framework configured today |
|
||||
| BLOCKING gates passed | Step 2 (components), Step 2.5 (module-layout), Step 4 (verification), Step 4.5 (glossary + vision), Step 6 (problem docs) — all confirmed by user |
|
||||
|
||||
---
|
||||
|
||||
## 10. What comes next (autodev existing-code flow)
|
||||
|
||||
`/document` Step 1 of the autodev flow is now **complete**. The next steps
|
||||
are state-driven from `_docs/_autodev_state.md`:
|
||||
|
||||
- **Step 2 — Architecture Baseline Scan** (`code-review` skill in baseline
|
||||
mode) → produces `_docs/02_document/architecture_compliance_baseline.md`
|
||||
marking pre-existing architecture violations (cycles, cross-component
|
||||
private imports, mission-planner convergence as a Critical Architecture
|
||||
finding).
|
||||
- **Step 3 — Test Spec** (`test-spec` skill) → produces
|
||||
`_docs/02_document/tests/traceability-matrix.md` and per-AC scenario files.
|
||||
- **Step 4 — Code Testability Revision** (`refactor` skill in guided mode)
|
||||
→ addresses the High-priority risks above as a minimal, surgical
|
||||
testability prep.
|
||||
- **Step 5 — Decompose Tests** (`decompose` skill in tests-only mode) →
|
||||
selects test framework (Q1) and creates per-AC test tasks.
|
||||
- **Steps 6–8** → Implement Tests / Run Tests / optional Refactor.
|
||||
- **Phase B (Steps 9–17, looping)** → Mission-planner convergence happens
|
||||
one feature group per cycle.
|
||||
|
||||
---
|
||||
|
||||
## 11. Ownership map (downstream-skill consumers)
|
||||
|
||||
| Downstream skill | Artifacts it reads first |
|
||||
|------------------|--------------------------|
|
||||
| `/code-review` (baseline mode) | `architecture.md` § Architecture Vision, `module-layout.md`, `00_discovery.md` § 8 (cross-layer imports) |
|
||||
| `/test-spec` | `acceptance_criteria.md`, `system-flows.md`, `architecture.md` § 6 NFRs |
|
||||
| `/refactor` (guided mode for Step 4) | `04_verification_log.md` (high-priority risks), `acceptance_criteria.md`, `module-layout.md` |
|
||||
| `/decompose` (tests-only mode) | `tests/traceability-matrix.md` (produced by `/test-spec`), `module-layout.md`, `restrictions.md` |
|
||||
| `/implement` | per-task spec files in `_docs/02_tasks/todo/`, `module-layout.md` (file ownership) |
|
||||
| `/new-task` (Phase B) | `architecture.md` § Architecture Vision, `glossary.md`, `01_legacy_coverage_gaps.md` |
|
||||
|
||||
---
|
||||
|
||||
**End of report.**
|
||||
@@ -0,0 +1,443 @@
|
||||
# Azaion UI — Architecture
|
||||
|
||||
> Synthesis output of `/document` Step 3a. Derived from Step 0 (`00_discovery.md`),
|
||||
> Step 1 (`modules/*.md`), Step 2 (`components/*/description.md`), Step 2.5
|
||||
> (`module-layout.md`), and the legacy reference `_docs/legacy/wpf-era.md`. No
|
||||
> new code is read in this step; if anything is missing, the gap belongs upstream.
|
||||
|
||||
## Architecture Vision
|
||||
|
||||
> Status: **confirmed-by-user** (Step 4.5 — 2026-05-10). Source of truth for the
|
||||
> system's structural intent and non-negotiables. Reconciles the verified
|
||||
> code-grounded view (Steps 1–4) with operator/product intent the code alone
|
||||
> cannot convey. Glossary at `_docs/02_document/glossary.md`.
|
||||
|
||||
### What this system is
|
||||
|
||||
The Azaion UI is a React 19 single-page application, statically built and served by nginx inside an ARM64 container, that operates the browser-facing half of the Azaion UAV operations suite. It is the **in-progress rewrite of the legacy WPF stack** (`Azaion.Annotator` + `Azaion.Dataset` + a `MapMatcher` mission planner) and communicates with the parent suite's microservices over **REST + SSE only** — no SSR, no GraphQL, no in-browser persistence beyond a single bearer token in memory and a `Secure HttpOnly` refresh cookie.
|
||||
|
||||
The dominant pattern is "**thin client over a typed REST contract**": React Context for two cross-cutting concerns (auth, selected flight), no global state library, feature pages that fetch + cache locally. A second React 18 + MUI 5 tree (`mission-planner/`) lives in the repo as the **port source** for the flights component — it is **NOT deployed**; its features migrate into `src/features/flights/` across Phase B feature cycles per the convergence plan below.
|
||||
|
||||
### Components / responsibilities
|
||||
|
||||
| ID | Component | One-line responsibility |
|
||||
|----|-----------|--------------------------|
|
||||
| 00 | `00_foundation` | Types, hooks (`useDebounce`, `useResizablePanel`), i18n (en + ua) — the data-vocabulary of the SPA |
|
||||
| 01 | `01_api-transport` | Native `fetch` wrapper (`api/client.ts`) + `EventSource` wrapper (`api/sse.ts`); 401-retry refresh lives here |
|
||||
| 02 | `02_auth` | `AuthContext`, login / logout, bootstrap refresh (broken — finding B3) + 401-retry refresh (works) |
|
||||
| 03 | `03_shared-ui` | Header (top nav + flight dropdown), `FlightContext`, `ConfirmDialog`, `HelpModal`, `DetectionClasses` strip |
|
||||
| 04 | `04_login` | Public `/login` route |
|
||||
| 05 | `05_flights` | Flight CRUD + waypoints + GPS-Denied + planned Test Mode; `mission-planner/` is the port source |
|
||||
| 06 | `06_annotations` | Bounding-box editor, AI Detect (sync today; async not wired), `MediaList` browser scoped to the selected flight |
|
||||
| 07 | `07_dataset` | Dataset Explorer with three tabs (annotations / editor / class distribution); bulk-validate works |
|
||||
| 08 | `08_admin` | Class CRUD (add + delete + **edit, to be re-introduced**), user management, AI/GPS settings forms (broken save) |
|
||||
| 09 | `09_settings` | System / Directory / Camera / User settings |
|
||||
| 10 | `10_app-shell` | `App.tsx` + `main.tsx` + routing tree |
|
||||
| 11 | `11_class-colors` | Class → color + text mapping (lifted out of `06_annotations` in Step 2 — its own component) |
|
||||
|
||||
### Major data flows
|
||||
|
||||
- **F1 Login** → bearer in memory + refresh cookie set.
|
||||
- **F2 Refresh** has TWO paths in code: broken bootstrap GET in `AuthContext.tsx:24` vs. working 401-retry POST in `api/client.ts:44` — Step 4 fix candidate.
|
||||
- **F3 Flight selection** persists as a `UserSettings` field on `annotations/` (NOT `/api/flights/select`).
|
||||
- **F5 Annotation save** POSTs the doubly-prefixed `/api/annotations/annotations`.
|
||||
- **F6 AI Detect (sync)** hits `/api/detect/${id}` for **both** images and videos today (silent UX hazard for long videos — bridge until F7 ships).
|
||||
- **F7 Async video detect** is target-only; not wired today. Comes via Phase B cycles.
|
||||
- **F9 Bulk-validate** works via the Validate button (only `[V]` shortcut missing).
|
||||
- **F12 GPS-Denied Test Mode** is target-only; planned per `_docs/how_to_test.md`.
|
||||
- **F13 Live-GPS SSE** stream per selected flight.
|
||||
- **F14 Annotation-status SSE** (admin-wide, client-side filtered).
|
||||
|
||||
Full sequence diagrams + error scenarios: `_docs/02_document/system-flows.md`.
|
||||
|
||||
### Architectural principles / non-negotiables
|
||||
|
||||
These are **inferred from code or user-confirmed at Step 4.5**. Downstream skills (refactor, decompose, new-task) treat them as binding constraints.
|
||||
|
||||
| # | Principle | Status | Inferred-from / source |
|
||||
|---|-----------|--------|------------------------|
|
||||
| P1 | **REST + SSE only** — no WebSocket, no GraphQL | inferred-from-code | `src/api/client.ts`, `src/api/sse.ts` |
|
||||
| P2 | **Static bundle + nginx reverse-proxy** — zero UI runtime, no SSR, no React Server Components | inferred-from-code | `Dockerfile`, `nginx.conf` |
|
||||
| P3 | **Bearer in memory; refresh in HttpOnly cookie** — tokens are never written to localStorage / sessionStorage | inferred-from-code | `src/auth/AuthContext.tsx` (no `storage.*` calls) |
|
||||
| P4 | **Two-context state** — `AuthContext` + `FlightContext` are the only cross-cutting state stores; everything else is local | inferred-from-code | `src/auth/AuthContext.tsx`, `src/components/FlightContext.tsx` |
|
||||
| P5 | **ARM-first edge deployment** — Woodpecker builds ARM64 only | inferred-from-code | `.woodpecker/build-arm.yml` |
|
||||
| P6 | **Bilingual UI (en + ua)** is mandatory — English-only UX is a regression | inferred-from-code + WPF era | `src/i18n/i18n.ts`, `_docs/legacy/wpf-era.md` |
|
||||
| P7 | **Lift cross-cutting concerns to their own component as soon as 2+ features touch them** — class colors did this at Step 2 | inferred-from-code | `components/11_class-colors/description.md` emergence |
|
||||
| P8 | **WPF parity is a goal, not a constraint** — features that don't make sense in a browser (DI host, LibVLC, ZeroMQ, binary-split key fragments, Cython sidecars) are intentionally NOT ported | inferred-from-WPF-source | `_docs/legacy/wpf-era.md` §11 |
|
||||
| P9 | **Spec is the source of truth for numeric enums** (`AnnotationStatus`, `MediaStatus`, `Affiliation`, `CombatReadiness`) — UI types file matches the spec verbatim and adds inline comments per numeric value | confirmed-by-user (Step 4.5) | `src/types/index.ts`; `04_verification_log.md` enum drift |
|
||||
| P10 | **No hardcoded credentials in source** — third-party keys (e.g., OpenWeatherMap) live in `.env` and are read via `import.meta.env.*` | confirmed-by-user (Step 4.5) | `mission-planner/src/utils/flightPlanUtils.ts:60` (current violation, Step 4 fix) |
|
||||
| P11 | **Persist what you type** — fields declared in `UserSettings` (incl. resizable-panel widths) are actually persisted; the typed shape is the contract | confirmed-by-user (Step 4.5) | `src/hooks/useResizablePanel.ts` (current violation, Step 4 fix); `src/types/index.ts` `UserSettings` |
|
||||
| P12 | **Admin can edit existing detection classes** — add + edit + delete is the full CRUD surface; current code has add + delete only | confirmed-by-user (Step 4.5) | `04_verification_log.md` F10; new `PATCH /api/admin/classes/{id}` to introduce |
|
||||
|
||||
### Mission-planner convergence plan
|
||||
|
||||
`mission-planner/` (37 modules, React 18 + MUI 5) is the port source for `src/features/flights/` (15 modules, React 19 + Tailwind 4). They are **one component, two trees** — convergence is the active migration. Per Step 4.5 decision the timing across the autodev `existing-code` flow is:
|
||||
|
||||
| Autodev step | Role in convergence |
|
||||
|--------------|---------------------|
|
||||
| Step 1 (Document) — done | Both trees documented as one component (`05_flights`) |
|
||||
| Step 2 (Architecture Baseline Scan) | **Flag the convergence as a Critical Architecture finding**; produces the work-list of port targets |
|
||||
| Step 3 (Test Spec) | Write ACs for the **converged target** — incl. mission-planner-only behaviors (camera-config side panel, mission JSON I/O, satellite tile provider, richer waypoint-altitude UX) |
|
||||
| Steps 5–7 (Decompose Tests / Implement Tests / Run Tests) | Build the test safety net for the **current** `src/features/flights/` |
|
||||
| Step 8 (Refactor — optional) | Reserved for **mechanical / no-behavior** consolidation only (shared leaflet helpers, type aliases). Skip if convergence is all behavior-bearing. |
|
||||
| Phase B feature cycles (Steps 9–17 looping) | **Primary home** for convergence. One Phase-B cycle per ported feature group: New Task → Implement → Run Tests → Test-Spec Sync → Update Docs → Security → Deploy → Retrospective. |
|
||||
| Phase B final cycle | Once all port targets land, a final cycle **deletes `mission-planner/`** (its only consumer became zero). |
|
||||
|
||||
Rationale: 37 modules with new behaviors is too big for a single Step 8 refactor. Phase B cycles give a per-feature test safety net, per-feature doc updates, and per-feature shippable deploys. *source: `flows/existing-code.md` Steps 2 / 3 / 8 / 9–17*.
|
||||
|
||||
### Open questions / drift signals (deferred — for downstream skills)
|
||||
|
||||
These are surfaces the verified code can't answer alone; they will be picked up by Step 2 (Architecture Baseline) or by individual Phase B cycles. They are **not** blocking Step 4.5 — they are recorded here so downstream skills don't re-discover them.
|
||||
|
||||
1. **Sync `/api/detect/${id}` used for video** is the deliberate bridge until F7 (async video detect) ships. Plan: keep the bridge, time-bound it to "before the first Phase B cycle that ports the async-detect flow".
|
||||
2. **OpenWeatherMap key** is currently hardcoded in `mission-planner/src/utils/flightPlanUtils.ts:60`. Step 4 (Code Testability Revision) extracts it to `import.meta.env.VITE_OPENWEATHERMAP_API_KEY` per principle P10.
|
||||
3. **Resizable-panel widths** typed in `UserSettings` but not persisted by `useResizablePanel` — Step 4 fix per principle P11.
|
||||
4. **Admin can no longer edit detection classes** — Step 4 fix candidate (or Phase B task) re-introduces `PATCH /api/admin/classes/{id}` plus the in-place edit form per principle P12.
|
||||
5. **AnnotationStatus / MediaStatus / Affiliation / CombatReadiness numeric drift** between `src/types/index.ts` and the suite spec — Step 4 fix per principle P9: align values to the spec, add inline comments per numeric value.
|
||||
6. **`IsSeed` annotation visual** (legacy 8 px IndianRed border) — does the modern API still expose `isSeed`? Defer to a future Phase B cycle.
|
||||
7. **Test framework selection** — deferred to Step 5 (Decompose Tests) per Step 4.5 decision; the autodev flow chooses the runner there.
|
||||
8. **Sound Detections + Drone Maintenance** (legacy WPF) — **dropped** per Step 4.5 decision; recorded in `_docs/02_document/01_legacy_coverage_gaps.md` and not ported.
|
||||
|
||||
---
|
||||
|
||||
## 1. System Context
|
||||
|
||||
**Problem being solved**: Azaion is a UAV / aerial-imagery operations suite for military and
|
||||
defense use cases. The piece of the system documented here is the **operator-facing browser
|
||||
UI** — a single-page React 19 application that lets an operator plan flights, browse and
|
||||
annotate captured media, run AI object detection (synchronous on images, asynchronous via
|
||||
SSE on video), curate datasets, manage detection classes / users / aircraft, and operate a
|
||||
GPS-Denied positioning workflow including a Test Mode that drives SITL simulation from
|
||||
a pre-recorded `.tlog` + video pair.
|
||||
|
||||
This UI is the **React rewrite of the front-end half** of the legacy WPF stack
|
||||
(`_docs/legacy/wpf-era.md`). The Cython sidecars, the SQLite outbox, the LibVLC
|
||||
playback, the per-app DI host, and the binary-split key-fragment loader handoff
|
||||
all moved server-side into the parent suite (`suite/`) as separate .NET / Python /
|
||||
Cython submodules. The UI's job is now narrowed to "render the suite's REST + SSE
|
||||
contract beautifully and accessibly".
|
||||
|
||||
**System boundaries**:
|
||||
|
||||
| Inside this workspace | Outside this workspace |
|
||||
|----------------------|------------------------|
|
||||
| React 19 SPA (`src/`) | Suite backend services (`annotations/`, `flights/`, `admin/`, `detect/`, `loader/`, `gps-denied-{desktop,onboard}/`, `autopilot/`, `resource/`) |
|
||||
| `mission-planner/` port-source (NOT deployed) | Database (PostgreSQL — managed by individual suite services, not the UI) |
|
||||
| Static-bundle Dockerfile + nginx config | OpenWeatherMap public API (consumed directly by the SPA — security finding) |
|
||||
| Woodpecker CI pipeline (`.woodpecker/build-arm.yml`) | Map tile providers (OpenStreetMap, satellite tile URL via env) |
|
||||
| | Identity provider (suite-internal — Admin API) |
|
||||
|
||||
**External systems**:
|
||||
|
||||
| System | Integration Type | Direction | Purpose |
|
||||
|--------|------------------|-----------|---------|
|
||||
| `annotations/` service | REST + SSE (via `/api/annotations/*` and `/api/detect/*`) | Outbound | CRUD annotations, AI detection results, detection classes |
|
||||
| `flights/` service | REST (via `/api/flights/*`) | Outbound | CRUD flights + waypoints; selected-flight persistence |
|
||||
| `admin/` service | REST (via `/api/admin/*`) | Outbound | Users, roles, aircraft, AI / GPS settings, auth (login + refresh) |
|
||||
| `detect/` service | REST + SSE (via `/api/detect/*`) | Outbound | Sync image inference; async video inference w/ SSE progress |
|
||||
| `loader/` service | REST (via `/api/loader/*`) | Outbound | (Currently nominal — UI does not call directly today) |
|
||||
| `gps-denied-desktop/`, `gps-denied-onboard/` | REST (via `/api/gps-denied-*/*`) | Outbound | GPS-Denied operations + Test Mode (SITL feed) |
|
||||
| `autopilot/` | REST (via `/api/autopilot/*`) | Outbound | Aircraft autopilot configuration (admin-side) |
|
||||
| `resource/` | REST (via `/api/resource/*`) | Outbound | Static resource fetch (icons, configs not bundled in the SPA) |
|
||||
| OpenStreetMap tile servers | HTTPS (Leaflet TileLayer) | Outbound | Map raster tiles (browser-direct, not via nginx proxy) |
|
||||
| Satellite tile provider | HTTPS (Leaflet TileLayer with env-configured URL) | Outbound | Satellite imagery (only consumed by mission-planner today) |
|
||||
| OpenWeatherMap | HTTPS (`api.openweathermap.org/data/2.5/onecall`) | Outbound | Wind data for flight planning. **Hardcoded API key in `flightPlanUtils.ts:60` — security finding to fix at Step 4.** |
|
||||
|
||||
## 2. Technology Stack
|
||||
|
||||
| Layer | Technology | Version | Rationale |
|
||||
|-------|------------|---------|-----------|
|
||||
| Language | TypeScript | 5.7 (`strict: true`) | Type-checked interfaces against the suite's REST contract |
|
||||
| UI framework | React | 19 | Latest stable; React Server Components NOT used (this is a static-bundle SPA) |
|
||||
| Bundler | Vite | 6 | Fast dev iteration; static-bundle output for nginx |
|
||||
| Pkg manager | Bun | 1.3.11 (declared via `packageManager`) | CI image (`oven/bun:1.3.11-alpine`) matches |
|
||||
| Styling | Tailwind CSS 4 + custom `az-*` design tokens (`src/index.css`) | 4 | Direct port of legacy WPF dark-navy / orange-accent / red-danger palette |
|
||||
| Routing | `react-router-dom` | 7 | `/login` public; everything else under `AuthProvider → ProtectedRoute → FlightProvider → Header + nested Routes` |
|
||||
| i18n | `i18next` + `react-i18next` | latest | English + Ukrainian. **Note**: `lng:'en'` hardcoded today — language detector / persistence is a Step 4 fix (finding) |
|
||||
| Map | `leaflet` 1.9 + `react-leaflet` 5 + `leaflet-draw` + `leaflet-polylinedecorator` | leaflet 1.9.4 | Replaces WPF MapMatcher. **Note**: `mapIcons.ts` pins `leaflet@1.7.1` CDN URL (drift) — Step 4 fix |
|
||||
| Charts | `chart.js` 4 + `react-chartjs-2` | 4 | Altitude charts in flights; class-distribution chart NOT YET built (gap) |
|
||||
| HTTP transport | native `fetch` (custom thin wrapper at `src/api/client.ts`) | — | No axios / TanStack Query — explicitly minimal |
|
||||
| Realtime | native `EventSource` (SSE) at `src/api/sse.ts` | — | Backend exposes SSE for long-running detect; no WebSocket |
|
||||
| State management | React Context only (`AuthContext`, `FlightContext`) | — | Explicitly NO Redux / Zustand / TanStack Query. Caching is in component state. |
|
||||
| File upload | `react-dropzone` | latest | Drag-drop in `MediaList` |
|
||||
| DnD | `@hello-pangea/dnd` | 18 | Waypoint reorder |
|
||||
| Tests | (none configured) | — | **Zero test coverage in `src/`.** Test plan owned by autodev Steps 5–7 |
|
||||
| Build target | static bundle → nginx (multi-stage Dockerfile) | nginx:alpine | All routes proxied via `nginx.conf` |
|
||||
| Runtime | nginx in container, **ARM64** image | — | Edge-device deployment (operator laptops, OrangePi, Jetson per legacy doc §1) |
|
||||
| CI | Woodpecker | — | `.woodpecker/build-arm.yml` builds + pushes `${REGISTRY_HOST}/azaion/ui:${branch}-arm`. **No test step today.** |
|
||||
|
||||
**Key constraints driving the stack**:
|
||||
|
||||
- **Static bundle only**: the UI ships zero server-side runtime. nginx serves `dist/` and reverse-proxies `/api/<service>/` to the matching suite service.
|
||||
- **ARM-first**: production target is ARM-class edge devices; CI builds ARM64 only today (no AMD64 image in the pipeline).
|
||||
- **Air-gapped friendly**: the SPA is bundled fully; only OpenWeatherMap and map tiles require internet. Field deployments will need an offline tile cache (not implemented).
|
||||
- **No test framework**: legacy carry-over; the WPF `Azaion.Test` project tested utilities only; full test infrastructure is being built fresh under autodev.
|
||||
- **Bilingual UI required**: Ukrainian + English are mandatory per the legacy WPF UX. English-only SaaS-style copy is a regression — finding tracked.
|
||||
|
||||
## 3. Deployment Model
|
||||
|
||||
**Environments**: Development (local Vite dev server + suite docker-compose), Stage, Production (per the Woodpecker `dev`/`stage`/`main` branch triggers).
|
||||
|
||||
**Infrastructure**:
|
||||
- **Container orchestration**: containerized — Dockerfile is multi-stage `oven/bun:1.3.11-alpine` build → `nginx:alpine` static serve. Orchestrator (Kubernetes / Docker Compose / Nomad) is the parent suite's concern, not this repo's.
|
||||
- **Scaling strategy**: stateless; horizontal scaling is trivial (each pod is identical).
|
||||
- **Edge target**: ARM64 image; deployed onto operator laptops / OrangePi / Jetson alongside the suite services.
|
||||
|
||||
**Environment-specific configuration**:
|
||||
|
||||
| Config | Development | Production |
|
||||
|--------|-------------|------------|
|
||||
| API base URL | Vite dev proxy (`/api → http://localhost:8080`, configured in `vite.config.ts`) | nginx reverse-proxy per `/api/<service>/` route → service hostname inside the docker network (configured in `nginx.conf`) |
|
||||
| Secrets | `.env.example` **absent** (Step 4 testability fix) | Secrets are server-side; the SPA carries no API keys EXCEPT the hardcoded OpenWeatherMap key (security finding) |
|
||||
| Logging | browser console | browser console (no centralized client telemetry today — Step 6 surface) |
|
||||
| Auth cookie | local Vite dev proxy passes through; cookies are `Secure; HttpOnly; SameSite=Strict` set by Admin API | Same — cookies are set server-side by Admin API on `POST /api/admin/auth/login` |
|
||||
| Refresh-token rotation | Same code path (handled inside Admin API; UI just retries on 401) | Same |
|
||||
| OpenWeatherMap | Direct HTTPS from the browser (CORS-enabled OWM endpoint) | Same — **but should be proxied via suite to remove the hardcoded key from the bundle.** Step 4 / Step 6. |
|
||||
|
||||
**Build pipeline** (`.woodpecker/build-arm.yml`):
|
||||
1. Triggered on push to `dev` / `stage` / `main`.
|
||||
2. `bun install --frozen-lockfile` + `bun run build` (= `tsc -b && vite build`).
|
||||
3. Multi-stage Dockerfile produces `nginx:alpine`-based image with `dist/` baked at `/usr/share/nginx/html`.
|
||||
4. `ENV AZAION_REVISION=$CI_COMMIT_SHA` is stamped into the image.
|
||||
5. Push to `${REGISTRY_HOST}/azaion/ui:${branch}-arm` with OCI labels (`org.opencontainers.image.{revision,created,source}`).
|
||||
|
||||
**Missing from the pipeline today**:
|
||||
- No test step (no test infrastructure exists).
|
||||
- No vulnerability scan / SBOM emission.
|
||||
- No image signing.
|
||||
- AMD64 build (only ARM64 today).
|
||||
|
||||
## 4. Data Model Overview
|
||||
|
||||
> Detailed per-component data models live in component specs and `data_model.md` (Step 3c). Below is the high-level entity map.
|
||||
|
||||
**Core entities** (defined in `src/types/index.ts`, mirroring the suite's REST contract):
|
||||
|
||||
| Entity | Description | Owned By Component | Backing service |
|
||||
|--------|-------------|--------------------|-----------------|
|
||||
| `AuthUser` | Logged-in user with role + permissions | `02_auth` | `admin/` |
|
||||
| `User` | User CRUD entity (admin) | `08_admin` | `admin/` |
|
||||
| `Aircraft` | Plane / Copter with default flag | `08_admin` (or `09_settings`) | `admin/` |
|
||||
| `Flight` | Flight session entity | `05_flights` | `flights/` |
|
||||
| `Waypoint` | Lat/lng/order point on a flight | `05_flights` | `flights/` |
|
||||
| `Media` | One captured image or video file | `06_annotations` | `annotations/` |
|
||||
| `MediaType` enum | None=0 / Image=1 / Video=2 | shared (`00_foundation`) | (matches suite spec) |
|
||||
| `MediaStatus` enum | New=0 / AiProcessing=1 / AiProcessed=2 / ManualCreated=3 — **drift, missing None/Confirmed/Error** | shared (`00_foundation`) | (matches suite spec — mismatch flagged) |
|
||||
| `AnnotationListItem` | Annotation row with detections | `06_annotations` | `annotations/` |
|
||||
| `AnnotationStatus` enum | Created=0 / Edited=1 / Validated=2 — **drift, spec is 0/10/20/30** | shared (`00_foundation`) | (mismatch flagged) |
|
||||
| `AnnotationSource` enum | AI=0 / Manual=1 | shared | (matches suite spec) |
|
||||
| `Detection` | Bounding box (x/y/w/h normalized) + class + affiliation + combatReadiness | `06_annotations` (display) | `annotations/` (storage) + `detect/` (production) |
|
||||
| `Affiliation` enum | Unknown=0 / Friendly=1 / Hostile=2 — **drift, spec also has 'None'** | shared | (mismatch flagged) |
|
||||
| `CombatReadiness` enum | NotReady=0 / Ready=1 — **drift, spec also has 'Unknown'** | shared | (mismatch flagged) |
|
||||
| `DetectionClass` | Admin-managed class with name / color / size / photoMode | `08_admin` (write) | `admin/` (write) + `annotations/` (read) |
|
||||
| `DatasetItem` | Thumbnail + status row | `07_dataset` | `annotations/` (queries) |
|
||||
| `ClassDistributionItem` | classNum / label / color / count | (currently unused in UI — backs missing chart) | `annotations/` |
|
||||
| `SystemSettings` / `DirectorySettings` / `CameraSettings` | Server-side configs | `09_settings` + `08_admin` | `admin/` |
|
||||
| `UserSettings` | Per-user preferences (incl. left/right panel widths — type exists, not wired) | `09_settings` | `admin/` |
|
||||
| `PaginatedResponse<T>` | `{ items, totalCount, page, pageSize }` envelope | shared | (used everywhere) |
|
||||
|
||||
**Key relationships**:
|
||||
- `Flight` 1:N `Waypoint` (waypoints belong to one flight; ordering preserved by `order` field)
|
||||
- `Flight` 1:N `Media` (capture media is associated with the flight that produced it; `Media.waypointId` optionally pinpoints the capturing waypoint)
|
||||
- `Media` 1:N `AnnotationListItem` 1:N `Detection`
|
||||
- `User` N:1 `Aircraft`-default (default aircraft applies to a user's new flights — currently global per a finding in `08_admin`/`09_settings`)
|
||||
- `DetectionClass` is referenced by `Detection.classNum` (not a typed FK — `classNum` is the raw int that includes the PhotoMode offset)
|
||||
|
||||
**Data flow summary**:
|
||||
1. **Plan flight** → `flights/` REST → flight + waypoints persist; the UI optimistically updates and listens for nothing today (no SSE on flight updates).
|
||||
2. **Capture media** → out-of-band: edge devices upload via the loader / annotations services; the UI surfaces them via `MediaList` polling.
|
||||
3. **Annotate** → user-edits → POST/PUT/DELETE to `annotations/` REST; **no streaming** of other users' annotations into this UI today.
|
||||
4. **AI Detect** (sync image) → `POST /api/detect/{mediaId}` returns inline detections.
|
||||
5. **AI Detect** (async video) → `POST /api/detect/video/{mediaId}` returns a job ID → SSE on `/api/detect/stream/{jobId}` streams progress + finalized detections. **The UI does not subscribe today** (finding #10).
|
||||
6. **Curate dataset** → `07_dataset` queries `annotations/` with status filters; bulk-validate transitions `AnnotationStatus.{Created,Edited} → Validated`.
|
||||
7. **GPS-Denied Test Mode** → user uploads `.tlog` + video → `gps-denied-desktop/` service auto-syncs them via IMU analysis → SITL simulation feeds frames to `gps-denied-onboard/` service → results render back through `flights/` GPS-Denied tab.
|
||||
|
||||
## 5. Integration Points
|
||||
|
||||
### Internal Communication (UI → suite)
|
||||
|
||||
> **Step 4 verification** corrected this table after grepping every `api.*()` and `createSSE()` call in `src/`.
|
||||
|
||||
| From (component) | To (suite service) | Protocol | Pattern | Endpoints actually called | Notes |
|
||||
|-----------------|-------------------|----------|---------|---------------------------|-------|
|
||||
| `02_auth/AuthContext` | `admin/` | REST | Request-Response | `POST /api/admin/auth/login`, `POST /api/admin/auth/logout`, `GET /api/admin/auth/refresh` (bootstrap, no `credentials:'include'`), `POST /api/admin/auth/refresh` (401-retry inside `api/client.ts:44`, has `credentials:'include'`) | **Two refresh paths exist** — bootstrap GET vs. 401-retry POST. Only the POST path correctly sends the cookie. The GET bootstrap will fail → Step 4 fix. |
|
||||
| `01_api-transport/sse.ts` | every service | SSE (HTTP) | Server-pushed events | Helper is named `createSSE` (NOT `subscribeSSE`). Bearer in **query string** (`?token=...`) — accepted trade-off. EventSource holds the token captured at create time; refresh-rotation breaks long subscriptions (Step 8 hardening). |
|
||||
| `03_shared-ui/FlightContext` | `flights/` + `annotations/` | REST | Request-Response | `GET /api/flights?pageSize=1000` (hardcoded ceiling, finding B3). `GET /api/annotations/settings/user` to load `selectedFlightId`. `GET /api/flights/${id}` to hydrate selected flight. **`PUT /api/annotations/settings/user`** to save selection (NOT `/api/flights/select` as initially drafted). Fire-and-forget — finding B3. |
|
||||
| `03_shared-ui/DetectionClasses` | `annotations/` | REST | Request-Response | `GET /api/annotations/classes` |
|
||||
| `06_annotations/MediaList` | `annotations/` | REST | Request-Response + upload | `GET /api/annotations/media?...`, `GET /api/annotations/annotations?mediaId=...&pageSize=1000`, `DELETE /api/annotations/media/${id}`, **`api.upload('/api/annotations/media/batch', formData)`** (multipart). |
|
||||
| `06_annotations/AnnotationsPage` | `annotations/` | REST + SSE | Request-Response + Event | `GET /api/annotations/media/${id}/file`, `POST /api/annotations/annotations` (NOT `/api/annotations` — the path is **doubly-prefixed**). Annotation save body shape: finding #32 (Step 4 fix). |
|
||||
| `06_annotations/AnnotationsSidebar` | `annotations/`, `detect/` | REST + SSE | Request-Response + Event | `POST /api/detect/${mediaId}` (sync detect — used for BOTH images and videos today); `createSSE('/api/annotations/annotations/events', ...)` for **annotation-status SSE** (NOT detect progress). **No `/api/detect/video/${id}` and no `/api/detect/stream/${jobId}` are wired today** — finding #10 / #21 confirmed. |
|
||||
| `06_annotations/CanvasEditor` | `annotations/` | static asset GET | — | `GET /api/annotations/annotations/${id}/image` (annotation thumbnail), `GET /api/annotations/media/${id}/file` (raw media). |
|
||||
| `07_dataset/DatasetPage` | `annotations/` | REST | Request-Response | `GET /api/annotations/dataset?...`, `GET /api/annotations/dataset/${annotationId}`, `POST /api/annotations/dataset/bulk-status`, **`GET /api/annotations/dataset/class-distribution`** (the endpoint **already exists**; the chart UI is what's missing — see `01_legacy_coverage_gaps.md`), `<img src="/api/annotations/annotations/${id}/thumbnail">`. **Editor tab does not save** — finding #4. |
|
||||
| `08_admin/AdminPage` | `annotations/` + `admin/` + `flights/` | REST | Request-Response | `GET /api/annotations/classes` (read), `POST /api/admin/classes` (create), `DELETE /api/admin/classes/${id}` (delete — no ConfirmDialog, finding B4), `POST /api/admin/users`, `PATCH /api/admin/users/${id}` (deactivate), `GET /api/flights/aircrafts`, `PATCH /api/flights/aircrafts/${id}`. **Cross-service reads** — admin page reads aircraft from `flights/` and classes from `annotations/`. |
|
||||
| `09_settings/SettingsPage` | `annotations/` + `flights/` | REST | Request-Response | `GET/PUT /api/annotations/settings/system`, `GET/PUT /api/annotations/settings/directories`, `GET /api/flights/aircrafts`, `PATCH /api/flights/aircrafts/${id}`. **Settings endpoints route to `annotations/`**, NOT `admin/` as initially drafted. |
|
||||
| `05_flights/FlightsPage` | `flights/` | REST + SSE | Request-Response + Event | `GET /api/flights/aircrafts`, `GET /api/flights/${id}/waypoints`, **`createSSE('/api/flights/${id}/live-gps', ...)` — live-GPS SSE for aircraft telemetry**, `POST /api/flights`, `DELETE /api/flights/${id}`, `DELETE /api/flights/${id}/waypoints/${wpId}` (loop), `POST /api/flights/${id}/waypoints` (loop, lossy shape — finding #20). |
|
||||
| `05_flights/flightPlanUtils` | OpenWeatherMap (external) | REST | Request-Response | `GET https://api.openweathermap.org/data/2.5/onecall?...` with **hardcoded API key** — security finding. |
|
||||
|
||||
### External Integrations
|
||||
|
||||
| External System | Protocol | Auth | Rate Limits | Failure Mode |
|
||||
|----------------|----------|------|-------------|--------------|
|
||||
| OpenStreetMap tiles | HTTPS (Leaflet TileLayer) | None | OSM Tile Usage Policy | Map renders blank / stale; no fallback today |
|
||||
| OpenWeatherMap | HTTPS | **Hardcoded API key in source** | Free-tier 60 calls/min | Errors silently swallowed in `flightPlanUtils.ts` (finding) — wind data missing → battery/duration estimates wrong, no UI surface |
|
||||
| Suite identity provider (admin/) | REST + HttpOnly refresh cookie | JWT bearer + refresh-token rotation | server-enforced | 401 → `ProtectedRoute` redirects to `/login`; refresh-token rotation handled inside `AuthContext` (mostly) |
|
||||
|
||||
## 6. Non-Functional Requirements
|
||||
|
||||
> Targets that are explicitly enforceable in code or config. Anything else is aspirational and noted as such.
|
||||
|
||||
| Requirement | Target | Measurement | Priority | Source |
|
||||
|------------|--------|-------------|----------|--------|
|
||||
| Bundle size (initial JS) | ≤ ~2 MB gzipped | `vite build` artifact inspection | High | Bundle bloat is a finding (`AltitudeChart` lazy-load opportunity in flights) |
|
||||
| Initial paint | < 2 s on operator laptops over LAN | Manual inspection | Medium | No metric collection today |
|
||||
| Long-running detect (video) | UI stays responsive; progress visible to user | Should be SSE-streamed | High | Currently NOT met — finding #21 (no progress UI), #10 (no SSE subscription) |
|
||||
| Auth refresh | Transparent — no user-visible flicker | One refresh = one network round trip; no UI re-render past `<ProtectedRoute>`| High | `refresh` missing `credentials:'include'` is a real bug — Step 4 fix |
|
||||
| Upload size | ≤ 500 MB single file | `nginx.conf` `client_max_body_size 500M` | Medium | Hard cap from server config |
|
||||
| Browser support | Chromium-based + Firefox latest 2 versions | Manual | Medium | No browser-list config; ES module output assumes evergreen |
|
||||
| Mobile responsiveness | Header has bottom-nav variant; main pages render at 768 px+ | `Header.tsx:113-129` | Low | Mobile is a P2 use-case |
|
||||
| Accessibility | Confirm dialogs / dropdowns must be keyboard-navigable | `ConfirmDialog` lacks `aria-modal/role=dialog`; Header dropdown lacks `role=combobox`/Esc | Medium | Multiple findings flagged for Step 4 / Step 8 |
|
||||
| i18n coverage | English + Ukrainian for all user-visible strings | Manual | High | Many strings hardcoded English today (admin, annotations help) — Step 4 |
|
||||
| Test coverage | Aspirational target TBD by autodev Step 3 | (none yet) | High | Zero coverage today |
|
||||
|
||||
## 7. Security Architecture
|
||||
|
||||
**Authentication**:
|
||||
- Operator logs in via `POST /api/admin/auth/login` → Admin service issues a JWT bearer (response body) + a `Secure; HttpOnly; SameSite=Strict` refresh-token cookie.
|
||||
- The bearer is held in `AuthContext` memory (not localStorage — XSS-resistant).
|
||||
- On 401, `AuthContext` calls `GET /api/admin/auth/refresh` (cookie-only credential) → new bearer + new refresh cookie. **Bug: this request is missing `credentials:'include'`** — likely fails on cross-origin path. Step 4 fix.
|
||||
- WPF-era encrypted-creds command-line handoff is **intentionally not ported** (`_docs/legacy/wpf-era.md §11`).
|
||||
|
||||
**Authorization**:
|
||||
- Admin service enforces RBAC server-side via `User.role` + `permissions[]`.
|
||||
- UI inspects `AuthUser.role` to render or hide nav links and pages, but does NOT enforce. Two findings (`/admin` route lacks role-gate — security PRIORITY; `/settings` route is more nuanced).
|
||||
- The browser is treated as untrusted; every action confirms with the server.
|
||||
|
||||
**Data protection**:
|
||||
- **At rest**: not in scope for the UI.
|
||||
- **In transit**: TLS terminated server-side at the suite ingress (nginx ingress → service mesh / docker network).
|
||||
- **Secrets management**: secrets are NEVER in the SPA bundle, EXCEPT the **hardcoded OpenWeatherMap API key** in `src/features/flights/flightPlanUtils.ts:60`. **Must rotate at OpenWeatherMap, remove from source, and proxy via suite/`flights` service.** Step 4 / Step 6.
|
||||
- **Bearer in SSE query string**: documented trade-off; the bearer is short-lived and the URL is HTTPS-encrypted on the wire. Risk: server-side access logs may capture the URL with the token. Cross-link to `security_approach.md` (Step 6).
|
||||
- **CORS**: handled server-side; `credentials:'include'` is required on every authenticated fetch. The bug above is the primary CORS-related defect.
|
||||
|
||||
**Input validation**:
|
||||
- Numeric inputs in `09_settings` use `parseInt(v) || 0` — clearing a field silently writes 0 (finding B4). Step 4 fix.
|
||||
- File uploads in `06_annotations` go through `react-dropzone` MIME filter; no client-side virus scan; server is authoritative.
|
||||
|
||||
**Audit logging**: server-side concern; the SPA does not emit audit events directly.
|
||||
|
||||
**Cross-site / clickjack**: no `Content-Security-Policy` headers configured in `nginx.conf` today — Step 6 surface.
|
||||
|
||||
## 8. Key Architectural Decisions
|
||||
|
||||
> ADRs inferred from the code + legacy doc. The decisions are recorded retrospectively
|
||||
> here — the original decision-making lives in commit history and the WPF-era doc.
|
||||
|
||||
### ADR-001: Pure SPA over server-rendered React
|
||||
|
||||
**Context**: The legacy WPF stack ran on the operator's machine. The new UI must deploy alongside the suite services as a peer container.
|
||||
|
||||
**Decision**: Static-bundle SPA served by nginx; no Node.js runtime in the production image; no SSR.
|
||||
|
||||
**Alternatives considered**:
|
||||
1. Next.js (SSR + RSC) — rejected because edge devices can't host a Node runtime cheaply, and the suite already has nginx for `/api` reverse-proxy.
|
||||
2. Plain HTML + jQuery — rejected because the WPF-era complexity (canvas editor, video sync, leaflet, charts) doesn't degrade well to non-React.
|
||||
|
||||
**Consequences**: Initial paint waits for the bundle. SEO and deep-linking are not concerns (the UI is operator-only). Bundle bloat is the main risk → flagged for Step 4.
|
||||
|
||||
### ADR-002: REST + SSE only; no WebSockets
|
||||
|
||||
**Context**: The suite already exposes REST + SSE on every service. WebSockets would require a duplex protocol the backend doesn't speak.
|
||||
|
||||
**Decision**: `src/api/client.ts` (fetch wrapper) + `src/api/sse.ts` (EventSource wrapper) cover all transport.
|
||||
|
||||
**Alternatives considered**: WebSockets, GraphQL Subscriptions, gRPC-Web — all rejected as needing backend changes that aren't on the roadmap.
|
||||
|
||||
**Consequences**: Long-running operations (video AI detect) require an SSE consumer; one is missing today (finding #10). Bidirectional updates (e.g., live "another user is editing") are not possible — accepted.
|
||||
|
||||
### ADR-003: HTML5 `<video>` instead of LibVLC
|
||||
|
||||
**Context**: Legacy used `LibVLCSharp` for frame-accurate playback. The browser cannot host LibVLC.
|
||||
|
||||
**Decision**: HTML5 `<video>` with a frame-accurate seeking shim.
|
||||
|
||||
**Alternatives considered**: WebAssembly LibVLC — rejected as too heavy in the bundle for marginal accuracy gains; HLS/DASH chunked playback — rejected as overkill for short capture videos.
|
||||
|
||||
**Consequences**: Per-frame stepping requires manual `currentTime ± (1/fps)` math; FPS is detected at metadata-load time. **Today fps is hardcoded `30`** in `VideoPlayer.tsx` — finding to fix in Step 4.
|
||||
|
||||
### ADR-004: React Context only; no Redux / TanStack Query
|
||||
|
||||
**Context**: Two pieces of cross-component state — current user (AuthContext) and selected flight (FlightContext) — and the rest is page-local.
|
||||
|
||||
**Decision**: Two Context providers; everything else is `useState`.
|
||||
|
||||
**Alternatives considered**: Redux — rejected as overkill for two stores; Zustand — rejected as adding a dependency; TanStack Query — rejected as we don't currently need cache invalidation across components.
|
||||
|
||||
**Consequences**: Pages re-fetch on mount; no shared cache. Add TanStack Query in a future iteration if cross-page caching becomes a real need (Step 5 solution surface).
|
||||
|
||||
### ADR-005: Tailwind 4 + custom `az-*` design tokens
|
||||
|
||||
**Context**: Legacy WPF had a fixed dark-navy/orange/red palette (`_docs/legacy/wpf-era.md §10`).
|
||||
|
||||
**Decision**: Tailwind 4 with `az-bg`, `az-text`, `az-orange`, `az-success`, `az-danger`, `az-primary` CSS variables defined in `src/index.css`.
|
||||
|
||||
**Consequences**: Design tokens are the single source of truth — but `index.html` body class hardcodes hex literals (`bg-[#1e1e1e] text-[#adb5bd]`) instead of using tokens (cosmetic finding, 00_discovery #11.10).
|
||||
|
||||
### ADR-006: nginx reverse-proxy strips `/api/<service>/` prefix per service
|
||||
|
||||
**Context**: The suite has 9 distinct backend services; the SPA must reach all of them via the same origin (cookie scope + CORS-free).
|
||||
|
||||
**Decision**: `nginx.conf` enumerates 9 routes and strips the prefix before proxying.
|
||||
|
||||
**Alternatives considered**: API gateway (e.g., Traefik / Kong) — rejected as adding ops complexity; service mesh — same.
|
||||
|
||||
**Consequences**: A new suite service requires a `nginx.conf` edit. The SPA hardcodes `/api/<service>/...` paths in source instead of an env-driven base URL — testability is poor (finding tracked).
|
||||
|
||||
### ADR-007: Bilingual (English + Ukrainian)
|
||||
|
||||
**Context**: Legacy WPF was Ukrainian-only with a tiny `translations.json` for English. Operators are Ukrainian-speaking; some allies are English-speaking.
|
||||
|
||||
**Decision**: `react-i18next` with `en.json` + `ua.json`. Operator can switch in the Header.
|
||||
|
||||
**Consequences**: Every user-visible string MUST be in both bundles. **Many strings are hardcoded English today** (admin page especially) — high-priority Step 4 fix.
|
||||
|
||||
### ADR-008: Bearer-token-in-query-string for SSE
|
||||
|
||||
**Context**: `EventSource` cannot send arbitrary headers; the suite SSE endpoints require a bearer.
|
||||
|
||||
**Decision**: Pass bearer in `?token=...`. Document the trade-off in `security_approach.md`.
|
||||
|
||||
**Consequences**: Bearer may appear in nginx access logs. Mitigation: short-lived bearers + log-redaction at the nginx layer (Step 6 surface). Also: refresh-rotation breaks live SSE subscriptions; reconnect logic is missing today (Step 8 hardening).
|
||||
|
||||
### ADR-009: `mission-planner/` is a vendored port-source, NOT a deployed component
|
||||
|
||||
**Context**: The mission-planner React 18 + MUI app is the upstream design source for `src/features/flights/`. Documenting it as a separate top-level component would imply parallel deployment; it isn't deployed.
|
||||
|
||||
**Decision**: Per the user's Step 2 BLOCKING-gate decision (2026-05-10), `mission-planner/` is documented INSIDE component `05_flights` as the port-source. The Vite build does NOT compile it. After the port reaches parity, the directory is a deletion candidate.
|
||||
|
||||
**Consequences**: Two physical trees under one logical component. The implement skill must include `mission-planner/**` in `05_flights`'s OWNED glob (called out in `module-layout.md` Verification Needed #4).
|
||||
|
||||
### ADR-010: GPS-Denied Test Mode is a planned sub-feature of `05_flights`
|
||||
|
||||
**Context**: Per `_docs/how_to_test.md`, the Test Mode lets an operator upload a `.tlog` + video pair, auto-sync them via IMU analysis, and feed SITL frames into the onboard GPS-Denied service.
|
||||
|
||||
**Decision**: Test Mode is a tab inside the `05_flights` GPS-Denied sub-feature. NOT a separate component.
|
||||
|
||||
**Consequences**: One component spans flight-planning + flight operations + GPS-Denied + Test Mode. Acceptable today; a future split is feasible if the component grows further.
|
||||
|
||||
---
|
||||
|
||||
## Open architecture questions
|
||||
|
||||
The following remain undecided and surface at Step 4.5 (Glossary & Architecture Vision):
|
||||
|
||||
1. **Sound Detections feature** (audio-analysis bbox button in legacy WPF) — port, drop, or new audio-pipeline service?
|
||||
2. **Drone Maintenance feature** (`Аналіз стану БПЛА`) — port, drop, or maintenance service?
|
||||
3. **Class Distribution chart** (Dataset's 3rd tab) — port or replace with admin-side analytics?
|
||||
4. **Status-bar clock + help-text-blink** — keep WPF UX or replace with toasts?
|
||||
5. **`IsSeed` thumbnail concept** — modern API still exposes it?
|
||||
6. **Camera config persistence scope** — per-user, per-flight, or per-detect-job?
|
||||
7. **Resizable-panel persistence scope** — Settings (server) or LocalStorage (client)?
|
||||
8. **OpenWeatherMap routing** — proxy via `flights/` service (preferred for security) or move wind compute server-side entirely?
|
||||
9. **`mission-planner/` end-state** — delete after parity port (preferred) or keep as a continuously-vendored reference?
|
||||
|
||||
These are the inputs for Step 4.5 user confirmation; this architecture doc proceeds without resolving them.
|
||||
@@ -0,0 +1,165 @@
|
||||
# Architecture Compliance Baseline
|
||||
|
||||
**Scope**: full existing codebase (`src/` deployed tree + `mission-planner/` port-source).
|
||||
**Date**: 2026-05-10
|
||||
**Mode**: code-review baseline (Phase 1 + Phase 7 only).
|
||||
**Verdict**: **FAIL** — 1 Critical, 4 High, 2 Medium, 2 Low. Verdict drives Step 2 → Step 4 / Step 8 routing per `flows/existing-code.md`; it does NOT block any pipeline.
|
||||
|
||||
Inputs read in Phase 1:
|
||||
- `_docs/02_document/architecture.md` (incl. Architecture Vision P1–P12, ADR-001..010, Mission-planner convergence plan).
|
||||
- `_docs/02_document/module-layout.md` (per-component file ownership, Layer table, Verification Needed #1–#8).
|
||||
- `_docs/00_problem/restrictions.md`, `_docs/01_solution/solution.md` (project context).
|
||||
|
||||
Detection approach: TypeScript `import ... from '...'` parsing across all `.ts` / `.tsx` files; layer resolved via `module-layout.md` "Per-Component Mapping"; layer comparison against the "Allowed Dependencies (layering)" table.
|
||||
|
||||
---
|
||||
|
||||
## Findings
|
||||
|
||||
| # | Severity | Category | Location | Title |
|
||||
|----|----------|-------------|--------------------------------------------------------------------------|---------------------------------------------------------------------|
|
||||
| F1 | Critical | Architecture | `mission-planner/**` vs `src/features/flights/**` | Mission-planner duplicates 13+ modules of the deployed flights tree |
|
||||
| F2 | High | Architecture | `src/features/dataset/DatasetPage.tsx:9` → `../annotations/CanvasEditor` | Cross-feature same-layer edge — `07_dataset` reaches into `06_annotations` |
|
||||
| F3 | High | Architecture | `src/features/annotations/classColors.ts` | Physical / logical owner split — `11_class-colors` file lives inside `06_annotations` |
|
||||
| F4 | High | Architecture | every component | No Public API barrels — every internal file is de-facto public |
|
||||
| F5 | High | Architecture | `mission-planner/src/flightPlanning/MapView.tsx ↔ MiniMap.tsx` | Pre-existing import cycle inside port-source |
|
||||
| F6 | Medium | Architecture | (codebase-wide) | No `src/shared/` infrastructure for cross-cutting concerns |
|
||||
| F7 | Medium | Architecture | every `api.*` / `createSSE` call site | Hardcoded `/api/<service>/...` paths instead of env-driven endpoints |
|
||||
| F8 | Low | Architecture | `_docs/02_document/module-layout.md` | Layering-table inconsistency — Header → useAuth is unannotated |
|
||||
| F9 | Low | Architecture | `mission-planner/src/{main,App,setupTests,vite-env}.tsx` | Inert second Vite entry tree at port-source root |
|
||||
|
||||
---
|
||||
|
||||
## Finding Details
|
||||
|
||||
### F1: Mission-planner duplicates 13+ modules of the deployed flights tree (Critical / Architecture)
|
||||
|
||||
- **Location**: `mission-planner/src/**` vs `src/features/flights/**`.
|
||||
- **Description**: Component `05_flights` has two physical trees (per ADR-009). The port-source duplicates almost every module the deployed tree exposes today AND carries behaviors the deployed tree does not yet have (camera-config side panel, mission JSON I/O, satellite tile provider, richer waypoint-altitude UX). Duplication enumerated below; until convergence completes, the same logic lives in two places and silently drifts. This is the **work-list** the Architecture Vision (Mission-planner convergence plan) asked Step 2 to surface.
|
||||
|
||||
**Duplicated by name** (deployed → port-source):
|
||||
|
||||
| Deployed (`src/features/flights/`) | Port-source (`mission-planner/src/.../`) | Notes |
|
||||
|--------------------------------------------|----------------------------------------------------------------------------|-------|
|
||||
| `AltitudeChart.tsx` | `flightPlanning/AltitudeChart.tsx` | Both consumed by their respective panels. |
|
||||
| `AltitudeDialog.tsx` | `flightPlanning/AltitudeDialog.tsx` | Port-source version uses `useLanguage` (custom i18n); deployed uses Tailwind. |
|
||||
| `DrawControl.tsx` | `flightPlanning/DrawControl.tsx` | Deployed uses `newGuid` from `flightPlanUtils`; port-source from `utils.ts`. |
|
||||
| `JsonEditorDialog.tsx` | `flightPlanning/JsonEditorDialog.tsx` | Mission JSON I/O — deployed version is a stub vs. port-source's full editor. |
|
||||
| `MapPoint.tsx` | `flightPlanning/MapPoint.tsx` | Both import the local `pointIcon*` set. |
|
||||
| `MiniMap.tsx` | `flightPlanning/MiniMap.tsx` | Port-source version is half of the F5 cycle. |
|
||||
| `WindEffect.tsx` | `flightPlanning/WindEffect.tsx` | Port-source pulls `useLanguage`; deployed uses `i18next`. |
|
||||
| `WaypointList.tsx` | `flightPlanning/PointsList.tsx` (renamed) | DnD reorder; same intent, different libs. |
|
||||
| `FlightMap.tsx` | `flightPlanning/MapView.tsx` (renamed) | The cycle partner. |
|
||||
| `FlightParamsPanel.tsx` | `flightPlanning/LeftBoard.tsx` (renamed) | Side-panel composition root. |
|
||||
| `FlightsPage.tsx` | `flightPlanning/flightPlan.tsx` (renamed) | Route component. |
|
||||
| `mapIcons.ts` | `icons/PointIcons.tsx`, `icons/MapIcons.tsx`, `icons/SidebarIcons.tsx` | Port-source uses inline SVG components; deployed uses `L.icon`. |
|
||||
| `flightPlanUtils.ts` (`newGuid`, `calculateDistance`, `calculateAllPoints`, `parseCoordinates`, `getMockAircraftParams`) | `utils.ts` (`newGuid`); `services/calculateDistance.ts`; `services/calculateBatteryUsage.ts`; `services/AircraftService.ts` (`mockGetAirplaneParams`) | Same five symbols, scattered across four files in the port-source. |
|
||||
| `types.ts` (`FlightPoint`, `CalculatedPointInfo`, `MapRectangle`, `ActionMode`, `WindParams`, `AircraftParams`, `PURPOSES`, `COORDINATE_PRECISION`, `TILE_URLS`) | `types/index.ts` + `constants/{actionModes,purposes,tileUrls,maptypes,languages,translations}.ts` | Port-source has richer constants tables (mapTypes, languages, translations) the deployed tree lacks. |
|
||||
|
||||
**Port-source-only** (no deployed counterpart yet — these are the behaviors that must port across Phase B):
|
||||
|
||||
- `flightPlanning/LanguageContext.tsx` + `LanguageSwitcher.tsx` — mission-planner's standalone i18n (deployed uses `i18next`). DO NOT port; consolidate on `i18next`.
|
||||
- `flightPlanning/TotalDistance.tsx` — distance + battery readout in the left panel. Behavior the deployed tree does not yet show in the same form.
|
||||
- `icons/PhoneIcon.tsx` (rotate-phone hint), `icons/SidebarIcons.tsx` (DashedArea / HideSidebar / ShowSidebar).
|
||||
- `services/WeatherService.ts` — wind compute (already partially in deployed `flightPlanUtils.ts:60` with the hardcoded key — P10 violation).
|
||||
- `flightPlanning/Aircraft.ts` — aircraft entity helpers.
|
||||
- `config.ts` — `COORDINATE_PRECISION`, `GOOGLE_GEOCODE_KEY` (second hardcoded-key risk — verify).
|
||||
|
||||
- **Suggestion**: This is the convergence work-list. Per Architecture Vision (Mission-planner convergence plan):
|
||||
- **NOT a Step 4 testability item** — these are behavior ports, not testability surgery.
|
||||
- **NOT a Step 8 refactor item alone** — too large for one mechanical refactor; behavior changes break tests.
|
||||
- **Primary home**: Phase B feature cycles (one cycle per port group: i18n consolidation; flight-planning UI parity; waypoint-altitude UX; mission JSON I/O; satellite tile provider; weather/battery service; camera-config side panel). Each cycle: New Task → Implement → Run Tests → Test-Spec Sync → Update Docs → Deploy → Retrospective.
|
||||
- **Final Phase B cycle**: delete `mission-planner/` (its only consumer becomes zero).
|
||||
- **Task / Epic**: feeds `05_flights` Step 3 (Test Spec) — every port target must have an AC for the converged behavior before its Phase B cycle starts.
|
||||
|
||||
### F2: Cross-feature same-layer edge — `07_dataset` reaches into `06_annotations` (High / Architecture)
|
||||
|
||||
- **Location**: `src/features/dataset/DatasetPage.tsx:9` → `import CanvasEditor from '../annotations/CanvasEditor'`.
|
||||
- **Description**: `07_dataset` and `06_annotations` are both Layer 3 features. Same-layer imports are forbidden except for explicit grandfathered edges. This edge IS grandfathered (`module-layout.md` Allowed-Dependencies table footnote †, Verification Needed #2). It is the only Layer-3 ↔ Layer-3 import in the codebase. Until a proper home is chosen, the implement skill must keep treating `CanvasEditor.tsx` as READ-ONLY for `07_dataset` tasks.
|
||||
- **Suggestion**: Lift `CanvasEditor.tsx` to `src/components/canvas/CanvasEditor.tsx` (under `03_shared-ui`) OR to a new `06b_canvas` component. Both options drop the same-layer edge. Decision should ride a Phase B cycle that already touches `CanvasEditor` — folding the move into a behavior change is cheaper than a standalone refactor.
|
||||
- **Task / Epic**: defer to Phase B (when a `CanvasEditor`-touching feature lands) or Step 8 refactor (optional).
|
||||
|
||||
### F3: Physical / logical owner split for `classColors.ts` (High / Architecture)
|
||||
|
||||
- **Location**: `src/features/annotations/classColors.ts`.
|
||||
- **Description**: The file is under `06_annotations`'s owns-glob (`src/features/annotations/**`) but the component spec assigns it to `11_class-colors` (Layer 0 shared kernel) — three external consumers depend on it (`03_shared-ui/DetectionClasses`, `06_annotations/{CanvasEditor,AnnotationsPage,AnnotationsSidebar}`, future `07_dataset` class-distribution chart). Module-layout Verification #1 records the workaround: `READ-ONLY` for `06_annotations` tasks. The workaround scales poorly — a new `06_annotations` contributor reading only the directory glob will not know the file is off-limits.
|
||||
- **Suggestion**: Move physical file to `src/shared/classColors.ts` (introducing a `src/shared/` layer for true Layer-0 utilities) or to `src/components/detection/classColors.ts` (under `03_shared-ui`). Either move drops the workaround and aligns physical/logical ownership.
|
||||
- **Task / Epic**: Step 4 testability — minimal, surgical move (rename + import-path update across 4 consumers).
|
||||
|
||||
### F4: No Public API barrels — every internal file is de-facto public (High / Architecture)
|
||||
|
||||
- **Location**: every component root (no `src/<component>/index.ts` exists today; only `src/types/index.ts` and `mission-planner/src/types/index.ts` are barrels and they're re-export hubs, not component facades).
|
||||
- **Description**: Cross-component imports use file-name granularity (`import { api } from '../api/client'`, `import { useFlight } from '../../components/FlightContext'`, etc.). Consequence: there is **no enforceable Public API surface**. Any internal refactor inside a component (split a file, rename an export) is a breaking change to every importer. Phase 7 Check #2 ("Public API respect") cannot meaningfully fail in this codebase because everything is public. Module-layout Verification #3 records the same observation.
|
||||
- **Suggestion**: Step 4 testability candidate — add `src/<component>/index.ts` for every component, re-exporting only the symbols listed in module-layout's "Public API (de-facto)" line for that component. Then a future Phase 7 invocation can flag deep imports as Architecture findings instead of folding into background noise.
|
||||
- **Task / Epic**: Step 4 testability (single mechanical change per component; ~11 new files + ~30 import-path edits).
|
||||
|
||||
### F5: Pre-existing import cycle inside port-source (High / Architecture)
|
||||
|
||||
- **Location**: `mission-planner/src/flightPlanning/MapView.tsx` (imports `MiniMap` on line 16) ↔ `mission-planner/src/flightPlanning/MiniMap.tsx` (imports `UpdateMapCenter` from `./MapView` on line 2).
|
||||
- **Description**: A named-handle cycle internal to `mission-planner/`. Module-layout Verification #5 + `00_discovery.md §7` already record it. Not introduced by this scan. The cycle does NOT cross component boundaries (both files belong to `05_flights` port-source). The cycle disappears at the end of the convergence (when `mission-planner/` is deleted).
|
||||
- **Suggestion**: No action. Track-only finding. Reason: fixing the cycle inside port-source means moving `UpdateMapCenter` to a third file — wasted work given the eventual delete. If the deployed tree gains the same cycle when porting, fix it there.
|
||||
- **Task / Epic**: (none — closed by mission-planner deletion in the final Phase B cycle).
|
||||
|
||||
### F6: No `src/shared/` infrastructure for cross-cutting concerns (Medium / Architecture)
|
||||
|
||||
- **Location**: codebase-wide. No `src/shared/` directory exists today (module-layout Layout Rules #4).
|
||||
- **Description**: There is no shared logger, no central error envelope, no config loader, no telemetry hook. Each feature page does ad-hoc `console.error` + silent catches (multiple module findings — annotations sidebar AI-detect silent catches, dataset silent catches, settings save without `try/finally`). Onboarding observability or a global error boundary today touches every feature.
|
||||
- **Suggestion**: Introduce `src/shared/` (or `src/components/util/`) at Phase B kickoff with:
|
||||
- `shared/logger.ts` — wraps `console.*`, adds revision + user context; replace ad-hoc `console.error`.
|
||||
- `shared/config.ts` — typed `import.meta.env.*` accessor (resolves P10 OpenWeatherMap key + the future env-base-URL refactor).
|
||||
- `shared/errorBoundary.tsx` — application-level boundary (today the SPA has no `ErrorBoundary` — recorded in `src__App-and-main.md` findings).
|
||||
- `shared/endpoints.ts` — typed endpoint constants (closes F7).
|
||||
- **Task / Epic**: Phase B candidate (one cycle for shared infrastructure) OR fold into Step 8 refactor if user picks A on the Step 8 gate.
|
||||
|
||||
### F7: Hardcoded `/api/<service>/...` paths instead of env-driven endpoints (Medium / Architecture)
|
||||
|
||||
- **Location**: every call site of `api.*()` and `createSSE()` across `src/features/**` and `src/auth/`, `src/components/FlightContext.tsx`, `src/components/DetectionClasses.tsx`. Approximately 30 call sites.
|
||||
- **Description**: Consequence of ADR-006 (nginx prefix-strip). Each call site repeats `/api/<service>/<path>` as a string literal. Testability suffers — every test fixture must duplicate paths; any nginx-route change touches every feature. Architecture intent (ADR-006 Consequences) explicitly flags this: *"The SPA hardcodes /api/<service>/... paths in source instead of an env-driven base URL — testability is poor (finding tracked)."*
|
||||
- **Suggestion**: Step 4 testability — introduce `src/shared/endpoints.ts` (or per-component `endpoints.ts` if shared/ is deferred) that exposes typed builders: `endpoints.auth.login()`, `endpoints.flights.byId(id)`, `endpoints.annotations.media(query)`, etc. Replace every string-literal path. Allows tests to mock at the endpoints layer rather than at every `fetch` call. Compounds well with F6 if `src/shared/` lands first.
|
||||
- **Task / Epic**: Step 4 testability (mechanical extract; per-component cohort).
|
||||
|
||||
### F8: Layering-table inconsistency — Header → useAuth is unannotated (Low / Architecture)
|
||||
|
||||
- **Location**: `_docs/02_document/module-layout.md` — "Allowed Dependencies (layering)" table vs "Per-Component Mapping" `03_shared-ui` row.
|
||||
- **Description**: The layering table says Layer 2 may import only from layers 0+1, no same-layer edges. The per-component table explicitly lists `03_shared-ui Imports from: ..., 02_auth`. The actual import `src/components/Header.tsx:3 → ../auth/AuthContext` is by design — every header needs the current user. This is not a code violation (the per-component table is authoritative for specific edges); it's a doc bug.
|
||||
- **Suggestion**: Add a layering-table footnote for `03_shared-ui` similar to the existing `07_dataset` footnote: *"03_shared-ui imports `useAuth` from `02_auth`'s `AuthContext` — same-layer cross-component edge, permitted as it is the only cross-cutting state-context dependency."* Update during Step 4 doc-touchup or fold into Step 13 docs cycle.
|
||||
- **Task / Epic**: documentation only — no code change.
|
||||
|
||||
### F9: Inert second Vite entry tree at port-source root (Low / Architecture)
|
||||
|
||||
- **Location**: `mission-planner/src/{main.tsx,App.tsx,setupTests.ts,vite-env.d.ts}`.
|
||||
- **Description**: `mission-planner/src/` carries its own Vite entrypoint (`main.tsx` + `App.tsx`), test setup file, and env shim. ADR-009 says the deployed Vite build does NOT compile this tree, but there is nothing in the codebase that **prevents** a future contributor from adding `mission-planner/` to a Vite `build.rollupOptions.input` and shipping two SPAs. Architecture intent is "vendored port-source, NOT a deployed component".
|
||||
- **Suggestion**: Step 4 testability or Step 8 refactor — verify `vite.config.ts` has no `mission-planner/` entry; if Vite ever adds workspace-aware builds, add explicit exclusion. Defer until the convergence retires the directory entirely.
|
||||
- **Task / Epic**: closed by F1's final delete cycle.
|
||||
|
||||
---
|
||||
|
||||
## Routing — what feeds where
|
||||
|
||||
Per `flows/existing-code.md` Step 2 → Step 4 / Step 8 rule, High and Critical Architecture findings must either (a) be appended to the testability `list-of-changes.md` input for Step 4, or (b) be deferred to Step 8 (optional Refactor) via Choose. Recommended routing:
|
||||
|
||||
| Finding | Recommended target step | Reason |
|
||||
|---------|----------------------------------------------------|------------------------------------------------------------------------|
|
||||
| F1 | **Phase B cycles** (NOT Step 4, NOT Step 8) | Behavior ports — need test safety net + per-feature deploy. |
|
||||
| F2 | **Phase B** (when a `CanvasEditor`-touching task lands) | Fold the lift into a behavior change cycle. |
|
||||
| F3 | **Step 4 testability** | Pure file move + import-path update — fits the "smallest fix" rule. |
|
||||
| F4 | **Step 4 testability** | 11 new `index.ts` files + cohort of import-path edits — mechanical. |
|
||||
| F5 | **No action** (closed by F1 final delete) | Fixing inside port-source is wasted work. |
|
||||
| F6 | **Phase B** (one infra cycle) OR **Step 8 refactor** | Shared logger / config / endpoints / error boundary — design choice. |
|
||||
| F7 | **Step 4 testability** | Endpoint extraction enables tests; depends on F6 if `src/shared/` is path. |
|
||||
| F8 | **Documentation touch-up** (no step) | Doc-only. |
|
||||
| F9 | **Defer** | Closed by F1 final delete. |
|
||||
|
||||
The 4 High and 1 Critical findings that should drive a Choose decision now:
|
||||
|
||||
- **F1** — Phase B work-list (not Step 4, not Step 8).
|
||||
- **F2** — Phase B side-quest (not Step 4, not Step 8).
|
||||
- **F3** — Step 4 candidate.
|
||||
- **F4** — Step 4 candidate.
|
||||
- **F5** — track-only (no decision needed).
|
||||
|
||||
---
|
||||
|
||||
## Baseline Delta
|
||||
|
||||
(N/A — this is the first baseline; no prior report to delta against. Future `code-review` invocations in `cumulative` or `full` mode will emit a Baseline Delta section against this file.)
|
||||
@@ -0,0 +1,87 @@
|
||||
# 00 — Foundation
|
||||
|
||||
## 1. High-Level Overview
|
||||
|
||||
**Purpose**: Pure leaf modules every other component depends on — TypeScript domain types, framework-agnostic React hooks, and i18next setup. No HTTP, no React tree, no business logic.
|
||||
|
||||
**Architectural Pattern**: Foundation / shared kernel.
|
||||
|
||||
**Upstream dependencies**: none (intra-repo). External: `i18next`, `react-i18next`, `react`.
|
||||
|
||||
**Downstream consumers**: every other `src/` component.
|
||||
|
||||
## 2. Internal Interfaces
|
||||
|
||||
### `src/types/index.ts`
|
||||
|
||||
| Export | Kind | Purpose |
|
||||
|--------|------|---------|
|
||||
| `DetectionClass`, `Annotation`, `Affiliation`, `CombatReadiness`, `AnnotationStatus`, `AnnotationSource`, `MediaStatus`, `Flight`, `Waypoint`, `DatasetItem`, `User`, `Permission`, etc. | type / enum | Shared domain shape used by `api/`, providers, and every feature page. |
|
||||
|
||||
> **CAVEAT — cross-cutting Step 4 work**. State.json records 4 enum-drift findings against the parent suite spec (`AnnotationStatus`, `Affiliation`, `CombatReadiness`, `MediaStatus`) plus a `Waypoint` shape mismatch. Owner of fix: this single file. The full target shapes live in `_docs/02_document/modules/src__features__annotations.md` findings #27–34 and `src__features__flights.md` finding #20.
|
||||
|
||||
### `src/hooks/useDebounce.ts`
|
||||
|
||||
| Export | Signature | Purpose |
|
||||
|--------|-----------|---------|
|
||||
| `useDebounce<T>(value: T, delay: number): T` | hook | Debounced value mirror. Used by Annotations search and Dataset filters. |
|
||||
|
||||
### `src/hooks/useResizablePanel.ts`
|
||||
|
||||
| Export | Signature | Purpose |
|
||||
|--------|-----------|---------|
|
||||
| `useResizablePanel(initialWidth: number, opts): { width, dragHandleProps }` | hook | Mouse-drag-resizable side panel. Used by Annotations and Dataset pages. Width is **not** persisted (finding #11 in `src__features__annotations.md`). |
|
||||
|
||||
### `src/i18n/i18n.ts`
|
||||
|
||||
| Export | Kind | Purpose |
|
||||
|--------|------|---------|
|
||||
| (default side-effect) | i18next init | Loads `en.json` + `ua.json`, wires `react-i18next`. Imported once by `main.tsx` for its side effect. |
|
||||
|
||||
> **CAVEAT**. `lng: 'en'` is hardcoded; no language detector or persistence. `ua.json` exists as a translation target but is not selectable at runtime (finding #1 in `src__i18n__i18n.md`). This is a Step 4 testability/configurability fix.
|
||||
|
||||
## 5. Implementation Details
|
||||
|
||||
| Module | Notes |
|
||||
|--------|-------|
|
||||
| `types/index.ts` | Plain TypeScript. No runtime code. |
|
||||
| `useDebounce` | `setTimeout` + `clearTimeout` in `useEffect`. |
|
||||
| `useResizablePanel` | `mousemove` listener attached to `window` while dragging; min/max width clamped. |
|
||||
| `i18n/i18n.ts` | i18next + ICU plurals. Bundles loaded synchronously (small JSONs, ~100 keys each). |
|
||||
|
||||
**State Management**: Stateless apart from the local hook state inside `useDebounce` / `useResizablePanel`. i18next's instance is module-level.
|
||||
|
||||
**Key Dependencies**:
|
||||
|
||||
| Library | Version | Purpose |
|
||||
|---------|---------|---------|
|
||||
| `i18next` | (per `package.json`) | Translation engine |
|
||||
| `react-i18next` | (per `package.json`) | React bindings; consumed via `useTranslation` in features |
|
||||
| `react` | 19 | Hooks runtime |
|
||||
|
||||
## 7. Caveats & Edge Cases
|
||||
|
||||
- Enum drift findings (cross-cutting). See state.json notes 2026-05-10 02:01Z and 02:13Z. Step 4 must reconcile against .NET service before patching `types/index.ts`.
|
||||
- `i18n` init is synchronous; if either bundle fails to load the app crashes at startup. No fallback.
|
||||
- `useResizablePanel` does not persist user-chosen width; resets every page nav.
|
||||
|
||||
## 8. Dependency Graph
|
||||
|
||||
**Must be implemented after**: nothing (Layer 0).
|
||||
|
||||
**Can be implemented in parallel with**: itself (the 4 modules are independent).
|
||||
|
||||
**Blocks**: every other component in this workspace.
|
||||
|
||||
## 6. Extensions and Helpers
|
||||
|
||||
`features/annotations/classColors.ts` was originally drafted as part of `06_annotations`, but per the Step 2 BLOCKING gate it has been lifted into its own component, **`11_class-colors`** (sibling shared kernel — see `components/11_class-colors/description.md`). The physical file location is unchanged — only the conceptual ownership moved. The proper physical home (a `src/shared/` or `src/components/detection/` directory) is deferred to Step 2.5 / Step 4 / Step 8.
|
||||
|
||||
## Module Inventory
|
||||
|
||||
| Path | Module Doc |
|
||||
|------|------------|
|
||||
| `src/types/index.ts` | `_docs/02_document/modules/src__types__index.md` |
|
||||
| `src/hooks/useDebounce.ts` | `_docs/02_document/modules/src__hooks__useDebounce.md` |
|
||||
| `src/hooks/useResizablePanel.ts` | `_docs/02_document/modules/src__hooks__useResizablePanel.md` |
|
||||
| `src/i18n/i18n.ts` | `_docs/02_document/modules/src__i18n__i18n.md` |
|
||||
@@ -0,0 +1,78 @@
|
||||
# 01 — API Transport
|
||||
|
||||
## 1. High-Level Overview
|
||||
|
||||
**Purpose**: Thin wrappers over the browser's `fetch` and `EventSource` that every feature uses to talk to the suite backend. Sole owners of cookie / bearer / refresh-token plumbing on the wire.
|
||||
|
||||
**Architectural Pattern**: HTTP/SSE facade. No service-specific clients — every feature passes string URLs directly.
|
||||
|
||||
**Upstream dependencies**: `00_foundation` (types).
|
||||
|
||||
**Downstream consumers**: `02_auth`, `03_shared-ui` (FlightContext, DetectionClasses), `05_flights`, `06_annotations`, `07_dataset`, `08_admin`, `09_settings`.
|
||||
|
||||
## 2. Internal Interfaces
|
||||
|
||||
### `src/api/client.ts`
|
||||
|
||||
| Export | Signature | Notes |
|
||||
|--------|-----------|-------|
|
||||
| `api.get<T>(url, opts?): Promise<T>` | thin `fetch` wrapper | Adds `credentials: 'include'`, parses JSON, throws on non-2xx |
|
||||
| `api.post<T>(url, body?, opts?): Promise<T>` | same | |
|
||||
| `api.put<T>(url, body?, opts?): Promise<T>` | same | |
|
||||
| `api.del<T>(url, opts?): Promise<T>` | same | |
|
||||
| `ApiError` | error class | Thrown with `{ status, body }` on non-2xx |
|
||||
|
||||
### `src/api/sse.ts`
|
||||
|
||||
| Export | Signature | Notes |
|
||||
|--------|-----------|-------|
|
||||
| `subscribe<T>(url, onMessage, onError?): { close }` | factory | Creates `EventSource` with the **bearer token in the query string** (browser `EventSource` can't set headers). Returns a `close()` handle. |
|
||||
|
||||
## 3. External API Specification
|
||||
|
||||
This component does not *expose* an API; it consumes the suite's. The set of consumed endpoints (collected from feature module docs):
|
||||
|
||||
| Service | Path prefix (after nginx strip) | Used by |
|
||||
|---------|---------------------------------|---------|
|
||||
| `admin/` auth | `/api/admin/auth/{login,refresh,logout,me,...}` | `02_auth`, `08_admin` |
|
||||
| `flights/` | `/api/flights/...` | `03_shared-ui` (FlightContext), `05_flights` |
|
||||
| `annotations/` | `/api/annotations/...` | `06_annotations`, `07_dataset`, `08_admin` (read) |
|
||||
| `detect/` | `/api/detect/...` | `06_annotations` |
|
||||
| `loader/`, `resource/`, `gps-denied-*`, `autopilot/` | `/api/{loader,resource,gps-denied-desktop,gps-denied-onboard,autopilot}/...` | various features |
|
||||
|
||||
**No service-specific client modules exist**. URL strings are inlined at every call site (testability finding from autodev Step 4).
|
||||
|
||||
## 5. Implementation Details
|
||||
|
||||
| Concern | Behavior |
|
||||
|---------|----------|
|
||||
| Auth bootstrap | `client.ts` does NOT auto-attach `credentials: 'include'` on the very first call from `AuthContext` startup — finding B3 (`src__auth__AuthContext.md`). Cookie-based session bootstrap therefore fails on first refresh. **PRIORITY for Step 4.** |
|
||||
| Refresh-token rotation | Server rotates access tokens via `X-Refresh-Token` header. `client.ts` handles refresh on 401 for fetch; `sse.ts` does **NOT** — `EventSource` holds the bearer captured at create time and dies after rotation (finding in `src__api__sse.md`). |
|
||||
| Timeouts | None — no `AbortController` wired up. Long requests (e.g., dataset bulk export) can hang indefinitely. Step 4. |
|
||||
| Error reporting | `ApiError` thrown to caller. Most features `catch` and call `alert()` or `console.error` silently — uneven across features. |
|
||||
|
||||
**State Management**: Module-level only — `sse.ts` keeps no registry; each subscription is independent.
|
||||
|
||||
**Key Dependencies**: native `fetch`, native `EventSource`. No third-party HTTP library.
|
||||
|
||||
## 7. Caveats & Edge Cases
|
||||
|
||||
- **No timeout / cancellation**. (Step 4.)
|
||||
- **Bearer in SSE query string**. Accepted trade-off; document in `security_approach.md` (Step 6).
|
||||
- **No reconnect-on-token-rotate** for SSE consumers — every feature that uses SSE will silently stop receiving events after the first refresh (Step 8 hardening).
|
||||
- **No service-specific clients** → URL strings duplicated across features. Risk of typos surfacing as 404s only at runtime (Step 4).
|
||||
|
||||
## 8. Dependency Graph
|
||||
|
||||
**Must be implemented after**: `00_foundation`.
|
||||
|
||||
**Can be implemented in parallel with**: `00_foundation` (it has no internal deps beyond types).
|
||||
|
||||
**Blocks**: `02_auth`, every feature page, `03_shared-ui` (FlightContext, DetectionClasses).
|
||||
|
||||
## Module Inventory
|
||||
|
||||
| Path | Module Doc |
|
||||
|------|------------|
|
||||
| `src/api/client.ts` | `_docs/02_document/modules/src__api__client.md` |
|
||||
| `src/api/sse.ts` | `_docs/02_document/modules/src__api__sse.md` |
|
||||
@@ -0,0 +1,84 @@
|
||||
# 02 — Auth
|
||||
|
||||
## 1. High-Level Overview
|
||||
|
||||
**Purpose**: Authentication state, login/logout/refresh plumbing, and the `<ProtectedRoute>` gate that wraps every non-public route.
|
||||
|
||||
**Architectural Pattern**: React Context provider + route-guard component.
|
||||
|
||||
**Upstream dependencies**: `00_foundation` (types), `01_api-transport`.
|
||||
|
||||
**Downstream consumers**: `04_login`, `10_app-shell`, every authenticated page (indirectly via the route gate).
|
||||
|
||||
## 2. Internal Interfaces
|
||||
|
||||
### `src/auth/AuthContext.tsx`
|
||||
|
||||
| Export | Signature | Notes |
|
||||
|--------|-----------|-------|
|
||||
| `AuthProvider({ children })` | React component | Wraps the app below `BrowserRouter`. Bootstraps via `GET /api/admin/auth/refresh` on mount. |
|
||||
| `useAuth(): AuthContextValue` | hook | Read-only access to `{ user, permissions, login, logout, refresh, loading }`. |
|
||||
|
||||
**`AuthContextValue`** (output DTO):
|
||||
|
||||
```
|
||||
user: User | null
|
||||
permissions: Permission[] ← from server, used by route guards & UI
|
||||
loading: boolean ← true during initial bootstrap and active refresh
|
||||
login(c): Promise<User> ← POST /api/admin/auth/login
|
||||
logout(): Promise<void> ← POST /api/admin/auth/logout
|
||||
refresh(): Promise<void> ← POST /api/admin/auth/refresh
|
||||
```
|
||||
|
||||
### `src/auth/ProtectedRoute.tsx`
|
||||
|
||||
| Export | Signature | Notes |
|
||||
|--------|-----------|-------|
|
||||
| `ProtectedRoute({ children, requirePermission? })` | React component | Renders children if authenticated; otherwise navigates to `/login`. Optional `requirePermission` is checked against `useAuth().permissions` and renders a 403 placeholder on miss. |
|
||||
|
||||
## 3. External API Specification
|
||||
|
||||
Consumes only — does not expose. Endpoint set (from `_docs/02_document/modules/src__auth__AuthContext.md`):
|
||||
|
||||
| Method | Path | Auth | When |
|
||||
|--------|------|------|------|
|
||||
| POST | `/api/admin/auth/login` | public | Login form submit |
|
||||
| POST | `/api/admin/auth/refresh` | cookie | Bootstrap + on 401 retry |
|
||||
| POST | `/api/admin/auth/logout` | cookie | Header → Logout |
|
||||
| GET | `/api/admin/auth/me` | cookie | (post-login profile fetch, if implemented) |
|
||||
|
||||
## 5. Implementation Details
|
||||
|
||||
**State Management**: Single React context. Token lives in an HTTP-only cookie (server-managed); the React state holds only the parsed user + permissions. No `localStorage`.
|
||||
|
||||
**Bootstrap sequence**:
|
||||
1. Mount → set `loading: true`.
|
||||
2. `api.post('/api/admin/auth/refresh')` to ask the server "do I have a valid session?".
|
||||
3. On 200 → store user + permissions, `loading: false`.
|
||||
4. On 4xx → user stays `null`, `loading: false`. `ProtectedRoute` then redirects.
|
||||
|
||||
> **PRIORITY finding (B3, copied from state.json)**: the bootstrap call inside `AuthContext.tsx` does not pass `credentials: 'include'` consistently — the cookie is therefore not sent on the very first request and bootstrap silently fails on a fresh page load. Confirmed real bug; Step 4 fix.
|
||||
|
||||
**Spinner UX**: `ProtectedRoute` renders a centered spinner during `loading`. The spinner has **no** `role="status"` / no accessible label / no timeout. (Findings B4, joint with Step 4 client.ts timeout flag.)
|
||||
|
||||
## 7. Caveats & Edge Cases
|
||||
|
||||
- **Bootstrap missing `credentials: 'include'`** → users land on `/login` even with a valid cookie session. PRIORITY Step 4.
|
||||
- **Spinner accessibility** — Step 4.
|
||||
- **Token-rotation interaction with SSE** — see `01_api-transport`. Auth refresh works for fetch but breaks every active EventSource.
|
||||
- **No idle-timeout / inactivity logout** — server-side concern; UI tolerates whatever the server enforces.
|
||||
|
||||
## 8. Dependency Graph
|
||||
|
||||
**Must be implemented after**: `00_foundation`, `01_api-transport`.
|
||||
|
||||
**Can be implemented in parallel with**: nothing inside this workspace's gate path.
|
||||
|
||||
**Blocks**: `03_shared-ui` (Header reads `useAuth`), `04_login`, `10_app-shell`, indirectly every authenticated page.
|
||||
|
||||
## Module Inventory
|
||||
|
||||
| Path | Module Doc |
|
||||
|------|------------|
|
||||
| `src/auth/AuthContext.tsx` | `_docs/02_document/modules/src__auth__AuthContext.md` |
|
||||
| `src/auth/ProtectedRoute.tsx` | `_docs/02_document/modules/src__auth__ProtectedRoute.md` |
|
||||
@@ -0,0 +1,90 @@
|
||||
# 03 — Shared UI & Cross-Cutting Context
|
||||
|
||||
## 1. High-Level Overview
|
||||
|
||||
**Purpose**: Reusable presentational components and the **flight selection context** that every authenticated page reads from. This is the "page chrome + flight scope" layer — the navbar, the help modal, the confirmation dialog, the detection-class picker, and the `FlightContext` provider that holds "which flight the user is currently working in".
|
||||
|
||||
**Architectural Pattern**: Mix of presentational components + one cross-cutting Context provider. `FlightContext` lives in `components/` (not `features/flights/`) because it is read by every feature page (Annotations, Dataset, Admin, Settings, Header).
|
||||
|
||||
**Upstream dependencies**: `00_foundation` (types), `01_api-transport`, `02_auth` (Header reads `useAuth`), `11_class-colors` (DetectionClasses fallback colors / names).
|
||||
|
||||
**Downstream consumers**: `10_app-shell` (mounts Header + FlightProvider), every feature page (consumes `useFlight()` and uses ConfirmDialog), `06_annotations` and `07_dataset` (use DetectionClasses + ConfirmDialog).
|
||||
|
||||
## 2. Internal Interfaces
|
||||
|
||||
### `src/components/Header.tsx`
|
||||
|
||||
| Export | Notes |
|
||||
|--------|-------|
|
||||
| `Header()` | Top bar: app logo, page nav links (`/flights`, `/annotations`, `/dataset`, `/admin`, `/settings`), flight-picker dropdown, language switch, user menu (logout, help). Mobile bottom-nav variant rendered conditionally (lines 113–129 per state.json correction). |
|
||||
|
||||
### `src/components/HelpModal.tsx`
|
||||
|
||||
| Export | Notes |
|
||||
|--------|-------|
|
||||
| `HelpModal({ open, onClose })` | Renders an in-page modal with `GUIDELINES` (currently a hardcoded string — finding: should be in i18n bundle). Esc does NOT close (inconsistent with `ConfirmDialog`). |
|
||||
|
||||
### `src/components/ConfirmDialog.tsx`
|
||||
|
||||
| Export | Notes |
|
||||
|--------|-------|
|
||||
| `ConfirmDialog({ open, title, message, confirmLabel, onConfirm, onCancel })` | Reusable confirm modal. Esc closes. **Missing `aria-modal` and `role="dialog"`** — finding flagged for Step 4 vs `ui_design/README.md` confirmation-dialogs spec. |
|
||||
|
||||
### `src/components/DetectionClasses.tsx`
|
||||
|
||||
| Export | Notes |
|
||||
|--------|-------|
|
||||
| `DetectionClasses({ value, onChange, ... })` | Detection-class picker grid. Loads classes from `GET /api/annotations/classes`. Number-key shortcuts 1–9 select `classes[idx + photoMode]` — ordering against the annotations service contract is unverified (Step 4). Imports from `11_class-colors` for fallback color and name (current physical path: `src/features/annotations/classColors.ts` — file location is misplaced; see `11_class-colors` §7 for refactor target). |
|
||||
|
||||
### `src/components/FlightContext.tsx`
|
||||
|
||||
| Export | Notes |
|
||||
|--------|-------|
|
||||
| `FlightProvider({ children })` | Loads flight list (paged, **`pageSize=1000` ceiling hardcoded** — finding B3) on mount. |
|
||||
| `useFlight(): FlightContextValue` | hook returning `{ flights, selectedFlight, selectFlight, refresh }`. `selectFlight` is **fire-and-forget** PUT to `/api/flights/select` — no error UI. |
|
||||
|
||||
## 5. Implementation Details
|
||||
|
||||
**State Management**:
|
||||
- Local component state for modals (open/closed).
|
||||
- One Context provider (`FlightProvider`) holding the cached flight list and current selection.
|
||||
- No global event bus.
|
||||
|
||||
**Routing awareness**: `Header` reads `useLocation()` to highlight the active link. `FlightProvider` does **not** persist selection across reloads.
|
||||
|
||||
**Accessibility** (cross-cutting findings, Step 4):
|
||||
- `ConfirmDialog` — no `aria-modal` / `role="dialog"` / focus trap.
|
||||
- `Header` flight dropdown — no `role="combobox"`, no `aria-expanded`, no Esc-to-close, no focus trap; outside-click handler always attached.
|
||||
- `HelpModal` — Esc does NOT close.
|
||||
|
||||
**Key Dependencies**: `react-router-dom` 7 (Header), `react-i18next`.
|
||||
|
||||
## 6. Extensions and Helpers
|
||||
|
||||
Class color / fallback name / PhotoMode suffix logic lives in `11_class-colors`. This component depends on it; it is no longer treated as a cross-layer leak — the *physical* file is misplaced (still in `src/features/annotations/`) but the *logical* dependency is a normal shared-layer dependency.
|
||||
|
||||
## 7. Caveats & Edge Cases
|
||||
|
||||
- **`classColors.ts` physical location** is `src/features/annotations/` even though it is logically a `11_class-colors` shared module. Step 4 testability candidate (file move) — does not break this component's dependency graph.
|
||||
- **`FlightContext.pageSize=1000`** — silent ceiling; >1000 flights are invisible.
|
||||
- **`selectFlight` fire-and-forget PUT** — server failures are invisible to the UI.
|
||||
- **`Header` flight dropdown a11y gaps** — Step 4 + Step 8.
|
||||
- **`HelpModal` GUIDELINES hardcoded** — Step 4 i18n.
|
||||
|
||||
## 8. Dependency Graph
|
||||
|
||||
**Must be implemented after**: `00_foundation`, `01_api-transport`, `02_auth`, `11_class-colors`.
|
||||
|
||||
**Can be implemented in parallel with**: nothing critical inside the workspace.
|
||||
|
||||
**Blocks**: `10_app-shell`, every feature page (they import `ConfirmDialog`, `useFlight`, and read `Header` from the shell).
|
||||
|
||||
## Module Inventory
|
||||
|
||||
| Path | Module Doc |
|
||||
|------|------------|
|
||||
| `src/components/Header.tsx` | `_docs/02_document/modules/src__components__Header.md` |
|
||||
| `src/components/HelpModal.tsx` | `_docs/02_document/modules/src__components__HelpModal.md` |
|
||||
| `src/components/ConfirmDialog.tsx` | `_docs/02_document/modules/src__components__ConfirmDialog.md` |
|
||||
| `src/components/DetectionClasses.tsx` | `_docs/02_document/modules/src__components__DetectionClasses.md` |
|
||||
| `src/components/FlightContext.tsx` | `_docs/02_document/modules/src__components__FlightContext.md` |
|
||||
@@ -0,0 +1,48 @@
|
||||
# 04 — Login
|
||||
|
||||
## 1. High-Level Overview
|
||||
|
||||
**Purpose**: The single public route `/login`. Renders the credential form and triggers `useAuth().login(...)`.
|
||||
|
||||
**Architectural Pattern**: Single-page feature module with one entry component.
|
||||
|
||||
**Upstream dependencies**: `02_auth` (`useAuth().login`).
|
||||
|
||||
**Downstream consumers**: `10_app-shell` (routed at `/login`).
|
||||
|
||||
## 2. Internal Interfaces
|
||||
|
||||
| Export | Notes |
|
||||
|--------|-------|
|
||||
| `LoginPage()` | Form: username + password + submit. Calls `useAuth().login({ username, password })` and on success navigates to `/flights`. Error state shown inline. |
|
||||
|
||||
## 5. Implementation Details
|
||||
|
||||
- "Theatrical" unlock animation (`runUnlockSequence`, 4 × 600 ms) plays on success before navigation. Documented in Step 5 solution.md as a UX choice, not a bug.
|
||||
- No "remember me" / persistent-session toggle.
|
||||
- No SSO integration.
|
||||
- No password-strength feedback or recovery link.
|
||||
|
||||
**State Management**: Local component state only.
|
||||
|
||||
**Key Dependencies**: `react-router-dom` (`useNavigate`), `react-i18next`.
|
||||
|
||||
## 7. Caveats & Edge Cases
|
||||
|
||||
- **2.4 s artificial delay** post-login (Step 5 doc note).
|
||||
- **No CSRF token** in the login POST body — server is expected to validate the same-site cookie pattern; document in `security_approach.md` (Step 6).
|
||||
- **No rate-limit feedback** — server returns `429` with no specific UI handling beyond a generic `alert`.
|
||||
|
||||
## 8. Dependency Graph
|
||||
|
||||
**Must be implemented after**: `02_auth`.
|
||||
|
||||
**Can be implemented in parallel with**: every feature page (`05_flights` … `09_settings`).
|
||||
|
||||
**Blocks**: nothing.
|
||||
|
||||
## Module Inventory
|
||||
|
||||
| Path | Module Doc |
|
||||
|------|------------|
|
||||
| `src/features/login/LoginPage.tsx` | `_docs/02_document/modules/src__features__login__LoginPage.md` |
|
||||
@@ -0,0 +1,189 @@
|
||||
# 05 — Flights & Mission Planning
|
||||
|
||||
## 1. High-Level Overview
|
||||
|
||||
**Purpose**: One logical component covering everything mission/flight related — flight CRUD, waypoint editing, altitude profile, wind/battery calc, raw mission JSON I/O, and **GPS-Denied** operations (incl. an end-to-end **test mode** that simulates a real flight from a tlog + video pair). It is currently **physically split** across two codebases that the project intends to converge.
|
||||
|
||||
**Architectural Pattern**: Page composition (`FlightsPage`) wiring three sibling panels — `FlightListSidebar`, `FlightParamsPanel`, `FlightMap` — plus modals (`AltitudeDialog`, `JsonEditorDialog`) and a GPS-Denied sub-page.
|
||||
|
||||
**Implementation status — two trees, one component**:
|
||||
|
||||
| Tree | What it is | Deployed? |
|
||||
|------|------------|-----------|
|
||||
| `src/features/flights/` (15 modules, React 19 + Tailwind) | The **target** implementation. Mostly a mechanical port-in-progress of the tree below. | **Yes** — Dockerfile builds `src/` only. |
|
||||
| `mission-planner/` (37 modules, React 18 + MUI 5) | The **port source / reference**. The richer, more battle-tested mission planner that the new SPA is being adapted from. | **No.** Disjoint dependency island. Deletion candidate after parity. |
|
||||
|
||||
The two trees are intentionally disjoint at the file level (no cross-imports — `00_discovery.md` §1) but they are **one component in the design**: same domain, same data model, same intent. Findings, port plan, and architecture decisions are tracked in this single component spec. Mission-planner files are listed in §"Module Inventory" below alongside the new SPA files; per-finding origin is preserved.
|
||||
|
||||
**Upstream dependencies** (target tree): `00_foundation`, `01_api-transport`, `03_shared-ui` (FlightContext, ConfirmDialog).
|
||||
|
||||
**Downstream consumers**: `10_app-shell` (routes `/flights` and the GPS-Denied sub-page).
|
||||
|
||||
## 2. Internal Interfaces
|
||||
|
||||
### Page entries (target tree, `src/features/flights/`)
|
||||
|
||||
| Export | Notes |
|
||||
|--------|-------|
|
||||
| `FlightsPage()` | Top-level route component for `/flights`. Uses `useFlight()`, fetches flight detail by id, exposes save/delete/duplicate. Wires `react-leaflet`, `leaflet-draw`, and `chart.js`. |
|
||||
| `GpsDeniedPage()` *(planned route, see §6)* | Sub-page for GPS-denied operations and test mode. Today a partial inline panel inside `FlightsPage` (finding #25) — slated to become its own route. |
|
||||
|
||||
### Internal modules — target tree (`src/features/flights/`)
|
||||
|
||||
| Module | Role |
|
||||
|--------|------|
|
||||
| `FlightsPage.tsx` | Orchestrator (route component) |
|
||||
| `FlightMap.tsx` | Leaflet map + draw control + waypoint markers + minimap |
|
||||
| `FlightListSidebar.tsx` | Left panel: flight list, search, new/duplicate/delete |
|
||||
| `FlightParamsPanel.tsx` | Right panel: name, aircraft, takeoff/landing, altitude chart, waypoint list, wind effect |
|
||||
| `WaypointList.tsx` | DnD-sortable waypoints (`@hello-pangea/dnd`) |
|
||||
| `AltitudeChart.tsx` | `chart.js` altitude profile |
|
||||
| `WindEffect.tsx` | Wind-vector visualisation |
|
||||
| `MiniMap.tsx` | Inline overview map |
|
||||
| `MapPoint.tsx` | Single waypoint marker |
|
||||
| `DrawControl.tsx` | `leaflet-draw` integration |
|
||||
| `AltitudeDialog.tsx` | Per-waypoint altitude/purpose modal |
|
||||
| `JsonEditorDialog.tsx` | Raw mission-JSON editor |
|
||||
| `flightPlanUtils.ts` | Distance / battery / weather computation helpers |
|
||||
| `mapIcons.ts` | Leaflet icon factory |
|
||||
| `types.ts` | Local feature types (waypoint shape, mission JSON shape) |
|
||||
|
||||
### Internal modules — port source (`mission-planner/`)
|
||||
|
||||
| Group | Modules | Role / what the target should learn |
|
||||
|-------|---------|-------------------------------------|
|
||||
| Entry | `main.tsx`, `App.tsx` (vestigial CRA stub) | Composition root + LanguageProvider. The CRA stub `App.tsx` is a deletion candidate post-port. |
|
||||
| Page composition | `flightPlanning/flightPlan.tsx`, `LeftBoard.tsx` | Canonical page shape (sidebar + map). |
|
||||
| Map | `flightPlanning/MapView.tsx` (cycle-paired with `MiniMap.tsx`), `MiniMap.tsx`, `DrawControl.tsx`, `MapPoint.tsx` | Reference Leaflet integration. **Cycle**: `MiniMap` imports the *named* helper `UpdateMapCenter` from `MapView`; `MapView` imports `MiniMap` as JSX child. Document the contract precisely if porting both at once. |
|
||||
| Panels | `flightPlanning/PointsList.tsx`, `AltitudeChart.tsx`, `AltitudeDialog.tsx`, `WindEffect.tsx`, `TotalDistance.tsx`, `JsonEditorDialog.tsx`, `LanguageSwitcher.tsx`, `Aircraft.ts` | Reference panel shapes. Several have richer behaviour than the current SPA siblings. |
|
||||
| Services | `services/calculateBatteryUsage.ts`, `AircraftService.ts`, `WeatherService.ts`, `calculateDistance.ts` | **Authoritative** battery / weather / distance logic. The target's `flightPlanUtils.ts` is currently an inferior port (silent errors, sequential `await`, hardcoded API key). |
|
||||
| i18n | `flightPlanning/LanguageContext.tsx`, `constants/translations.ts`, `constants/languages.ts` | Local translation pattern. The port should converge to `00_foundation/i18n` instead. |
|
||||
| Constants | `constants/{actionModes,maptypes,tileUrls,purposes}.ts` | Reference constant tables. |
|
||||
| Icons | `icons/{MapIcons,PointIcons,SidebarIcons,PhoneIcon}.tsx` | Reference icon factory. |
|
||||
| Utilities | `utils.ts`, `config.ts`, `types/index.ts` | Reference helpers + types. |
|
||||
| Test (vestigial) | `test/jsonImport.test.ts`, `setupTests.ts` | One Jest test that **cannot run today** (Jest not in `package.json`). Out of scope for the live SPA test plan. |
|
||||
|
||||
## 3. External API Specification
|
||||
|
||||
Endpoints consumed (target tree + planned for GPS-Denied):
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|--------|------|---------|
|
||||
| GET | `/api/flights` | List + page (`pageSize=1000` ceiling from `FlightContext`) |
|
||||
| GET | `/api/flights/{id}` | Detail + waypoints |
|
||||
| POST | `/api/flights` | Create |
|
||||
| PUT | `/api/flights/{id}` | Update flight metadata |
|
||||
| DELETE | `/api/flights/{id}` | Delete |
|
||||
| POST/DELETE | `/api/flights/{id}/waypoints` | Add / remove waypoints |
|
||||
| POST | `/api/gps-denied-desktop/...` | GPS-denied desktop service (mission setup, plan upload) — partial today |
|
||||
| POST | `/api/gps-denied-onboard/...` | GPS-denied onboard service (frame + IMU consumer) — target of test-mode SITL output |
|
||||
| GET | OpenWeatherMap (third-party, **direct from browser**) | Wind/temperature lookup. **Will be proxied via suite** as part of Step 4 (hardcoded key removal). |
|
||||
|
||||
Concrete GPS-Denied endpoint shapes are **not yet finalised** in the suite spec — flagged for confirmation in autodev Step 3 (Test Spec) and Step 6 (Problem Extraction).
|
||||
|
||||
## 5. Implementation Details
|
||||
|
||||
**State Management**: Page-local React state for the active flight; `FlightContext` (in `03_shared-ui`) for the list of flights.
|
||||
|
||||
**Save model — current shape, target tree** (finding #19): on Save, the UI deletes all existing waypoints and POSTs each one again. N delete + M POST round-trips. **Lossy** — concurrent edits race; if a POST fails halfway through, the saved flight is left with truncated waypoints. The `mission-planner/` reference does this differently (single mission-JSON PUT) and is the recommended target shape.
|
||||
|
||||
**Waypoint POST shape mismatch (PRIORITY, finding #20)**: target tree sends `{name, latitude, longitude, order}`; suite spec wants `{Geopoint:{Lat,Lon,MGRS}, Source, Objective, OrderNum, Height}`. Strict server returns 400. Owner of fix: this component + `00_foundation/types/index.ts::Waypoint`.
|
||||
|
||||
**Battery / weather calc** (target tree `flightPlanUtils.ts`):
|
||||
- **Hardcoded OpenWeather API key in source** (`'335799082893fad97fa36118b131f919'`) — committed secret. Step 4 fix.
|
||||
- Sequential `await` per segment — perf trap on long missions.
|
||||
- Silent `try/catch` swallows weather errors.
|
||||
- Mixes km / m altitudes; ambiguous battery-capacity unit (Wh vs Ws).
|
||||
- Port source (`mission-planner/services/`) has a cleaner, more correct implementation — use it as the reference.
|
||||
|
||||
**Map / icons**:
|
||||
- Target tree `mapIcons.ts::defaultIcon` CDN URL pinned to `leaflet@1.7.1` while `package.json` has 1.9.4.
|
||||
- `MiniMap` map-tile licence attribution missing in some configurations.
|
||||
|
||||
**Modal a11y** (`AltitudeDialog`, `JsonEditorDialog`) — no `aria-modal` / `role="dialog"` / focus trap. Step 4. Same gap on the port-source counterparts.
|
||||
|
||||
**Tech-stack divergence between the two trees** (carry into the port plan):
|
||||
|
||||
| Concern | `mission-planner/` | `src/features/flights/` (target) |
|
||||
|---------|-------------------|----------------------------------|
|
||||
| React | 18 | 19 |
|
||||
| UI library | MUI 5 | Tailwind 4 + custom `az-*` tokens |
|
||||
| i18n | local `LanguageContext` | `react-i18next` (Foundation) |
|
||||
| `react-leaflet` | 4.2 | 5 |
|
||||
| `@hello-pangea/dnd` | 16 | 18 |
|
||||
|
||||
**Key Dependencies** (target tree): `leaflet` 1.9, `react-leaflet` 5, `leaflet-draw`, `leaflet-polylinedecorator`, `chart.js` 4, `@hello-pangea/dnd` 18.
|
||||
|
||||
## 6. GPS-Denied sub-feature
|
||||
|
||||
Today a **partial** UI panel exists inside `FlightsPage` (target tree finding #25). The component design promotes this to a first-class sub-page with two tabs.
|
||||
|
||||
### 6a. Operations tab — current intent (already present, partial)
|
||||
|
||||
- Upload / select a mission plan.
|
||||
- Configure GPS-denied desktop parameters.
|
||||
- Hand off to onboard.
|
||||
|
||||
The exact endpoints are partially wired today and tracked under "External API Specification" above.
|
||||
|
||||
### 6b. **Test mode** — new subitem (per `_docs/how_to_test.md`)
|
||||
|
||||
> **Source of truth**: `_docs/how_to_test.md`. Architecture Vision artifact (`/document` Step 4.5) MUST surface this verbatim.
|
||||
|
||||
**Goal**: enable end-to-end testing of the GPS-denied onboard system **without a real flight**, using a recorded telemetry log + video pair.
|
||||
|
||||
**User journey**:
|
||||
|
||||
1. **Upload tlog file** (MAVLink telemetry log).
|
||||
2. **Upload video** synced with the tlog (the two are **usually not** time-aligned at the file level — the system aligns them).
|
||||
3. The system:
|
||||
- Extracts **timestamps, IMU, and GPS** samples from the tlog.
|
||||
- **Auto-syncs** video to tlog by detecting the take-off moment in the IMU stream and matching it to the corresponding frame in the video. Most test sessions are quadcopter "ground-to-ground" flights; the start-on-ground signature in the IMU is the alignment anchor.
|
||||
- Spawns a **SITL** (Software-In-The-Loop) instance.
|
||||
- **Feeds IMU samples + video frames** into the GPS-denied **onboard** system in lockstep.
|
||||
4. The user observes the onboard system's outputs (position estimate, drift, GPS-recovery moments) on the same map / chart components used for live flights — reusing `FlightMap`, `AltitudeChart`, and a results overlay.
|
||||
|
||||
**Scope notes for downstream skills**:
|
||||
|
||||
- This sub-feature is **not implemented today**. It is a planned addition that this component will own.
|
||||
- The tlog parser, IMU/video sync, and SITL controller are **suite-side services**; this component contributes the upload UI, the run controller, and the result overlay.
|
||||
- Test-mode I/O endpoints will live under `/api/gps-denied-desktop/test/...` (proposed; confirm in `autodev` Step 3 / Step 6).
|
||||
- The existing `/document` Step 1 finding "GPS-Denied panel partial" remains valid for the Operations tab and is broadened to track the Test mode tab as well.
|
||||
|
||||
## 7. Caveats & Edge Cases
|
||||
|
||||
26 numbered findings consolidated in `src__features__flights.md`. Highest-priority Step 4 items:
|
||||
|
||||
1. **Hardcoded OpenWeather API key** — rotate + remove + proxy via suite.
|
||||
2. **Waypoint POST shape mismatch + delete-then-recreate save model** — likely-broken on a strict suite server. Reference port-source's PUT-mission-JSON model.
|
||||
3. **`flightPlanUtils.ts` units / silent errors / sequential awaits.** Replace with port-source services.
|
||||
4. **Modal a11y** + **flight dropdown a11y** (overlap with Shared UI).
|
||||
5. **Leaflet 1.7.1 CDN URL drift.**
|
||||
|
||||
Mission-planner-side caveats (port-only):
|
||||
|
||||
- `mission-planner/src/test/jsonImport.test.ts` cannot run (Jest absent). **Do not** add Jest just for this one test.
|
||||
- `mission-planner/src/App.tsx` is a CRA stub. Delete only after parity.
|
||||
- `MapView.tsx ↔ MiniMap.tsx` named-handle cycle. Document precisely.
|
||||
|
||||
GPS-Denied-side caveats:
|
||||
|
||||
- Operations tab is partial (finding #25 unchanged).
|
||||
- **Test mode** is unimplemented — no risk of regression today, but the design must accommodate the eventual test-mode entry point in routing and in `FlightContext`.
|
||||
|
||||
## 8. Dependency Graph
|
||||
|
||||
**Must be implemented after**: `00_foundation`, `01_api-transport`, `03_shared-ui`.
|
||||
|
||||
**Can be implemented in parallel with**: every other feature page.
|
||||
|
||||
**Blocks**: `10_app-shell` (routes to `/flights` as default authenticated landing; will also host the GPS-Denied sub-route).
|
||||
|
||||
**Internal port order** (within this component): port `services/` (battery/weather/distance) → port `flightPlanning/` panels (`AltitudeChart`, `WindEffect`, `PointsList`) → port `MapView/MiniMap` cycle group → fold the `mission-planner/` tree out as the target reaches parity.
|
||||
|
||||
## Module Inventory
|
||||
|
||||
| Tree | Module Doc |
|
||||
|------|------------|
|
||||
| `src/features/flights/*` (15 modules) | `_docs/02_document/modules/src__features__flights.md` |
|
||||
| `mission-planner/*` (37 modules) | `_docs/02_document/modules/mission-planner.md` |
|
||||
@@ -0,0 +1,132 @@
|
||||
# 06 — Annotations
|
||||
|
||||
## 1. High-Level Overview
|
||||
|
||||
**Purpose**: Image / video annotation editor — bounding boxes, classes, affiliation, combat readiness, AI detection (sync + async via SSE), and the media-list browser scoped to the active flight.
|
||||
|
||||
**Architectural Pattern**: Page composition (`AnnotationsPage`) wiring `MediaList` + `VideoPlayer` (or static image) + `CanvasEditor` + `AnnotationsSidebar` + `DetectionClasses`.
|
||||
|
||||
**Upstream dependencies**: `00_foundation`, `01_api-transport`, `03_shared-ui` (FlightContext, ConfirmDialog, DetectionClasses), `11_class-colors`.
|
||||
|
||||
**Downstream consumers**: `10_app-shell` (routed at `/annotations`); `07_dataset` imports `CanvasEditor` directly (cross-feature edge — see baseline scan).
|
||||
|
||||
## 2. Internal Interfaces
|
||||
|
||||
| Export | Notes |
|
||||
|--------|-------|
|
||||
| `AnnotationsPage()` | Top-level route component. Manages selected media, panel widths (via `useResizablePanel`), and the open annotation under edit. |
|
||||
|
||||
Internal modules:
|
||||
|
||||
| Module | Role |
|
||||
|--------|------|
|
||||
| `AnnotationsPage.tsx` | Orchestrator (route component) |
|
||||
| `MediaList.tsx` | Left panel: thumbnail browser + search/filter; consumes `useFlight()` |
|
||||
| `VideoPlayer.tsx` | HTML5 video + frame seek + per-frame annotation overlays |
|
||||
| `CanvasEditor.tsx` | Bounding-box draw / move / resize layer (also used by `07_dataset`) |
|
||||
| `AnnotationsSidebar.tsx` | Right panel: annotation list, AI-detect controls |
|
||||
|
||||
## 3. External API Specification
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|--------|------|---------|
|
||||
| GET | `/api/annotations/media?flightId=...` | List media |
|
||||
| GET | `/api/annotations/media/{id}` | Media metadata |
|
||||
| GET | `/api/annotations/media/{id}/annotations` | Bbox list |
|
||||
| POST | `/api/annotations` | Create one |
|
||||
| PUT | `/api/annotations/{id}` | Update one |
|
||||
| DELETE | `/api/annotations/{id}` | Delete one |
|
||||
| POST | `/api/detect/{mediaId}` | Sync image AI-detect |
|
||||
| POST | `/api/detect/video/{mediaId}` | Async video AI-detect — should send `X-Refresh-Token`, currently does not (finding #30) |
|
||||
| GET | `/api/detect/classes` | Detection class list |
|
||||
| SSE | `/api/detect/stream/{jobId}` | Async detect progress (subscribed via `01_api-transport/sse.ts`) — but **`AnnotationsPage` does not subscribe today** (finding #10) |
|
||||
|
||||
## 5. Implementation Details
|
||||
|
||||
**State Management**: Page-local for the open annotation + selection; `useResizablePanel` for panel widths (not persisted — finding #11).
|
||||
|
||||
**Time-window math** (`CanvasEditor`, finding #6, post-cross-check correction): implementation is symmetric ±200 ms (400 ms total). Spec wants asymmetric 50 ms before + 150 ms after (200 ms total). UI is 4× too wide and not centred per spec.
|
||||
|
||||
**Gradient cap** (finding #9, post-cross-check correction): annotation row alpha gradient maxes at `0x28 = 16 %` opacity due to a `* 40` literal that is decimal, not hex. Wireframe demands `0x40 = 25 %`.
|
||||
|
||||
**`handleSave` body** (finding #32): currently `{ classNum, x, y, w, h, time }`. Suite spec requires `{ classNum, x, y, w, h, videoTime, Source, WaypointId }`. Owner: this component, also touches Foundation types.
|
||||
|
||||
**handleDownload (image export)** — risks tainting the `<canvas>` if the video is from a `blob:` URL with cross-origin frames; finding #12.
|
||||
|
||||
**Missing affordances** (findings #13–18):
|
||||
- Affiliation icons absent (spec mandates per-bbox).
|
||||
- Combat-readiness indicator absent.
|
||||
- `AFFILIATION_COLORS` defined but unused (dead).
|
||||
- No keyboard shortcuts R / V / PageUp / PageDown.
|
||||
- No camera-config side panel.
|
||||
- No tile zoom indicator for `splitTile` media.
|
||||
|
||||
**AI-detect controls** (`AnnotationsSidebar`, findings #21–23):
|
||||
- Async progress is not streamed (no SSE subscription).
|
||||
- Errors silently `console.error`'d, no UI feedback.
|
||||
|
||||
**MediaList** (findings #24–26):
|
||||
- Uses `alert()` for "no media" state.
|
||||
- `blob:` local previews ignore the search filter.
|
||||
- No virtualisation — long flights render all thumbnails.
|
||||
|
||||
**Cross-feature leak**: `07_dataset` imports `CanvasEditor` directly (caveat from `00_discovery.md` §8). The right home is a shared `components/canvas/` directory; not done in this step.
|
||||
|
||||
**Enum drift cross-link**: findings #27–34 capture the enum drift (`AnnotationStatus`, `Affiliation`, `CombatReadiness`, `MediaStatus`, `AnnotationSource`) — wire payloads using current `src/types/index.ts` values are wrong. Owner of fix: `00_foundation/types/index.ts`. Two findings (#31, #33) are **NO UI CHANGE — PARENT-DOC FIX** and have already been applied to the suite docs (state.json 02:18Z note); the rest are Step 4.
|
||||
|
||||
**Key Dependencies**: HTML5 `<canvas>` + `<video>`, `react-dropzone` (upload).
|
||||
|
||||
## 6b. WPF gap analysis (vs `suite/annotations-research`)
|
||||
|
||||
> Output of the Step 2 BLOCKING-gate cross-check (2026-05-10). The legacy WPF `Azaion.Annotator` window is the design source for this component; the file `_docs/legacy/wpf-era.md` §10 calls out which features must be ported. The list below is the delta — features that exist in the WPF source and are NOT yet present in the React port. Each entry names the WPF anchor and the React owner; numeric findings (#) come from `_docs/02_document/modules/src__features__annotations.md`.
|
||||
|
||||
| WPF feature | Anchor in `annotations-research` | React status | Owner |
|
||||
|------------|----------------------------------|--------------|-------|
|
||||
| **Time window asymmetric 50/150 ms** (interval-tree `_thresholdBefore=50ms`, `_thresholdAfter=150ms`) | `Azaion.Annotator/Annotator.xaml.cs:53-54` | Wrong (symmetric ±200 ms). Finding #6. | `CanvasEditor.tsx` |
|
||||
| **Keyboard shortcut `[Space]` = pause / resume** | `Annotator.xaml` `PauseClick` button tooltip "[Пробіл]" | Missing (no global key listener) | `VideoPlayer` + `AnnotationsPage` |
|
||||
| **Keyboard `[Left]` / `[Right]` = prev / next frame; `+Ctrl` = ±5 sec** | `PreviousFrameClick` / `NextFrameClick` tooltips | Missing | `VideoPlayer` |
|
||||
| **Keyboard `[Enter]` = save annotations and continue** | `SaveAnnotationsClick` tooltip "[Ентер]" | Missing. Finding #16 broadens this. | `AnnotationsPage` |
|
||||
| **Keyboard `[Del]` = delete selected annotations (with confirm)** | `Annotator.xaml.cs:204-222` (`DgAnnotations.KeyUp`) | Missing | `AnnotationsSidebar` + `ConfirmDialog` |
|
||||
| **Keyboard `[X]` = delete ALL annotations** | `RemoveAllClick` tooltip "[X]" | Missing | `AnnotationsPage` |
|
||||
| **Keyboard `[M]` = mute volume; also toggles GPS panel (context-sensitive)** | `TurnOffVolume` + `SwitchGpsPanel` tooltips both "[M]" | Missing | `VideoPlayer` |
|
||||
| **Keyboard `[R]` = AI Detect** | `AIDetectBtn_OnClick` tooltip "[R]" | Missing. Finding #16. | `AnnotationsSidebar` |
|
||||
| **Keyboard `[Ctrl+click]` = multi-select; `[Ctrl+drag]` = pan; `[Ctrl+wheel]` = zoom** | `Azaion.Common/Controls/CanvasEditor.cs` | Pan / zoom missing (finding listed); multi-select unverified | `CanvasEditor.tsx` |
|
||||
| **Volume slider** (`UpdatableProgressBar Volume`, range 0–100, mediator `VolumeChangedEvent`) | `Annotator.xaml:500-507` | Missing entirely | `VideoPlayer` |
|
||||
| **Status bar — clock `mm:ss / mm:ss`** | `Annotator.xaml.cs:237` `StatusClock.Text = ...` | Missing | `VideoPlayer` (display) + `AnnotationsPage` (slot) |
|
||||
| **Status bar — contextual help text** (`HelpTextEnum.{Initial, PlayVideo, PauseForAnnotations, AnnotationHelp}`, `BlinkHelp` flicker pattern) | `Azaion.Annotator/HelpTexts.cs` + `Annotator.xaml.cs:144-158` | Missing | `AnnotationsPage` (or a global toast) |
|
||||
| **Status bar — generic status text** (`StatusBarItem Status`) | `Annotator.xaml:653` | Missing | shared chrome (could live in App Shell or `AnnotationsPage`) |
|
||||
| **Sound Detections feature** ("Show objects detected by audio analysis", own button, distinct from AI Detect) | `Annotator.xaml:565-617` `SoundDetections` button + handler | **Entirely missing**. Not mentioned anywhere in `_docs/legacy/wpf-era.md §10` "What survived" — needs a user decision: port or drop. | TBD |
|
||||
| **Drone Maintenance feature** ("Аналіз стану БПЛА" — UAV state analysis, [K]) | `Annotator.xaml:618-630` `RunDroneMaintenance` button + handler | **Entirely missing**. Same status as above — port-or-drop decision required. | TBD |
|
||||
| **Resizable panel widths persisted** (left + right panels) | `Annotator.xaml.cs:243-252` `SaveUserSettings` writes `UIConfig.LeftPanelWidth` / `RightPanelWidth` | Missing — `useResizablePanel` does not persist (finding #11). | `00_foundation/useResizablePanel` + Settings backend |
|
||||
| **Camera config side panel** (altitude / focal / sensor → GSD) | `Annotator.xaml:196-203` `CameraConfigControl` | Missing (finding #17) | `AnnotationsPage` |
|
||||
| **Affiliation icons + Combat readiness indicator on bbox label** | `Azaion.Common/DTO/AffiliationEnum`, `_docs/ui_design/README.md` | Missing (findings #14–15) | `CanvasEditor.tsx` + types |
|
||||
| **Annotation list seek + zoom on double-click** | `Annotator.xaml.cs:197-202`, `OpenAnnotationResult` (seek + ZoomTo for split tiles) | Partial — seek probably works, "open split-tile zoom" not verified | `AnnotationsSidebar` |
|
||||
| **Help window "Як анотувати" (6 quality rules)** | `HelpWindow.xaml`, `_docs/legacy/wpf-era.md §10` "Help window" | `HelpModal` exists but GUIDELINES is a hardcoded string in source — not moved to i18n bundle. Step 4. | `03_shared-ui/HelpModal` |
|
||||
|
||||
### Decisions required at Step 4.5 (Architecture Vision)
|
||||
|
||||
- **Sound Detections** — port, drop, or move to a different module (e.g., a future audio-pipeline service)?
|
||||
- **Drone Maintenance** — same.
|
||||
- **Camera config** persistence — was per-`AppConfig` in WPF; in the React port should it be per-user-settings, per-flight, or per-detect-job?
|
||||
- **Status bar / help-text blinking** — keep the WPF "blink twice" UX, replace with toasts, or drop?
|
||||
|
||||
These are Architecture-Vision-level questions, not Step 2 component-graph decisions. Recorded here so Step 4.5 can pick them up.
|
||||
|
||||
## 7. Caveats & Edge Cases
|
||||
|
||||
- 26 findings in `src__features__annotations.md`. Cross-cutting blockers cluster on enum drift + `handleSave` body shape + missing `X-Refresh-Token`.
|
||||
- **Time-window** and **gradient** math wrong against spec.
|
||||
- **Video AI-detect not wired to SSE** — long-running jobs appear to hang from the user's POV.
|
||||
- **WPF gap analysis above** lists ~17 missing affordances. Highest user-impact: keyboard shortcuts, volume slider, status bar with clock + help text. Highest design-impact: Sound Detections + Drone Maintenance (both require a port-or-drop decision).
|
||||
|
||||
## 8. Dependency Graph
|
||||
|
||||
**Must be implemented after**: `00_foundation`, `01_api-transport`, `03_shared-ui`, `11_class-colors`.
|
||||
|
||||
**Can be implemented in parallel with**: every other feature page (note: `07_dataset` imports `CanvasEditor`, so a `CanvasEditor` extraction must coordinate).
|
||||
|
||||
**Blocks**: `07_dataset` (direct import dependency on `CanvasEditor`), `10_app-shell`.
|
||||
|
||||
## Module Inventory
|
||||
|
||||
Single consolidated module doc: `_docs/02_document/modules/src__features__annotations.md`. `classColors.ts` is moved into a separate component (`11_class-colors`) — its module doc is referenced from there, not here.
|
||||
@@ -0,0 +1,98 @@
|
||||
# 07 — Dataset Explorer
|
||||
|
||||
## 1. High-Level Overview
|
||||
|
||||
**Purpose**: Browse, filter, edit, split, and export the dataset. Reuses `CanvasEditor` from `06_annotations` for in-place bbox editing on dataset thumbnails.
|
||||
|
||||
**Architectural Pattern**: Single-page feature with one route component composing local panels.
|
||||
|
||||
**Upstream dependencies**: `00_foundation`, `01_api-transport`, `03_shared-ui` (FlightContext, ConfirmDialog, DetectionClasses), `06_annotations` (`CanvasEditor` — cross-feature edge).
|
||||
|
||||
**Downstream consumers**: `10_app-shell` (routed at `/dataset`).
|
||||
|
||||
## 2. Internal Interfaces
|
||||
|
||||
| Export | Notes |
|
||||
|--------|-------|
|
||||
| `DatasetPage()` | Top-level route component. Loads paged dataset items, applies filters (class, affiliation, status, flight), renders thumbnail grid + edit pane. |
|
||||
|
||||
## 3. External API Specification
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|--------|------|---------|
|
||||
| GET | `/api/annotations/dataset` | Paged list with filters |
|
||||
| GET | `/api/annotations/dataset/{id}` | Detail |
|
||||
| PUT | `/api/annotations/dataset/{id}` | Update (class, status, bbox) |
|
||||
| DELETE | `/api/annotations/dataset/{id}` | Delete |
|
||||
| POST | `/api/annotations/dataset/bulk-status` | Bulk status update (numeric per finding cross-check) |
|
||||
| POST | `/api/annotations/dataset/{id}/split` | Split tile |
|
||||
|
||||
## 5. Implementation Details
|
||||
|
||||
**State Management**: Page-local. Uses `useDebounce` for filter inputs and `useResizablePanel` for the editor pane.
|
||||
|
||||
**Findings** (13 numbered, from `src__features__dataset__DatasetPage.md`):
|
||||
|
||||
1. **No keyboard shortcuts** at all.
|
||||
2. **No "Refresh thumbnails"** action.
|
||||
3. **No virtualisation** — long lists render all thumbnails.
|
||||
4. **Editor tab does not save** — confirmed regression.
|
||||
5. **Magic `mediaType=1`** literal — should be the typed enum.
|
||||
6. **Dead `ConfirmDialog` import** — never used.
|
||||
7. **Silent `try/catch`** in delete handler.
|
||||
8. **Status filter conflates `None` with `All`** — depends on the `AnnotationStatus` enum drift fix (`00_foundation/types/index.ts`).
|
||||
9. **`classNum=0` sentinel collides with real class 0** — needs explicit "all classes" sentinel.
|
||||
10. **`mediaType=1` again** — appears twice.
|
||||
11. **Bulk-status request** uses string status names; spec wants numerics — already retagged for parent-doc fix (state.json 02:18Z note covered the spec side).
|
||||
12. **DatasetItem.isSplit** missing in the parent-doc response schema — cross-repo PARENT-DOC FIX applied.
|
||||
13. **Cross-feature `CanvasEditor` import** — finding #14 (cross-link to enum drift + isSplit gap).
|
||||
|
||||
**Key Dependencies**: `react-dropzone` (export trigger), `@hello-pangea/dnd` (potentially, for reordering — verify in Step 3).
|
||||
|
||||
## 6b. WPF gap analysis (vs `suite/annotations-research`)
|
||||
|
||||
> Cross-check of the legacy `Azaion.Dataset.DatasetExplorer` window (`Azaion.Dataset/DatasetExplorer.xaml`) against the current React `DatasetPage`. **Step 4 correction**: an earlier draft of this table claimed several WPF features were missing that are in fact already implemented. Re-read of `src/features/dataset/DatasetPage.tsx` corrected the table below.
|
||||
|
||||
| WPF feature | Anchor in `annotations-research` | React status | Owner |
|
||||
|------------|----------------------------------|--------------|-------|
|
||||
| **Class Distribution chart tab** (3rd tab — horizontal bars per `DetectionClass`, bar tinted with the class color) | `Azaion.Dataset/Controls/ClassDistribution.xaml` + `DatasetExplorer.xaml:146-148` | **Implemented** — `DatasetPage.tsx:151` has three tabs (`annotations`, `editor`, `distribution`); `loadDistribution()` calls `GET /api/annotations/dataset/class-distribution`. Step-4 verify the bar tint matches `classColors`. | — |
|
||||
| **"Show only annotations with objects" checkbox** in left filter pane | `DatasetExplorer.xaml:89-95` `ShowWithObjectsOnlyChBox` | **Implemented** — `DatasetPage.tsx:110-114`, state name `objectsOnly`. | — |
|
||||
| **Validate button (bulk-validate selected annotations to `AnnotationStatus.Validated`)** | `DatasetExplorer.xaml:177-200` `ValidateBtn` + `ValidateAnnotationsClick` | **Implemented** — `DatasetPage.tsx:142-146` Validate button appears when `selectedIds.size > 0`; `handleValidate()` posts to `/api/annotations/dataset/bulk-status`. **Gap is the `[V]` keyboard shortcut**, not the button. | `DatasetPage` (shortcut only) |
|
||||
| **Refresh thumbnails button + progress bar** | `DatasetExplorer.xaml:205-247` `RefreshThumbnailsButtonItem` + `RefreshProgressBarItem` | Button missing (finding #2); progress UI also missing | `DatasetPage` + an as-yet-undefined refresh service endpoint |
|
||||
| **`SelectedAnnotationName` status indicator** (bottom-right of status bar) | `DatasetExplorer.xaml:252-254` | Missing | `DatasetPage` |
|
||||
| **Generic `StatusText` slot** | `DatasetExplorer.xaml:249-251` | Missing | `DatasetPage` |
|
||||
| **Seed annotation highlight** (`IsSeed=true` thumbnails get an 8 px IndianRed border) | `DatasetExplorer.xaml:15-29` thumbnail template | Missing — `DatasetItem.isSeed` shape unverified against suite spec (cross-link to `00_foundation/types/index.ts`). | `DatasetPage` + types |
|
||||
| **Thumbnail caption** (image name + `CreatedDate: CreatedEmail`) | `DatasetExplorer.xaml:42-56` | Likely missing or simplified — verify in Step 4 against current React render. | `DatasetPage` |
|
||||
| **Keyboard shortcuts `[1]–[9]`, `[Enter]`, `[Del]`, `[X]`, `[V]`, arrows, PgUp/PgDn, `[Esc]`** for inline editor | `DatasetExplorer.xaml.cs` (listed in `_docs/legacy/wpf-era.md §5`) | Missing entirely (finding #1) | `DatasetPage` |
|
||||
| **Editor tab actually saves** | WPF wires `ExplorerEditor` → `AnnotationService.OnAnnotationCreated` etc. | **Broken in React** (finding #4 — Editor tab does not save). PRIORITY Step 4. | `DatasetPage` + `06_annotations/CanvasEditor` |
|
||||
| **`DetectionClasses` strip in left pane** (same control reused from Annotator) | `DatasetExplorer.xaml:85-88` | Present (via `03_shared-ui/DetectionClasses`) | — |
|
||||
| **Filter `TextBox`** | `DatasetExplorer.xaml:112-115` `TbSearch` with `TextChanged` debounce | Present (uses `00_foundation/useDebounce`) | — |
|
||||
| **Virtualised thumbnail grid** (`vwp:GridView` from `WpfToolkit.VirtualizingWrapPanel`) | `DatasetExplorer.xaml:126-135` | **Missing virtualisation** (finding #3) — long lists render all thumbnails. | `DatasetPage` |
|
||||
|
||||
### Decisions required at Step 4.5 (Architecture Vision)
|
||||
|
||||
- **Refresh-thumbnails action** — is the existing thumbnail refresh strategy (server-side on annotation save) acceptable, or do we need a manual "Refresh" affordance like the WPF era?
|
||||
- **Status-bar surfaces** (`StatusText`, `SelectedAnnotationName`) — port the WPF status bar verbatim, or rely on existing toasts and selection counters?
|
||||
- **Seed annotation concept** (`IsSeed=true` highlight) — does the modern API still expose `IsSeed`, and is the visual still desired?
|
||||
- **Inline editor save** — is the broken save (#4) a regression to fix or a feature to be redesigned?
|
||||
|
||||
## 7. Caveats & Edge Cases
|
||||
|
||||
- **Cross-feature import** of `CanvasEditor` (`06_annotations`). Either lift to a shared `components/canvas/` or accept the edge — record in module-layout / baseline scan.
|
||||
- **Editor tab broken** (#4) — PRIORITY Step 4.
|
||||
- **Filter sentinels colliding** (#8, #9) — wire-format consistency depends on enum drift fix.
|
||||
- **WPF gap analysis above** lists ~12 missing affordances. Highest user-impact: virtualisation, Refresh thumbnails, keyboard shortcuts, broken editor save. Highest design-impact: Class Distribution chart (entirely missing third tab).
|
||||
|
||||
## 8. Dependency Graph
|
||||
|
||||
**Must be implemented after**: `00_foundation`, `01_api-transport`, `03_shared-ui`, `06_annotations` (`CanvasEditor`).
|
||||
|
||||
**Can be implemented in parallel with**: `04_login`, `05_flights`, `08_admin`, `09_settings`.
|
||||
|
||||
**Blocks**: `10_app-shell` only.
|
||||
|
||||
## Module Inventory
|
||||
|
||||
| Path | Module Doc |
|
||||
|------|------------|
|
||||
| `src/features/dataset/DatasetPage.tsx` | `_docs/02_document/modules/src__features__dataset__DatasetPage.md` |
|
||||
@@ -0,0 +1,64 @@
|
||||
# 08 — Admin
|
||||
|
||||
## 1. High-Level Overview
|
||||
|
||||
**Purpose**: Operator-only configuration page. User management, detection-class management, AI Settings, GPS Settings, aircraft default.
|
||||
|
||||
**Architectural Pattern**: Single-page feature, large monolithic component (~215 lines pre-consolidation per state.json).
|
||||
|
||||
**Upstream dependencies**: `00_foundation`, `01_api-transport`, `03_shared-ui` (ConfirmDialog).
|
||||
|
||||
**Downstream consumers**: `10_app-shell` (routed at `/admin`, **currently with no role-based guard** — see #1 caveat below).
|
||||
|
||||
## 2. Internal Interfaces
|
||||
|
||||
| Export | Notes |
|
||||
|--------|-------|
|
||||
| `AdminPage()` | Top-level route component. Sub-sections: Users, Detection Classes, AI Settings, GPS Settings, Aircraft default. |
|
||||
|
||||
## 3. External API Specification
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|--------|------|---------|
|
||||
| GET / POST / PUT / DELETE | `/api/admin/users` | User CRUD |
|
||||
| GET | `/api/annotations/classes` | Read class list (note: read uses `annotations/`, write uses `admin/`) |
|
||||
| POST / PUT / DELETE | `/api/admin/classes` | Class CRUD |
|
||||
| GET / PUT | `/api/admin/settings/ai` | AI service config |
|
||||
| GET / PUT | `/api/admin/settings/gps` | GPS device config |
|
||||
| GET / PUT | `/api/admin/settings/aircraft-default` | Aircraft default |
|
||||
|
||||
## 5. Implementation Details
|
||||
|
||||
**State Management**: Page-local React state per sub-form. No global form library.
|
||||
|
||||
**Findings (B4, copied from state.json):**
|
||||
|
||||
1. **PRIORITY (security): no role-based route guard on `/admin`** — anyone authenticated can access. Server-enforced 403 protects the data, but UI does not gate. Surface in Step 6 problem-extraction. Cross-link with `10_app-shell`.
|
||||
2. **AI Settings & GPS Settings forms render with `defaultValue` only — NO state, NO submit handler, the Save button does nothing.** PRIORITY surface in Step 6.
|
||||
3. **Hardcoded GPS device default `'192.168.1.100'` / port `'5535'`** shipped in production bundle. Step 4.
|
||||
4. **`handleDeleteClass` has NO `ConfirmDialog`** despite being destructive. Step 4 vs `ui_design/README.md`.
|
||||
5. **Service split mismatch**: detection-class read uses `/api/annotations/classes` (annotations service) but write uses `/api/admin/classes` (admin service). Verify with suite ADRs in Step 3a.
|
||||
6. **`handleToggleDefault` duplicated** between AdminPage and SettingsPage; aircraft default is global config but page exists in both `/admin` and `/settings` — surface intent in Step 6.
|
||||
7. **Many hardcoded English strings.** Step 4 i18n.
|
||||
|
||||
**Key Dependencies**: `03_shared-ui/ConfirmDialog` (used for some destructive actions; missing on `handleDeleteClass`).
|
||||
|
||||
## 7. Caveats & Edge Cases
|
||||
|
||||
- The **broken Save button** is the most user-visible bug.
|
||||
- The **annotations/admin service split** for class CRUD looks like a copy-paste residue but may be deliberate; verify in Step 3a.
|
||||
- **No optimistic concurrency / version check** for any settings — last writer wins.
|
||||
|
||||
## 8. Dependency Graph
|
||||
|
||||
**Must be implemented after**: `00_foundation`, `01_api-transport`, `03_shared-ui`.
|
||||
|
||||
**Can be implemented in parallel with**: every other feature page.
|
||||
|
||||
**Blocks**: `10_app-shell`.
|
||||
|
||||
## Module Inventory
|
||||
|
||||
| Path | Module Doc |
|
||||
|------|------------|
|
||||
| `src/features/admin/AdminPage.tsx` | `_docs/02_document/modules/src__features__admin__AdminPage.md` |
|
||||
@@ -0,0 +1,60 @@
|
||||
# 09 — Settings
|
||||
|
||||
## 1. High-Level Overview
|
||||
|
||||
**Purpose**: User-scoped + system settings: language, theme, system params, directory paths, aircraft default (duplicated with Admin).
|
||||
|
||||
**Architectural Pattern**: Single-page feature, ~181 lines pre-consolidation.
|
||||
|
||||
**Upstream dependencies**: `00_foundation`, `01_api-transport`, `03_shared-ui`.
|
||||
|
||||
**Downstream consumers**: `10_app-shell` (routed at `/settings`).
|
||||
|
||||
## 2. Internal Interfaces
|
||||
|
||||
| Export | Notes |
|
||||
|--------|-------|
|
||||
| `SettingsPage()` | Top-level route component. Sub-sections: Personal (language, theme), System (params), Directories, Aircraft default. |
|
||||
|
||||
## 3. External API Specification
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|--------|------|---------|
|
||||
| GET / PUT | `/api/annotations/settings/user` | Per-user UI preferences |
|
||||
| GET / PUT | `/api/admin/settings/system` | System params (saveSystem) |
|
||||
| GET / PUT | `/api/admin/settings/directories` | Storage paths (saveDirs) |
|
||||
| GET / PUT | `/api/admin/settings/aircraft-default` | Aircraft default (duplicated with Admin) |
|
||||
|
||||
## 5. Implementation Details
|
||||
|
||||
**State Management**: Page-local React state per form section.
|
||||
|
||||
**Findings (B4, copied from state.json):**
|
||||
|
||||
1. **`saveSystem` / `saveDirs` lack `try/finally`** — PUT failure leaves `saving:true` permanently and the spinner never stops. Step 4.
|
||||
2. **Numeric inputs use `parseInt(v) || 0`** — clearing a field silently writes 0. Step 4.
|
||||
3. **No optimistic concurrency** (no version field, no ETag) — Step 6 problem-extraction.
|
||||
4. **`handleToggleDefault` duplicated with AdminPage** — same global config behind two different pages. Surface intent in Step 6.
|
||||
5. **Possibly should be guarded by a permission like `SETTINGS`** — spec doesn't have such a code; server-enforces via 403. Less clear-cut than the `/admin` gap. Surface in Step 6.
|
||||
|
||||
**Key Dependencies**: `react-i18next` (language switch).
|
||||
|
||||
## 7. Caveats & Edge Cases
|
||||
|
||||
- **Stuck-saving spinner** on PUT failure (#1).
|
||||
- **Silent zero on cleared numeric input** (#2) — corrupts settings.
|
||||
- **Aircraft default duplicated** with Admin — eventually one page should win.
|
||||
|
||||
## 8. Dependency Graph
|
||||
|
||||
**Must be implemented after**: `00_foundation`, `01_api-transport`, `03_shared-ui`.
|
||||
|
||||
**Can be implemented in parallel with**: every other feature page.
|
||||
|
||||
**Blocks**: `10_app-shell`.
|
||||
|
||||
## Module Inventory
|
||||
|
||||
| Path | Module Doc |
|
||||
|------|------------|
|
||||
| `src/features/settings/SettingsPage.tsx` | `_docs/02_document/modules/src__features__settings__SettingsPage.md` |
|
||||
@@ -0,0 +1,68 @@
|
||||
# 10 — App Shell
|
||||
|
||||
## 1. High-Level Overview
|
||||
|
||||
**Purpose**: Application bootstrap. `main.tsx` mounts React + StrictMode + BrowserRouter; `App.tsx` defines the top-level routing tree and provider stack.
|
||||
|
||||
**Architectural Pattern**: Composition root.
|
||||
|
||||
**Upstream dependencies**: every other component (this is the wiring root).
|
||||
|
||||
**Downstream consumers**: none (top of the tree).
|
||||
|
||||
## 2. Internal Interfaces
|
||||
|
||||
### `src/main.tsx`
|
||||
|
||||
- Imports `./i18n/i18n` for side-effect (`00_foundation`).
|
||||
- Imports `./index.css`.
|
||||
- Mounts `<StrictMode><BrowserRouter><App /></BrowserRouter></StrictMode>` into `#root`.
|
||||
|
||||
### `src/App.tsx`
|
||||
|
||||
Routes:
|
||||
|
||||
| Route | Wrapping | Component |
|
||||
|-------|----------|-----------|
|
||||
| `/login` | (public) | `04_login/LoginPage` |
|
||||
| `/flights` (default authenticated) | `AuthProvider → ProtectedRoute → FlightProvider → Header` | `05_flights/FlightsPage` |
|
||||
| `/annotations` | same | `06_annotations/AnnotationsPage` |
|
||||
| `/dataset` | same | `07_dataset/DatasetPage` |
|
||||
| `/admin` | same — **no role guard** | `08_admin/AdminPage` |
|
||||
| `/settings` | same | `09_settings/SettingsPage` |
|
||||
| `*` | same | redirect → `/flights` |
|
||||
|
||||
## 5. Implementation Details
|
||||
|
||||
**State Management**: provider stack only (`AuthProvider`, `FlightProvider`).
|
||||
|
||||
**Findings (5 items from `src__App-and-main.md`):**
|
||||
|
||||
1. **No role-based route guards** on `/admin` (PRIORITY — security). `/settings` is more nuanced (no `SETTINGS` permission code in spec; server-enforced via 403).
|
||||
2. **Mobile bottom-nav** route layout — confirmed present (Header.tsx:113–129). Earlier draft incorrectly listed this as missing; corrected per state.json 02:01Z.
|
||||
3. **No `ErrorBoundary`** — any uncaught render throw crashes the whole app to a white screen.
|
||||
4. **No lazy chunks / code-splitting** — every route is in the initial bundle. Compounds the `chart.js` bloat from `05_flights`.
|
||||
5. **`/flights` is the default landing for everyone** — user-specific landing per role would require `00_foundation` permission types + `02_auth.permissions`.
|
||||
|
||||
**Key Dependencies**: `react-router-dom` 7.
|
||||
|
||||
## 7. Caveats & Edge Cases
|
||||
|
||||
- **No `ErrorBoundary`** is the highest-impact gap; even one runtime null deref in any feature kills the app.
|
||||
- **`/admin` open to any authenticated user** at the UI level (PRIORITY).
|
||||
- **No lazy loading** — initial bundle is ~all of the SPA.
|
||||
|
||||
## 8. Dependency Graph
|
||||
|
||||
**Must be implemented after**: every other component (composition root).
|
||||
|
||||
**Can be implemented in parallel with**: nothing.
|
||||
|
||||
**Blocks**: nothing.
|
||||
|
||||
## Module Inventory
|
||||
|
||||
| Path | Module Doc |
|
||||
|------|------------|
|
||||
| `src/App.tsx` | `_docs/02_document/modules/src__App-and-main.md` |
|
||||
| `src/main.tsx` | `_docs/02_document/modules/src__App-and-main.md` |
|
||||
@@ -0,0 +1,85 @@
|
||||
# 11 — Class Colors (Detection Class Theme)
|
||||
|
||||
## 1. High-Level Overview
|
||||
|
||||
**Purpose**: The single source of fallback color, fallback name, and `PhotoMode` suffix for any detection class number — used whenever the live `DetectionClass[]` from the admin API is unavailable, partial, or being rendered next to UI chrome that cannot wait for it (initial paint, gradient stops, label tints, sidebar swatches).
|
||||
|
||||
**Architectural Pattern**: Pure-function shared kernel. Stateless, no React, no HTTP, no DOM.
|
||||
|
||||
**Layer**: shared / Layer 1 (above Foundation, below every UI component that names a detection class).
|
||||
|
||||
**Upstream dependencies**: none (no internal imports; no external libraries).
|
||||
|
||||
**Downstream consumers**:
|
||||
- `03_shared-ui/DetectionClasses` (fallback name + color when admin classes haven't loaded)
|
||||
- `06_annotations/CanvasEditor` (bbox label color + crosshair tint)
|
||||
- `06_annotations/AnnotationsPage` (active-class indicator)
|
||||
- `06_annotations/AnnotationsSidebar` (annotation-row gradient stops)
|
||||
- `07_dataset/DatasetPage` (class-filter chip color, class-distribution chart) — when those features are wired up
|
||||
|
||||
## 2. Internal Interfaces
|
||||
|
||||
```ts
|
||||
export const FALLBACK_CLASS_NAMES: string[]; // 12 generic English labels
|
||||
export function getClassColor(classNum: number): string; // hex string, no '#'-alpha
|
||||
export function getPhotoModeSuffix(classNum: number): string; // '' | ' (winter)' | ' (night)'
|
||||
export function getClassNameFallback(classNum: number): string; // FALLBACK_CLASS_NAMES[base] or '#<n>'
|
||||
```
|
||||
|
||||
A 12-color palette `CLASS_COLORS` is module-private and exposed only via `getClassColor`.
|
||||
|
||||
### PhotoMode contract (from legacy WPF)
|
||||
|
||||
`yoloId = classId + photoModeOffset`. Three offsets:
|
||||
|
||||
| `mode = floor(classNum / 20)` | Suffix | Meaning |
|
||||
|------------------------------|--------|---------|
|
||||
| 0 | (empty) | Regular |
|
||||
| 1 | `' (winter)'` | Winter |
|
||||
| 2 | `' (night)'` | Night |
|
||||
|
||||
`base = classNum % 20` is the index into both `CLASS_COLORS` and `FALLBACK_CLASS_NAMES`.
|
||||
|
||||
## 5. Implementation Details
|
||||
|
||||
```
|
||||
base = classNum % 20
|
||||
mode = floor(classNum / 20)
|
||||
color = CLASS_COLORS[base % CLASS_COLORS.length]
|
||||
name = FALLBACK_CLASS_NAMES[base % FALLBACK_CLASS_NAMES.length] ?? `#${classNum}`
|
||||
suffix = mode === 1 ? ' (winter)' : mode === 2 ? ' (night)' : ''
|
||||
```
|
||||
|
||||
**Open question** (carried forward from `src__features__annotations__classColors.md`): the `??` guard is dead because `base % length` already brings the index back into range. Either the array is wrong (the legacy palette had >12 entries?) or the guard is dead code. Step 4 verification.
|
||||
|
||||
**Redundancy with `DetectionClass.photoMode`** (also in module doc): the live admin DTO carries an explicit `photoMode` field on `DetectionClass`. Computing the suffix from `classNum / 20` here risks disagreeing with the admin-defined value. Step 4 testability candidate: keep `getPhotoModeSuffix` only as a fallback when the admin DTO is missing.
|
||||
|
||||
**State Management**: stateless module. Calls are pure.
|
||||
|
||||
**Key Dependencies**: none.
|
||||
|
||||
## 6. Extensions and Helpers
|
||||
|
||||
This *is* the helper. There are no further extensions inside this component.
|
||||
|
||||
## 7. Caveats & Edge Cases
|
||||
|
||||
- **Physical location is misplaced today**. The file lives at `src/features/annotations/classColors.ts` — inside the Annotations feature folder — even though logically it belongs to a feature-neutral shared layer. The cross-layer import from `src/components/DetectionClasses.tsx` to this file (recorded in `00_discovery.md` §8) is the visible symptom.
|
||||
- **Owner of fix**: `module-layout.md` (autodev Step 2.5) records the *target* layer; the actual file move is an autodev Step 4 (testability) candidate or a Step 8 refactor task. Until moved, both `03_shared-ui` and `06_annotations` import from the current path.
|
||||
- **Fallback names are generic English** ("Car", "Person", "Truck", …) and bear no relation to the actual military class taxonomy in `_docs/ui_design/README.md` §"Detection Classes Table". Acceptable only because they appear strictly when admin-loaded classes failed to load. Document in Step 5 (Solution Extraction).
|
||||
- **No localization**. Suffix strings (`' (winter)'`, `' (night)'`) and fallback names are hardcoded English. Step 4 i18n.
|
||||
- **Color palette size (12)** vs `base = 0..19` — the wrap-around silently reuses colors for indices 12..19. Visually distinct fallbacks above 12 are not guaranteed.
|
||||
|
||||
## 8. Dependency Graph
|
||||
|
||||
**Must be implemented after**: nothing (no internal deps).
|
||||
|
||||
**Can be implemented in parallel with**: `00_foundation`, `01_api-transport`.
|
||||
|
||||
**Blocks**: `03_shared-ui` (DetectionClasses), `06_annotations`, `07_dataset` (when class-distribution chart is added).
|
||||
|
||||
## Module Inventory
|
||||
|
||||
| Path | Module Doc |
|
||||
|------|------------|
|
||||
| `src/features/annotations/classColors.ts` *(physical location pending refactor)* | `_docs/02_document/modules/src__features__annotations__classColors.md` |
|
||||
@@ -0,0 +1,166 @@
|
||||
# Azaion UI — Data Model
|
||||
|
||||
> Synthesis output of `/document` Step 3c. Consolidated from `src/types/index.ts`,
|
||||
> per-component data sections, and the parent suite spec at
|
||||
> `_docs/legacy/wpf-era.md` §8 + the suite-level docs (cross-referenced).
|
||||
>
|
||||
> The UI does NOT own a database. The entities below are the **contract shapes**
|
||||
> the UI consumes from suite REST + SSE endpoints. The authoritative schema is
|
||||
> server-side; this document captures the **client-side type expectations** and
|
||||
> the **mismatches** between those expectations and the suite spec (enum drift,
|
||||
> shape drift) for resolution at autodev Step 4.
|
||||
|
||||
## 1. Entities by component
|
||||
|
||||
| Entity | Component | Backing service | Wire shape |
|
||||
|--------|-----------|-----------------|------------|
|
||||
| `AuthUser` | `02_auth` | `admin/` | `{id, email, name, role, permissions[]}` |
|
||||
| `User` | `08_admin` | `admin/` | `{id, name, email, role, isActive}` |
|
||||
| `Aircraft` | `08_admin` / `09_settings` | `admin/` | `{id, model, type:'Plane'\|'Copter', isDefault}` |
|
||||
| `Flight` | `05_flights` | `flights/` | `{id, name, createdDate, aircraftId\|null}` |
|
||||
| `Waypoint` | `05_flights` | `flights/` | UI sends: `{id, flightId, name, latitude, longitude, order}`. Spec wants: `{Geopoint:{Lat,Lon,MGRS}, Source, Objective, OrderNum, Height}` — **drift, finding #20** |
|
||||
| `Media` | `06_annotations` | `annotations/` | `{id, name, path, mediaType, mediaStatus, duration, annotationCount, waypointId, userId}` |
|
||||
| `AnnotationListItem` | `06_annotations` | `annotations/` | `{id, mediaId, time, createdDate, userId, source, status, isSplit, splitTile, detections[]}` |
|
||||
| `Detection` | `06_annotations` | `annotations/` (storage) + `detect/` (production) | `{id, classNum, label, confidence, affiliation, combatReadiness, centerX, centerY, width, height}` |
|
||||
| `DetectionClass` | `08_admin` (write) + `06_annotations` (read) | `admin/` (write) + `annotations/` (read) | `{id, name, shortName, color, maxSizeM, photoMode}` |
|
||||
| `DatasetItem` | `07_dataset` | `annotations/` | `{annotationId, imageName, thumbnailPath, status, createdDate, createdEmail, flightName, source, isSeed, isSplit}` |
|
||||
| `ClassDistributionItem` | (currently unused — backs missing chart) | `annotations/` | `{classNum, label, color, count}` |
|
||||
| `SystemSettings` | `09_settings` | `admin/` | `{id, name, militaryUnit, defaultCameraWidth, defaultCameraFoV, thumbnailWidth, thumbnailHeight, thumbnailBorder, generateAnnotatedImage, silentDetection}` |
|
||||
| `DirectorySettings` | `09_settings` | `admin/` | `{id, videosDir, imagesDir, labelsDir, resultsDir, thumbnailsDir, gpsSatDir, gpsRouteDir}` |
|
||||
| `CameraSettings` | `09_settings` | `admin/` | `{id, altitude, focalLength, sensorWidth}` |
|
||||
| `UserSettings` | `09_settings` | `admin/` | `{id, userId, selectedFlightId, annotationsLeftPanelWidth, annotationsRightPanelWidth, datasetLeftPanelWidth, datasetRightPanelWidth}` |
|
||||
| `PaginatedResponse<T>` | shared (`00_foundation`) | every list endpoint | `{items[], totalCount, page, pageSize}` |
|
||||
|
||||
## 2. Enums (numeric wire format)
|
||||
|
||||
> The suite uses **numeric** wire values for every enum. The UI types in `src/types/index.ts`
|
||||
> match in *shape* but several have **wrong values** vs. spec. The state-of-the-world is captured
|
||||
> in `state.json::notes[]` (2026-05-10 02:13Z entries) — Step 4 will fix the UI side.
|
||||
|
||||
| Enum | UI values today | Spec values | Status |
|
||||
|------|-----------------|-------------|--------|
|
||||
| `MediaType` | `None=0, Image=1, Video=2` | matches | ✓ |
|
||||
| `MediaStatus` | `New=0, AiProcessing=1, AiProcessed=2, ManualCreated=3` | also has `None`, `Confirmed`, `Error` | **drift** — UI cannot render error state. Step 4 fix. |
|
||||
| `AnnotationSource` | `AI=0, Manual=1` | matches numerically; spec doc shows strings (cross-repo doc fix replayed 2026-05-10) | ✓ (after parent-doc fix) |
|
||||
| `AnnotationStatus` | `Created=0, Edited=1, Validated=2` | spec is `None=0, Created=10, Edited=20, Validated=30, Deleted=40` | **drift, severe** — wire payloads will be wrong. Step 4 PRIORITY. |
|
||||
| `Affiliation` | `Unknown=0, Friendly=1, Hostile=2` | spec also has `None` | **drift** — Step 4. |
|
||||
| `CombatReadiness` | `NotReady=0, Ready=1` | spec also has `Unknown` | **drift** — Step 4. |
|
||||
|
||||
## 3. Entity-relationship diagram
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
User ||--o{ Flight : "creates"
|
||||
Flight ||--o{ Waypoint : "has"
|
||||
Flight ||--o{ Media : "captures"
|
||||
Media ||--o{ AnnotationListItem : "annotated by"
|
||||
AnnotationListItem ||--o{ Detection : "contains"
|
||||
DetectionClass ||--o{ Detection : "classifies (by classNum)"
|
||||
Aircraft }o--o| Flight : "default for"
|
||||
User ||--|| AuthUser : "session view of"
|
||||
User ||--|| UserSettings : "preferences"
|
||||
User ||--o{ DatasetItem : "validated by"
|
||||
SystemSettings ||--|| Aircraft : "may default to"
|
||||
|
||||
Detection {
|
||||
string id
|
||||
int classNum "raw int including PhotoMode offset"
|
||||
string label
|
||||
float confidence
|
||||
Affiliation affiliation
|
||||
CombatReadiness combatReadiness
|
||||
float centerX "normalized 0..1"
|
||||
float centerY "normalized 0..1"
|
||||
float width "normalized 0..1"
|
||||
float height "normalized 0..1"
|
||||
}
|
||||
|
||||
DetectionClass {
|
||||
int id
|
||||
string name
|
||||
string shortName
|
||||
string color "hex"
|
||||
float maxSizeM "GSD constraint"
|
||||
int photoMode "0=Regular, 1=Winter (+20), 2=Night (+40)"
|
||||
}
|
||||
|
||||
Waypoint {
|
||||
string id
|
||||
string flightId
|
||||
string name
|
||||
float latitude "wire shape: drift — see finding 20"
|
||||
float longitude
|
||||
int order
|
||||
}
|
||||
|
||||
AnnotationListItem {
|
||||
string id
|
||||
string mediaId
|
||||
string time "video timestamp HH:MM:SS or null"
|
||||
string createdDate "ISO 8601"
|
||||
string userId
|
||||
AnnotationSource source
|
||||
AnnotationStatus status
|
||||
bool isSplit
|
||||
string splitTile "YOLO label string or null"
|
||||
}
|
||||
|
||||
Media {
|
||||
string id
|
||||
string name
|
||||
string path
|
||||
MediaType mediaType
|
||||
MediaStatus mediaStatus
|
||||
string duration "HH:MM:SS or null"
|
||||
int annotationCount
|
||||
string waypointId
|
||||
string userId
|
||||
}
|
||||
|
||||
DatasetItem {
|
||||
string annotationId
|
||||
string imageName
|
||||
string thumbnailPath
|
||||
AnnotationStatus status
|
||||
string createdDate
|
||||
string createdEmail
|
||||
string flightName
|
||||
AnnotationSource source
|
||||
bool isSeed
|
||||
bool isSplit
|
||||
}
|
||||
```
|
||||
|
||||
## 4. Migration / schema-evolution strategy
|
||||
|
||||
The UI does NOT own a database, so there is no client-side migration to run. However:
|
||||
|
||||
- **Enum drift** above is effectively a "client-side schema migration" — every drifted enum must be aligned with the suite spec in Step 4 (or in the case of `AnnotationSource`, the parent-suite doc is what's wrong and was already fixed via cross-repo doc patch on 2026-05-10).
|
||||
- **Backwards compatibility** is the suite's responsibility. The UI assumes the latest contract; if the suite needs to roll out a breaking change, it must coordinate with the UI version (typically by gating the change behind a feature flag in the admin service, then deploying both at once).
|
||||
- **`UserSettings.{annotationsLeftPanelWidth, ...}`** — the type exists; the wire endpoint exists; the UI does not write these today (`useResizablePanel` finding #11). The fix is purely client-side wiring.
|
||||
|
||||
## 5. Seed data observations
|
||||
|
||||
The UI has no seed data of its own. Two sources of "default" data are observable:
|
||||
|
||||
1. **`FALLBACK_CLASS_NAMES`** (`11_class-colors`) — 12 generic English labels (Car, Person, Truck, …) shown only when admin classes failed to load. These are NOT a seed for the admin service; they are a defensive UI fallback only.
|
||||
2. **`Constants.DefaultAnnotationClasses`** in the legacy WPF — referenced in `_docs/legacy/wpf-era.md §10`. The React UI does NOT carry an equivalent (admin classes are always fetched). Acceptable.
|
||||
|
||||
## 6. Validation rules (client-side)
|
||||
|
||||
| Field | Rule | Source | Defect |
|
||||
|-------|------|--------|--------|
|
||||
| Login email | non-empty | `LoginPage` | none observed |
|
||||
| Login password | non-empty | `LoginPage` | none observed |
|
||||
| Numeric settings | `parseInt(v) \|\| 0` | `SettingsPage` | clearing field silently writes 0 — finding B4 |
|
||||
| Waypoint lat/lng | implicit (Leaflet bounds) | `FlightsPage` | no explicit clamp — Step 4 |
|
||||
| Detection bbox normalized 0..1 | implicit (CanvasEditor scaling) | `CanvasEditor` | normalized-coordinate clamping mentioned in `_docs/legacy/wpf-era.md §10` — verify in Step 4 |
|
||||
| Class 1–9 keyboard pick | `classes[idx + photoMode]` | `DetectionClasses` | ordering vs admin contract unverified — Step 4 |
|
||||
| File upload size | server cap 500 MB (nginx) | `nginx.conf` | client does not pre-validate — Step 4 cosmetic |
|
||||
|
||||
## 7. Wire-format gotchas
|
||||
|
||||
- **`time` as a string** in `AnnotationListItem` (e.g., `"00:01:23.456"`) is parsed/formatted client-side; precision is millisecond. Used for video annotation overlay window math (50 ms before / 150 ms after — currently wrong, finding #6).
|
||||
- **`splitTile` as a YOLO label string** is the raw `<class> <cx> <cy> <w> <h>` text, parsed client-side in `CanvasEditor.tsx`. Format mismatch is a Step 4 verification candidate.
|
||||
- **`PaginatedResponse<T>` ceiling** — `pageSize=1000` is hardcoded for flights (finding B3). Other lists vary; no canonical default.
|
||||
- **Date strings** — assumed ISO 8601; no timezone handling beyond what the browser's `Date` constructor implies. Step 4 verification when timezone bugs surface.
|
||||
@@ -0,0 +1,56 @@
|
||||
# Azaion UI — CI/CD Pipeline
|
||||
|
||||
> Synthesis output of `/document` Step 3d (ci_cd_pipeline). Derived from
|
||||
> `.woodpecker/build-arm.yml`.
|
||||
|
||||
## 1. Triggers
|
||||
|
||||
| Branch | Triggers | Image tag |
|
||||
|--------|----------|-----------|
|
||||
| `dev` | every push | `${REGISTRY_HOST}/azaion/ui:dev-arm` |
|
||||
| `stage` | every push | `${REGISTRY_HOST}/azaion/ui:stage-arm` |
|
||||
| `main` | every push | `${REGISTRY_HOST}/azaion/ui:main-arm` |
|
||||
|
||||
Other branches do NOT build (PR builds, feature-branch builds, tag builds — none configured today).
|
||||
|
||||
## 2. Steps
|
||||
|
||||
| # | Step | What | Notes |
|
||||
|---|------|------|-------|
|
||||
| 1 | Checkout | `git clone` + `git checkout $CI_COMMIT_SHA` | Standard Woodpecker behaviour |
|
||||
| 2 | Build + Push image | Multi-stage Dockerfile produces `nginx:alpine` image with `dist/` baked in | Pushes to `${REGISTRY_HOST}/azaion/ui:${branch}-arm` with OCI labels (revision, created, source) |
|
||||
|
||||
**Missing steps** (recommended for autodev Steps 5–7):
|
||||
|
||||
| Step | Purpose | Tool candidates |
|
||||
|------|---------|-----------------|
|
||||
| `bun install --frozen-lockfile` smoke | Catch lockfile drift before build | First few seconds of the build stage cover this |
|
||||
| `tsc --noEmit` | Type-check the whole project | Already part of `bun run build` (`tsc -b && vite build`) |
|
||||
| `bun test` (or vitest / jest) | Run test suite | **Required** — there is no test runner today |
|
||||
| `eslint` / `biome` | Lint | Not configured today |
|
||||
| Vulnerability scan | CVE scan on the image | `trivy` or `grype` candidates |
|
||||
| SBOM emission | Software bill of materials | `syft` candidate |
|
||||
| Image signing | Supply-chain trust | `cosign` candidate |
|
||||
| Multi-arch build | Add AMD64 alongside ARM64 | `docker buildx` candidates |
|
||||
|
||||
These are tracked as Step 4–7 deliverables under autodev; the current pipeline is correct but minimal.
|
||||
|
||||
## 3. Secrets & registry
|
||||
|
||||
- `${REGISTRY_HOST}` — provided by Woodpecker secrets at runtime.
|
||||
- Registry credentials — stored as Woodpecker secrets; not in this repo.
|
||||
- No GPG/TLS signing keys today.
|
||||
|
||||
## 4. Branch model
|
||||
|
||||
- `dev` is the active development branch (per `.cursor/rules/git-workflow.mdc`).
|
||||
- `stage` is for pre-production validation.
|
||||
- `main` is production.
|
||||
- No `release/*` long-lived branches.
|
||||
- PR builds are not configured (Woodpecker build only fires on push, not on PR open).
|
||||
|
||||
## 5. Build artifact
|
||||
|
||||
The output of the pipeline is exactly one OCI image per push: `${REGISTRY_HOST}/azaion/ui:${branch}-arm`. There is **no** versioned image tag (e.g., `1.2.3-arm`); branch tags are mutable. The OCI `revision` label is the deterministic anchor (= `$CI_COMMIT_SHA`).
|
||||
|
||||
**Future**: when this UI ships under a versioned suite release, the pipeline should also tag images with `vMAJOR.MINOR.PATCH-arm` derived from `package.json` `version`.
|
||||
@@ -0,0 +1,72 @@
|
||||
# Azaion UI — Containerization
|
||||
|
||||
> Synthesis output of `/document` Step 3d (containerization). Derived from
|
||||
> `Dockerfile`, `nginx.conf`, and `00_discovery.md` §3.
|
||||
|
||||
## 1. Image
|
||||
|
||||
**Multi-stage build** (`Dockerfile`):
|
||||
|
||||
| Stage | Base image | Role |
|
||||
|-------|------------|------|
|
||||
| 1 (builder) | `oven/bun:1.3.11-alpine` | `bun install --frozen-lockfile` + `bun run build` (= `tsc -b && vite build`) → `dist/` |
|
||||
| 2 (runtime) | `nginx:alpine` | Serves `/usr/share/nginx/html` (`dist/`); listens on `:80` |
|
||||
|
||||
**Why this shape**:
|
||||
- Bun gives a fast install + build vs. npm/yarn/pnpm.
|
||||
- nginx alpine is a sub-25 MB runtime that already has reverse-proxy routing for `/api`.
|
||||
- No Node runtime in production → smaller attack surface, faster startup, lower memory.
|
||||
|
||||
**Image labels** (OCI, set by Woodpecker CI):
|
||||
- `org.opencontainers.image.revision = $CI_COMMIT_SHA`
|
||||
- `org.opencontainers.image.created = $CI_BUILD_CREATED`
|
||||
- `org.opencontainers.image.source = <repo url>`
|
||||
|
||||
**Environment**:
|
||||
- `AZAION_REVISION = $CI_COMMIT_SHA` — accessible at runtime for diagnostics.
|
||||
- No other env vars consumed at runtime by the SPA bundle (the bundle is fully static).
|
||||
|
||||
## 2. nginx routing (`nginx.conf`)
|
||||
|
||||
The image's nginx config strips `/api/<service>/` and reverse-proxies to the matching suite service inside the container network.
|
||||
|
||||
| Public path | Upstream (intra-cluster) | Service |
|
||||
|-------------|--------------------------|---------|
|
||||
| `/api/annotations/` | `http://annotations:8080/` | `annotations/` |
|
||||
| `/api/flights/` | `http://flights:8080/` | `flights/` |
|
||||
| `/api/admin/` | `http://admin:8080/` | `admin/` |
|
||||
| `/api/resource/` | `http://resource:8080/` | `resource/` |
|
||||
| `/api/detect/` | `http://detect:8080/` | `detect/` |
|
||||
| `/api/loader/` | `http://loader:8080/` | `loader/` |
|
||||
| `/api/gps-denied-desktop/` | `http://gps-denied-desktop:8080/` | `gps-denied-desktop/` |
|
||||
| `/api/gps-denied-onboard/` | `http://gps-denied-onboard:8080/` | `gps-denied-onboard/` |
|
||||
| `/api/autopilot/` | `http://autopilot:8080/` | `autopilot/` |
|
||||
| `/` (any other path) | static fallback to `/index.html` (SPA routing) | — |
|
||||
|
||||
**Body size cap**: `client_max_body_size 500M` — tlog + video uploads in GPS-Denied Test Mode and large image uploads in Annotations both ride this limit.
|
||||
|
||||
**Headers passed to upstream**: standard `Host`, `X-Real-IP`, `X-Forwarded-For`, `X-Forwarded-Proto` (assumed — verify in `nginx.conf`).
|
||||
|
||||
**SSE handling**: `proxy_buffering off` MUST be set on `/api/detect/` and any other path that streams (Step 4 verification — confirm in `nginx.conf`).
|
||||
|
||||
## 3. Resource sizing (recommended, not enforced)
|
||||
|
||||
| Resource | Recommendation | Rationale |
|
||||
|----------|----------------|-----------|
|
||||
| CPU | 100 m (0.1 vCPU) | nginx is near-idle; 99 % of work is suite services |
|
||||
| Memory | 32 Mi | nginx + ~5 MB of static assets |
|
||||
| Storage | ephemeral 50 Mi | bundle is sub-5 MB gzipped today; some headroom |
|
||||
| Replicas | 1+ | trivially horizontal; HA only matters if the ingress sits in front |
|
||||
|
||||
**Bundle size budget**: `vite build` output should stay under ~2 MB gzipped initial JS. Currently `chart.js` and `leaflet` are the dominant chunks; `AltitudeChart` is a lazy-load candidate (finding in `05_flights`).
|
||||
|
||||
## 4. Health checks
|
||||
|
||||
**Today: none.**
|
||||
|
||||
Recommended (Step 4 / Step 6 surface):
|
||||
- **Liveness**: `GET /index.html → 200`
|
||||
- **Readiness**: same (the SPA has no warm-up)
|
||||
- **Container health**: `wget --spider -q http://localhost/index.html`
|
||||
|
||||
The suite-level orchestrator (parent suite docker-compose / k8s) is expected to handle ingress health-checking; individual UI replicas don't need their own.
|
||||
@@ -0,0 +1,51 @@
|
||||
# Azaion UI — Environment Strategy
|
||||
|
||||
> Synthesis output of `/document` Step 3d (environment_strategy). Derived from
|
||||
> `vite.config.ts`, `nginx.conf`, `.gitignore`, the workspace `README.md`, and
|
||||
> the absence of a workspace `.env.example`.
|
||||
|
||||
## 1. Environments
|
||||
|
||||
| Env | How it runs | API base | Auth | Tile providers |
|
||||
|-----|-------------|----------|------|----------------|
|
||||
| Development | `bun run dev` (Vite dev server, port 5173) | Vite dev proxy: `/api → http://localhost:8080` (configured in `vite.config.ts`) | Suite admin/ service running locally (typically via parent suite `docker-compose up`) | OSM + satellite (env-configurable in mission-planner only) |
|
||||
| Stage | nginx in container, ARM image `:stage-arm` | nginx `/api/<service>/ → http://<service>:8080/` (intra-cluster) | Stage suite admin/ service | Same |
|
||||
| Production | nginx in container, ARM image `:main-arm` | nginx `/api/<service>/ → http://<service>:8080/` | Prod suite admin/ service | Same |
|
||||
|
||||
## 2. Configuration model
|
||||
|
||||
The SPA bundle is **fully static**. No env vars are read at runtime by the bundle. Every cross-environment difference is resolved at the **deployment edge** (nginx) or at the **suite-service level**.
|
||||
|
||||
| Concern | Where it's set | Notes |
|
||||
|---------|----------------|-------|
|
||||
| Backend API URL | nginx `proxy_pass` (`nginx.conf`) — same nginx config across stage / prod | Base URLs are intra-cluster service names (`http://annotations:8080`, etc.); the URL difference between environments is hidden by the orchestrator's DNS |
|
||||
| Auth cookie domain | Set by suite admin/ service on `Set-Cookie` | UI does not control |
|
||||
| Refresh-token lifetime | Set by suite admin/ service | UI tolerates any TTL |
|
||||
| Tile provider URL (mission-planner) | `.env.example` declares `VITE_SATELLITE_TILE_URL` | mission-planner only; not deployed |
|
||||
| OpenWeatherMap API key | **Hardcoded in source** (`flightPlanUtils.ts:60`) | Security finding — Step 4 fix to remove + proxy via suite |
|
||||
| `AZAION_REVISION` | Stamped into image at build time | For diagnostics |
|
||||
|
||||
## 3. Why no `.env`
|
||||
|
||||
The workspace `.env.example` is **absent** today. The `README.md` "Local development" section explicitly notes this as a Step 4 testability fix.
|
||||
|
||||
**Trade-off**: avoiding a build-time env injection means `dist/` is identical across environments, which is great for promotability (the same image flows dev → stage → prod). The cost: the OpenWeatherMap key (and any future runtime config) cannot be changed without a rebuild.
|
||||
|
||||
**Future direction** (Step 4 / Step 5):
|
||||
- Move the OpenWeatherMap call server-side (`flights/` service) — eliminates the bundled key entirely.
|
||||
- Introduce a runtime `/config.json` that nginx serves — lets ops change feature flags / tile URLs without rebuilding.
|
||||
- OR keep the static bundle and use Vite's `define` for build-time injection of safe-to-publish values (no secrets).
|
||||
|
||||
## 4. Promotability
|
||||
|
||||
The same image (`:dev-arm`, `:stage-arm`, `:main-arm`) is built per branch from the same Dockerfile. Theoretically the `:dev-arm` image is functionally identical to the `:main-arm` image except for the `AZAION_REVISION` label.
|
||||
|
||||
In practice: branch separation is the gating mechanism. Once dev → stage → main propagation is normalized, the safer pattern is to build ONE image per commit and re-tag it across environments (immutable image promotion). The Woodpecker pipeline does not implement this today; it rebuilds per-branch.
|
||||
|
||||
## 5. Local-dev quirks
|
||||
|
||||
- **Vite dev proxy** (`vite.config.ts`) requires the suite to be reachable on `http://localhost:8080`. If the parent suite's docker-compose binds to a different port, the developer must edit `vite.config.ts` (no env-driven override today).
|
||||
- **`bun.lock`**: committed (per `package.json`'s `packageManager` field). `package-lock.json` is gitignored.
|
||||
- **`.idea/`, `.claude/`, `.superpowers/`**: gitignored — IDE / agent metadata.
|
||||
- **Playwright entries in `.gitignore`**: present but aspirational — Playwright is not installed (Step 5–7 territory).
|
||||
- **mission-planner**: has its own `.env.example` declaring `VITE_SATELLITE_TILE_URL` and runs as a sibling Vite app. Not bundled into the deployed image.
|
||||
@@ -0,0 +1,64 @@
|
||||
# Azaion UI — Observability
|
||||
|
||||
> Synthesis output of `/document` Step 3d (observability). Derived from inspection
|
||||
> of all module docs + `nginx.conf` + the absence of any client telemetry SDK
|
||||
> in `package.json`.
|
||||
|
||||
## 1. Status: minimal
|
||||
|
||||
The browser-side SPA emits **no centralized telemetry today**:
|
||||
|
||||
- No analytics SDK (no `@sentry/*`, `@datadog/*`, `web-vitals`, `posthog`, etc.).
|
||||
- No error reporting service.
|
||||
- No client-side feature-flag service.
|
||||
- Errors that aren't caught by an `<ErrorBoundary>` (which doesn't exist today — finding in `10_app-shell`) end up as `console.error` only.
|
||||
|
||||
This is acceptable as a starting state. A future iteration adds an error-tracking SDK (Sentry candidate) with the SDK key sourced from a runtime `/config.json` — see `environment_strategy.md`.
|
||||
|
||||
## 2. Existing logging (per module)
|
||||
|
||||
| Module | What is logged | How | Why it's unsatisfactory |
|
||||
|--------|----------------|-----|-------------------------|
|
||||
| `01_api-transport/client.ts` | request / response errors | `console.error` | No retries, no spans, no correlation IDs |
|
||||
| `01_api-transport/sse.ts` | EventSource errors | `console.error` | No reconnect logic; no telemetry |
|
||||
| `02_auth/AuthContext.tsx` | login / refresh outcomes | `console.error` | Successful refresh is silent (good); failures are silent (bad — need user-visible recovery flow) |
|
||||
| `03_shared-ui/FlightContext.tsx` | flight load + select-flight errors | swallowed | `selectFlight` is fire-and-forget, error invisible |
|
||||
| `06_annotations/AnnotationsSidebar.tsx` | AI-detect errors | `console.error` | User sees no feedback (finding #21–23) |
|
||||
| `06_annotations/AnnotationsPage.tsx` | save errors | partial — `handleSave` has fallback that **hides save loss** (finding) | Worst case: user thinks the annotation saved but it didn't |
|
||||
| `07_dataset/DatasetPage.tsx` | various | swallowed `catch` blocks (finding #6) | Same risk |
|
||||
| `05_flights/FlightsPage.tsx` | save partial-failure | not detected | Per-waypoint failures invisible (finding #19) |
|
||||
| `05_flights/flightPlanUtils.ts` | weather fetch errors | swallowed silently | Wind data missing → battery estimate wrong; user not informed |
|
||||
|
||||
The dominant pattern is "silent catch + console.error" — this is the single biggest observability gap.
|
||||
|
||||
## 3. Server-side logs the UI relies on
|
||||
|
||||
The suite services (admin, flights, annotations, detect, etc.) are responsible for:
|
||||
|
||||
- Audit logging (login, logout, role changes, destructive admin actions)
|
||||
- Request tracing (the UI does not send a `traceparent` header today — Step 6 candidate)
|
||||
- Performance metrics (UI does not measure RUM)
|
||||
|
||||
The UI's bug-reproduction story relies on suite-side logs. A correlation ID injected by the UI on every request would dramatically simplify cross-service debugging — a Step 6 problem-extraction surface.
|
||||
|
||||
## 4. Client-side metrics (none)
|
||||
|
||||
No `web-vitals` or equivalent is installed. Recommended (Step 5 solution surface):
|
||||
|
||||
- **CLS** (cumulative layout shift) — the canvas + leaflet + chart layout has known shifts on initial load.
|
||||
- **LCP** (largest contentful paint) — the bundle is the dominant cost.
|
||||
- **FID / INP** (interaction latency) — relevant for the canvas drag and waypoint drag-drop.
|
||||
- **Custom metrics**: time-to-first-flight-list, time-to-first-thumbnail, time-to-first-detection.
|
||||
|
||||
## 5. Error boundaries
|
||||
|
||||
`10_app-shell` finding: no `<ErrorBoundary>` wraps the route tree. A single uncaught render error today crashes the whole SPA. Step 4 / Step 5 surface — add a top-level `<ErrorBoundary>` plus per-feature boundaries for the canvas / map / chart so isolated failures don't take down the whole UI.
|
||||
|
||||
## 6. Recommended near-term improvements (Step 5 solution candidates)
|
||||
|
||||
1. **Add a top-level `<ErrorBoundary>`** in `App.tsx` with a "something broke" recovery card.
|
||||
2. **Replace silent catches** (`}` `catch {}`) with `console.error` + user toast — at minimum.
|
||||
3. **Inject a correlation ID** (`X-Request-Id` header) on every fetch + EventSource.
|
||||
4. **Surface AI-detect progress + errors** — see Flow F7 (currently flow doesn't even subscribe).
|
||||
5. **Add Sentry (or equivalent)** with runtime-config-driven DSN.
|
||||
6. **Add `web-vitals`** + emit to suite admin/ telemetry endpoint.
|
||||
@@ -0,0 +1,174 @@
|
||||
# Component Diagram
|
||||
|
||||
> Output of `/document` Step 2 — produced from the module-level dependency graph
|
||||
> in `_docs/02_document/00_discovery.md` §7. Edges are aggregated to component
|
||||
> level; cross-feature edges are kept (they exist in the code today).
|
||||
>
|
||||
> **Note on `05_flights`**: per user direction (Step 2 BLOCKING gate, 2026-05-10),
|
||||
> the `mission-planner/` codebase is NOT a separate component. It is the
|
||||
> port-source for `src/features/flights/` — both trees realise the same logical
|
||||
> component. They are physically disjoint at the file level (see `00_discovery.md`
|
||||
> §1) but documented together under `05_flights`.
|
||||
|
||||
## Component graph
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
classDef foundation fill:#1f3a4d,stroke:#3b6e8c,color:#cfe1ec
|
||||
classDef transport fill:#3a2d4d,stroke:#6a4f8c,color:#dccfe6
|
||||
classDef auth fill:#4d3a2d,stroke:#8c6a4f,color:#e6dccf
|
||||
classDef shared fill:#2d4d3a,stroke:#4f8c6a,color:#cfe6dc
|
||||
classDef feature fill:#4d3a3a,stroke:#8c5f5f,color:#e6cfcf
|
||||
classDef shell fill:#1e1e1e,stroke:#888,color:#fff
|
||||
|
||||
Foundation[00 — Foundation<br/>types · hooks · i18n]
|
||||
Transport[01 — API Transport<br/>client.ts · sse.ts]
|
||||
Auth[02 — Auth<br/>AuthContext · ProtectedRoute]
|
||||
ClassColors[11 — Class Colors<br/>fallback color/name · PhotoMode]
|
||||
SharedUI[03 — Shared UI & Context<br/>Header · HelpModal · ConfirmDialog<br/>DetectionClasses · FlightContext]
|
||||
|
||||
Login[04 — Login]
|
||||
Flights[05 — Flights & Mission Planning<br/>incl. GPS-Denied sub-page<br/>+ Test Mode (tlog+video→SITL→onboard)]
|
||||
Annotations[06 — Annotations]
|
||||
Dataset[07 — Dataset Explorer]
|
||||
Admin[08 — Admin]
|
||||
Settings[09 — Settings]
|
||||
|
||||
Shell[10 — App Shell<br/>main.tsx · App.tsx]
|
||||
|
||||
Foundation --> Transport
|
||||
Foundation --> Auth
|
||||
Foundation --> SharedUI
|
||||
Foundation --> Login
|
||||
Foundation --> Flights
|
||||
Foundation --> Annotations
|
||||
Foundation --> Dataset
|
||||
Foundation --> Admin
|
||||
Foundation --> Settings
|
||||
|
||||
Transport --> Auth
|
||||
Transport --> SharedUI
|
||||
Transport --> Flights
|
||||
Transport --> Annotations
|
||||
Transport --> Dataset
|
||||
Transport --> Admin
|
||||
Transport --> Settings
|
||||
|
||||
Auth --> SharedUI
|
||||
Auth --> Login
|
||||
Auth --> Shell
|
||||
|
||||
ClassColors --> SharedUI
|
||||
ClassColors --> Annotations
|
||||
ClassColors --> Dataset
|
||||
|
||||
SharedUI --> Flights
|
||||
SharedUI --> Annotations
|
||||
SharedUI --> Dataset
|
||||
SharedUI --> Admin
|
||||
SharedUI --> Settings
|
||||
SharedUI --> Shell
|
||||
|
||||
Login --> Shell
|
||||
Flights --> Shell
|
||||
Annotations --> Shell
|
||||
Dataset --> Shell
|
||||
Admin --> Shell
|
||||
Settings --> Shell
|
||||
|
||||
%% cross-feature edge that remains (existing today, NOT lifted)
|
||||
Annotations -. CanvasEditor .-> Dataset
|
||||
|
||||
class Foundation foundation
|
||||
class Transport transport
|
||||
class Auth auth
|
||||
class ClassColors shared
|
||||
class SharedUI shared
|
||||
class Login,Flights,Annotations,Dataset,Admin,Settings feature
|
||||
class Shell shell
|
||||
```
|
||||
|
||||
## `05_flights` — internal physical split
|
||||
|
||||
The Flights component is realised by two physically disjoint codebases that
|
||||
will converge over time. The graph below documents the port direction; no
|
||||
import edge crosses between the two trees at the file level today.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
classDef target fill:#4d3a3a,stroke:#8c5f5f,color:#e6cfcf
|
||||
classDef source fill:#2a2a3a,stroke:#666,color:#bbb
|
||||
classDef planned fill:#2d4d3a,stroke:#4f8c6a,color:#cfe6dc,stroke-dasharray: 4 4
|
||||
|
||||
subgraph Target_tree["Target tree — src/features/flights/ (deployed)"]
|
||||
SPA_FlightsPage[FlightsPage]
|
||||
SPA_FlightMap[FlightMap]
|
||||
SPA_FlightParams[FlightParamsPanel]
|
||||
SPA_FlightList[FlightListSidebar]
|
||||
SPA_Utils[flightPlanUtils.ts]
|
||||
SPA_Types[types.ts]
|
||||
SPA_GpsDenied[GPS-Denied panel<br/>partial today]
|
||||
SPA_TestMode[GPS-Denied · Test Mode<br/>tlog + video → SITL → onboard]:::planned
|
||||
end
|
||||
|
||||
subgraph Source_tree["Port source — mission-planner/ (NOT deployed)"]
|
||||
MP_FlightPlan[flightPlan.tsx]
|
||||
MP_LeftBoard[LeftBoard.tsx]
|
||||
MP_MapView[MapView.tsx ↔ MiniMap.tsx<br/>named-handle cycle]
|
||||
MP_PointsList[PointsList.tsx]
|
||||
MP_Services[services/<br/>calculateBatteryUsage<br/>AircraftService · WeatherService]
|
||||
MP_Lang[LanguageContext]
|
||||
end
|
||||
|
||||
MP_Services -. "port to →" .-> SPA_Utils
|
||||
MP_FlightPlan -. "port to →" .-> SPA_FlightsPage
|
||||
MP_LeftBoard -. "port to →" .-> SPA_FlightParams
|
||||
MP_MapView -. "port to →" .-> SPA_FlightMap
|
||||
MP_PointsList -. "port to →" .-> SPA_FlightParams
|
||||
MP_Lang -. "→ converge to react-i18next" .-> SPA_Types
|
||||
|
||||
SPA_FlightsPage --> SPA_GpsDenied
|
||||
SPA_GpsDenied --> SPA_TestMode
|
||||
|
||||
class SPA_FlightsPage,SPA_FlightMap,SPA_FlightParams,SPA_FlightList,SPA_Utils,SPA_Types,SPA_GpsDenied target
|
||||
class MP_FlightPlan,MP_LeftBoard,MP_MapView,MP_PointsList,MP_Services,MP_Lang source
|
||||
```
|
||||
|
||||
> Test Mode (`tlog + video → IMU/GPS sync → SITL → onboard`) is a **planned**
|
||||
> addition per `_docs/how_to_test.md`. The component's
|
||||
> `description.md` §6b is the spec.
|
||||
|
||||
### Cross-feature / cross-layer edges (kept, flagged for baseline scan)
|
||||
|
||||
| From | To | Why it exists | Owner of fix (if any) |
|
||||
|------|----|---------------|-----------------------|
|
||||
| `07_dataset/DatasetPage` | `06_annotations/CanvasEditor` | Dataset reuses the annotation canvas. Legacy carry-over from WPF era (`Azaion.Common.Controls.CanvasEditor`). | Architecture Baseline Scan; lift `CanvasEditor` to a shared `components/canvas/` location when convenient. |
|
||||
|
||||
> The `classColors` cross-edge that earlier appeared between Annotations and
|
||||
> SharedUI no longer exists at the component level — `classColors` is
|
||||
> documented as its own component (`11_class-colors`). The physical file
|
||||
> still lives in `src/features/annotations/`; that's a Step 4 testability
|
||||
> file-move candidate, not a component-graph issue.
|
||||
|
||||
## Layered view
|
||||
|
||||
```
|
||||
Layer 4 ── 10_app-shell
|
||||
│
|
||||
Layer 3 ── 04_login 05_flights* 06_annotations 07_dataset 08_admin 09_settings
|
||||
│ │ │ │ │ │
|
||||
Layer 2 ──────── 03_shared-ui ←──────────────────────────────────────────────────┘
|
||||
│ ↑ (Header reads useAuth; uses Foundation; etc.)
|
||||
│ 02_auth
|
||||
│ │
|
||||
Layer 1 ────── 01_api-transport 11_class-colors (sibling shared kernel)
|
||||
│
|
||||
Layer 0 ──── 00_foundation
|
||||
|
||||
* 05_flights spans two physical trees; the layering applies to the target
|
||||
tree (src/features/flights/). The mission-planner/ port-source is its own
|
||||
dependency island and is layered internally — see its module doc.
|
||||
```
|
||||
|
||||
The exact layering with cycle markers is finalised in
|
||||
`_docs/02_document/module-layout.md` (Step 2.5).
|
||||
@@ -0,0 +1,176 @@
|
||||
# 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 |
|
||||
@@ -0,0 +1,217 @@
|
||||
# Module Layout
|
||||
|
||||
**Status**: derived-from-code
|
||||
**Language**: typescript (React 19 + Vite + Tailwind)
|
||||
**Layout Convention**: custom (flat-features under `src/`; no per-component barrels)
|
||||
**Root**: `src/`
|
||||
**Last Updated**: 2026-05-10
|
||||
|
||||
> Authoritative file-ownership map for the React UI workspace. Derived from
|
||||
> `_docs/02_document/00_discovery.md` (dependency graph) and the Step 2
|
||||
> component specs at `_docs/02_document/components/`. Consumed by
|
||||
> `/implement` Step 4 (file ownership), `/code-review` Phase 7
|
||||
> (architecture violations), and `/refactor` discovery.
|
||||
|
||||
## Layout Rules
|
||||
|
||||
1. Each component owns ONE OR MORE top-level directories (or top-level files) under `src/`. The mapping is NOT 1:1 — `00_foundation` owns three sibling directories (`src/types/`, `src/hooks/`, `src/i18n/`), `05_flights` spans `src/features/flights/` AND a separate `mission-planner/` port-source root, and `10_app-shell` owns top-level files (`App.tsx`, `main.tsx`, `index.css`, `vite-env.d.ts`).
|
||||
2. Shared code does **not** live under `src/shared/` today — there is no `shared/` directory. Two helper modules (`11_class-colors/classColors.ts` and `06_annotations/CanvasEditor.tsx`) are physically misplaced and consumed across components; both are flagged in the `## Verification Needed` block. A `src/shared/` directory is a Step 4 testability candidate.
|
||||
3. Public API per component: NO barrel `index.ts` exists at any component root. The only `index.ts` files are `src/types/index.ts` (a re-export hub for type aliases — used as the de-facto public API for `00_foundation` types) and `mission-planner/src/types/index.ts`. Until Step 4 introduces barrels, Public API is approximated as "every named export from any file under the component's owned directories". Cross-component imports ARE happening at file-name granularity (`import { api } from '../api/client'`, `import { CanvasEditor } from '../annotations/CanvasEditor'`).
|
||||
4. Cross-cutting concerns (logging, config, error handling, telemetry): no dedicated infrastructure today. `console.error` / silent catches are the closest thing — recorded in module findings.
|
||||
5. Tests: there are **zero tests** under `src/`. The only test file is `mission-planner/src/test/jsonImport.test.ts`, which can't run because Jest isn't installed (00_discovery.md §11.5). Test layout is therefore TBD; suggest `src/<component>/__tests__/` per the standard React convention when tests are added (autodev Step 5–6).
|
||||
|
||||
## Per-Component Mapping
|
||||
|
||||
### Component: `00_foundation`
|
||||
|
||||
- **Epic**: TBD (set during autodev Step 4 / Decompose)
|
||||
- **Directories**: `src/types/`, `src/hooks/`, `src/i18n/`
|
||||
- **Public API** (de-facto, no barrel):
|
||||
- `src/types/index.ts` — every exported type alias (`Detection`, `Flight`, `MediaItem`, `User`, etc.)
|
||||
- `src/hooks/useDebounce.ts` — `useDebounce`
|
||||
- `src/hooks/useResizablePanel.ts` — `useResizablePanel`
|
||||
- `src/i18n/i18n.ts` — default export (i18n instance)
|
||||
- **Internal**: `src/i18n/en.json`, `src/i18n/ua.json` (data; consumed only by `i18n.ts`)
|
||||
- **Owns** (exclusive write): `src/types/**`, `src/hooks/**`, `src/i18n/**`
|
||||
- **Imports from**: (none — Layer 0)
|
||||
- **Consumed by**: every other component
|
||||
|
||||
### Component: `11_class-colors`
|
||||
|
||||
- **Epic**: TBD
|
||||
- **Directories**: (none today — physical file lives at `src/features/annotations/classColors.ts`, which is owned by `06_annotations` on disk). Logical owner is this component; physical move to `src/shared/classColors.ts` (or `src/components/detection/classColors.ts`) is a Step 4 testability task.
|
||||
- **Public API**: `src/features/annotations/classColors.ts` exports `getClassColor`, `getClassNameFallback`, `getPhotoModeSuffix`, `FALLBACK_CLASS_NAMES`.
|
||||
- **Internal**: module-private `CLASS_COLORS` constant.
|
||||
- **Owns**: pending — see Verification Needed item #1.
|
||||
- **Imports from**: (none — Layer 0/1, no internal imports)
|
||||
- **Consumed by**: `03_shared-ui` (DetectionClasses), `06_annotations` (CanvasEditor, AnnotationsPage, AnnotationsSidebar)
|
||||
|
||||
### Component: `01_api-transport`
|
||||
|
||||
- **Epic**: TBD
|
||||
- **Directory**: `src/api/`
|
||||
- **Public API** (de-facto): `src/api/client.ts` exports `api` (fetch wrapper); `src/api/sse.ts` exports `subscribeSSE` / equivalent helper.
|
||||
- **Internal**: none (both files are externally consumed)
|
||||
- **Owns**: `src/api/**`
|
||||
- **Imports from**: `00_foundation` (types)
|
||||
- **Consumed by**: `02_auth`, `03_shared-ui`, every feature page (04, 05, 06, 07, 08, 09)
|
||||
|
||||
### Component: `02_auth`
|
||||
|
||||
- **Epic**: TBD
|
||||
- **Directory**: `src/auth/`
|
||||
- **Public API**: `src/auth/AuthContext.tsx` exports `AuthProvider`, `useAuth`. `src/auth/ProtectedRoute.tsx` exports `ProtectedRoute`.
|
||||
- **Internal**: none
|
||||
- **Owns**: `src/auth/**`
|
||||
- **Imports from**: `00_foundation`, `01_api-transport`
|
||||
- **Consumed by**: `03_shared-ui` (Header reads `useAuth`), `04_login`, `10_app-shell` (mounts `AuthProvider` + `ProtectedRoute`)
|
||||
|
||||
### Component: `03_shared-ui`
|
||||
|
||||
- **Epic**: TBD
|
||||
- **Directory**: `src/components/`
|
||||
- **Public API** (de-facto, all are externally consumed):
|
||||
- `Header.tsx` → `Header`
|
||||
- `HelpModal.tsx` → `HelpModal`
|
||||
- `ConfirmDialog.tsx` → `ConfirmDialog`
|
||||
- `DetectionClasses.tsx` → `DetectionClasses`
|
||||
- `FlightContext.tsx` → `FlightProvider`, `useFlight`
|
||||
- **Internal**: none — every file in `src/components/` is consumed externally today
|
||||
- **Owns**: `src/components/**`
|
||||
- **Imports from**: `00_foundation`, `11_class-colors` (physical: `../features/annotations/classColors`), `01_api-transport`, `02_auth`
|
||||
- **Consumed by**: `10_app-shell` (mounts `Header` + `FlightProvider`), every feature page (consumes `useFlight`, `ConfirmDialog`, `DetectionClasses`)
|
||||
|
||||
### Component: `04_login`
|
||||
|
||||
- **Epic**: TBD
|
||||
- **Directory**: `src/features/login/`
|
||||
- **Public API**: `LoginPage.tsx` → `LoginPage`
|
||||
- **Internal**: none (single-page component)
|
||||
- **Owns**: `src/features/login/**`
|
||||
- **Imports from**: `00_foundation`, `01_api-transport`, `02_auth`
|
||||
- **Consumed by**: `10_app-shell` (route)
|
||||
|
||||
### Component: `05_flights`
|
||||
|
||||
- **Epic**: TBD (this is the merged Flights & Mission Planning component)
|
||||
- **Directories** (TWO physical roots):
|
||||
- `src/features/flights/` — deployed target tree (15 modules)
|
||||
- `mission-planner/` — port-source, NOT deployed (37 modules under `mission-planner/src/`). Documented inside this component per the user's Step 2 BLOCKING-gate decision (`_docs/02_document/state.json::component_05_flights_merge_2026-05-10`). The port direction is `mission-planner/` → `src/features/flights/`; module-layout treats both trees as owned by this component but only the target tree is in the layering table below.
|
||||
- **Public API** (target tree, de-facto): `FlightsPage.tsx` → `FlightsPage` (route component). Internal sub-components (`FlightMap`, `FlightParamsPanel`, `FlightListSidebar`, `WaypointList`, `AltitudeChart`, `AltitudeDialog`, `WindEffect`, `MiniMap`, `MapPoint`, `DrawControl`, `JsonEditorDialog`, `mapIcons`, `flightPlanUtils`, `types`) are NOT consumed outside the component.
|
||||
- **Public API** (port-source `mission-planner/`): not consumed at all by `src/` today (separate Vite entrypoint, `main.tsx` of its own). Effectively a private vendored sibling.
|
||||
- **Internal** (target tree): every file under `src/features/flights/` except `FlightsPage.tsx`
|
||||
- **Internal** (port-source): every file under `mission-planner/`
|
||||
- **Owns**: `src/features/flights/**`, `mission-planner/**`
|
||||
- **Imports from** (target tree): `00_foundation`, `01_api-transport`, `02_auth` (via `ProtectedRoute` from shell), `03_shared-ui` (uses `ConfirmDialog`, `useFlight`)
|
||||
- **Consumed by**: `10_app-shell` (route)
|
||||
|
||||
### Component: `06_annotations`
|
||||
|
||||
- **Epic**: TBD
|
||||
- **Directory**: `src/features/annotations/`
|
||||
- **Public API** (de-facto):
|
||||
- `AnnotationsPage.tsx` → `AnnotationsPage` (route component)
|
||||
- `CanvasEditor.tsx` → `CanvasEditor` — **also imported by `07_dataset`** (cross-feature edge, see Verification Needed #3)
|
||||
- **Internal**: `MediaList.tsx`, `VideoPlayer.tsx`, `AnnotationsSidebar.tsx`
|
||||
- **Owns**: `src/features/annotations/**` EXCEPT `classColors.ts` (logically owned by `11_class-colors`; physical home pending refactor)
|
||||
- **Imports from**: `00_foundation`, `11_class-colors`, `01_api-transport`, `03_shared-ui`
|
||||
- **Consumed by**: `10_app-shell` (route); `07_dataset` (imports `CanvasEditor` directly — see Verification Needed)
|
||||
|
||||
### Component: `07_dataset`
|
||||
|
||||
- **Epic**: TBD
|
||||
- **Directory**: `src/features/dataset/`
|
||||
- **Public API**: `DatasetPage.tsx` → `DatasetPage`
|
||||
- **Internal**: none (single-page)
|
||||
- **Owns**: `src/features/dataset/**`
|
||||
- **Imports from**: `00_foundation`, `11_class-colors` (only when class-distribution chart is added — not in code yet), `01_api-transport`, `03_shared-ui`, **`06_annotations` (CanvasEditor cross-feature edge)**
|
||||
- **Consumed by**: `10_app-shell` (route)
|
||||
|
||||
### Component: `08_admin`
|
||||
|
||||
- **Epic**: TBD
|
||||
- **Directory**: `src/features/admin/`
|
||||
- **Public API**: `AdminPage.tsx` → `AdminPage`
|
||||
- **Internal**: none (single-page)
|
||||
- **Owns**: `src/features/admin/**`
|
||||
- **Imports from**: `00_foundation`, `01_api-transport`, `03_shared-ui`
|
||||
- **Consumed by**: `10_app-shell` (route)
|
||||
|
||||
### Component: `09_settings`
|
||||
|
||||
- **Epic**: TBD
|
||||
- **Directory**: `src/features/settings/`
|
||||
- **Public API**: `SettingsPage.tsx` → `SettingsPage`
|
||||
- **Internal**: none (single-page)
|
||||
- **Owns**: `src/features/settings/**`
|
||||
- **Imports from**: `00_foundation`, `01_api-transport`, `03_shared-ui`
|
||||
- **Consumed by**: `10_app-shell` (route)
|
||||
|
||||
### Component: `10_app-shell`
|
||||
|
||||
- **Epic**: TBD
|
||||
- **Files** (no dedicated directory): `src/App.tsx`, `src/main.tsx`, `src/index.css`, `src/vite-env.d.ts`
|
||||
- **Public API**: `main.tsx` is the Vite entrypoint (no symbols are externally imported). `App.tsx` exports `App`.
|
||||
- **Internal**: `index.css` (global Tailwind base + `az-*` design-token CSS variables), `vite-env.d.ts` (type shim)
|
||||
- **Owns**: `src/App.tsx`, `src/main.tsx`, `src/index.css`, `src/vite-env.d.ts`
|
||||
- **Imports from**: every other component (it is the composition root)
|
||||
- **Consumed by**: (none — top of the graph; bundled by Vite)
|
||||
|
||||
## Shared / Cross-Cutting
|
||||
|
||||
> No `src/shared/` directory exists today. Two cross-cutting concerns are tracked here as **proposed** shared modules; they require a physical file move scheduled for Step 4 (testability) or Step 8 (refactor).
|
||||
|
||||
### shared/class-colors (proposed; current physical location: `src/features/annotations/classColors.ts`)
|
||||
|
||||
- **Owner component**: `11_class-colors`
|
||||
- **Purpose**: Detection-class fallback color, fallback name, PhotoMode suffix.
|
||||
- **Owned by**: pending move task — current physical file is under `06_annotations`'s owns-glob, which makes it ambiguous. Workaround: until moved, treat `classColors.ts` as `OWNED` by tasks targeting `11_class-colors` and `READ-ONLY` to all other tasks (including those targeting `06_annotations`).
|
||||
- **Consumed by**: `03_shared-ui/DetectionClasses`, `06_annotations` (CanvasEditor, AnnotationsPage, AnnotationsSidebar)
|
||||
|
||||
### shared/canvas-editor (proposed; current physical location: `src/features/annotations/CanvasEditor.tsx`)
|
||||
|
||||
- **Owner component**: still `06_annotations` for now (it's the dominant consumer)
|
||||
- **Purpose**: Bounding-box draw / move / resize layer; reused by Dataset's inline editor.
|
||||
- **Status**: cross-feature edge (07_dataset imports it). The proper home is a future `src/components/canvas/` directory. Decision deferred to Step 2 architecture baseline scan; the implement skill should treat this as a `READ-ONLY` for `07_dataset` tasks.
|
||||
|
||||
## Allowed Dependencies (layering)
|
||||
|
||||
Read top-to-bottom; an upper layer may import from a lower layer but NEVER the reverse. Same-layer imports are permitted only for explicit cross-feature edges listed in the table footnotes.
|
||||
|
||||
| Layer | Components | May import from |
|
||||
|-------|------------|-----------------|
|
||||
| 4. App Shell / Entry | `10_app-shell` | 0, 1, 2, 3 (and any feature in Layer 3) |
|
||||
| 3. Application / Features | `04_login`, `05_flights`, `06_annotations`, `07_dataset`<sup>†</sup>, `08_admin`, `09_settings` | 0, 1, 2, 3<sup>†</sup> |
|
||||
| 2. Composition | `02_auth`, `03_shared-ui` | 0, 1 |
|
||||
| 1. Transport | `01_api-transport` | 0 |
|
||||
| 0. Foundation / Shared kernel | `00_foundation`, `11_class-colors` | (none) |
|
||||
|
||||
<sup>†</sup> `07_dataset` imports `06_annotations/CanvasEditor.tsx` — same-layer cross-feature edge. Permitted today; flagged as a refactor target. The implement skill grants `07_dataset` tasks **READ-ONLY** access to that one file specifically.
|
||||
|
||||
Violations of this table are **Architecture** findings in code-review Phase 7 and are High severity.
|
||||
|
||||
## Verification Needed
|
||||
|
||||
The following inferences could not be made cleanly from code alone. They are surfaced for the user to confirm or override at the Step 2.5 BLOCKING gate.
|
||||
|
||||
1. **Physical home of `11_class-colors`**. The component is logically Layer 0/1 shared kernel, but its physical file lives inside `06_annotations`'s owns-glob (`src/features/annotations/classColors.ts`). Until the file is moved (proposed: `src/shared/classColors.ts`), the implement skill must apply the special-case rule documented under `shared/class-colors` above (READ-ONLY for `06_annotations` tasks even though the file is inside that component's directory). **Decision needed**: schedule the file move at Step 4 / Step 8, or accept the special-case rule indefinitely?
|
||||
|
||||
2. **Physical home of `CanvasEditor.tsx`**. Same shape: it lives under `06_annotations` and is consumed cross-feature by `07_dataset`. Proposed: `src/components/canvas/CanvasEditor.tsx` (or a new `06b_canvas` component). **Decision needed**: keep the same-layer cross-feature edge, or schedule the lift?
|
||||
|
||||
3. **No barrel exports anywhere**. The codebase imports cross-component at file-name granularity (`import { api } from '../api/client'`). This means every internal file is *de-facto* Public API. Recommendation: Step 4 testability task to add `src/<component>/index.ts` barrels per component, locking the public surface. **Decision needed**: add barrels now or stay file-import?
|
||||
|
||||
4. **`mission-planner/` is owned by `05_flights` but lives at the repo root** (not under `src/`). Layout rule #1 says one component owns one or more top-level directories — this satisfies the rule (it owns two: `src/features/flights/` AND `mission-planner/`). Implement-skill consumers must include `mission-planner/**` in `05_flights`'s OWNED glob. **Decision needed**: confirm the implement skill should treat `mission-planner/**` as OWNED by 05_flights (otherwise it's FORBIDDEN by default).
|
||||
|
||||
5. **`05_flights` cycle inside the port-source**. `mission-planner/src/flightPlanning/MapView.tsx ↔ MiniMap.tsx` form a circular import (named-handle, see `00_discovery.md` §7 footnote). They were analyzed together in batch MP-B6. The cycle is internal to the component and does not cross component boundaries; flagged here for completeness.
|
||||
|
||||
6. **`00_foundation` owns three sibling directories** (`types/`, `hooks/`, `i18n/`). Layout rule #1 permits this. Future option: split into `00a_types`, `00b_hooks`, `00c_i18n` if the directories grow. **Decision needed**: keep the multi-directory component, or split now?
|
||||
|
||||
7. **`10_app-shell` owns top-level files instead of a directory** (`src/App.tsx`, `src/main.tsx`, etc.). Layout rule #1 permits this. The implement-skill OWNED glob for app-shell tasks must therefore be the explicit file list, not a directory glob.
|
||||
|
||||
8. **Test layout is undefined** (no tests exist). When Steps 5–6 of autodev produce tests, recommended layout is `src/<component-dir>/__tests__/` per React convention; for `05_flights` cross-tree tests, prefer `src/features/flights/__tests__/` (target tree only).
|
||||
|
||||
## Layout Conventions (reference)
|
||||
|
||||
| Language | Root | Per-component path | Public API file | Test path |
|
||||
|----------|------|-------------------|-----------------|-----------|
|
||||
| TypeScript / React | `src/` | `src/<component>/` (this codebase deviates: features under `src/features/<feature>/`, shared chrome under `src/components/`) | `src/<component>/index.ts` (barrel — none exist today) | `src/<component>/__tests__/` (none exist today) |
|
||||
@@ -0,0 +1,123 @@
|
||||
# Module group: `mission-planner/`
|
||||
|
||||
> **Single consolidated doc** for the entire `mission-planner/` sub-project (37 modules across `services/`, `flightPlanning/`, `icons/`, `constants/`, `types/`, `utils.ts`, `config.ts`, `main.tsx`, `App.tsx`).
|
||||
>
|
||||
> **Why a single doc**: `mission-planner/` is **port-source, not deployed product** (per workspace `README.md` + `00_discovery.md §1`). The Dockerfile builds only the workspace `src/`. Documenting each of the 37 files at the same fidelity as the production SPA would burn context for code that exists only as a reference for the React-19 port. Future deletion of `mission-planner/` is a Step 8 / autodev follow-up once `src/features/flights/` reaches feature-parity.
|
||||
|
||||
## Role in the codebase
|
||||
|
||||
| Aspect | Status |
|
||||
|---|---|
|
||||
| Purpose | Reference implementation of the flight-mission planner UI being mechanically translated into `src/features/flights/`. Stand-alone CRA-flavoured Vite + React 18 + MUI 5 app. |
|
||||
| Build | Has its own `vite.config.ts`, `tsconfig`, `index.html`, `package.json`. No alias path. |
|
||||
| Deployment | None — workspace `Dockerfile` does NOT build it; `nginx.conf` does NOT serve it. |
|
||||
| Tests | `src/test/jsonImport.test.ts` uses `describe/it/expect` style; **Jest is not installed** and there is no `test` script — the test cannot run as-is. Documented gap, no fix planned (out of scope per `00_discovery.md §11.5`). |
|
||||
| Lifecycle | Will be deleted once `src/features/flights/` covers all mission-planner features. Not before. |
|
||||
|
||||
## Directory map
|
||||
|
||||
```
|
||||
mission-planner/src/
|
||||
├── main.tsx → mounts <LanguageProvider><FlightPlan /> into #root
|
||||
├── App.tsx UNUSED — empty CRA stub; main.tsx mounts FlightPlan directly
|
||||
├── config.ts COORDINATE_PRECISION, downang, upang, defaults
|
||||
├── utils.ts newGuid (Math.random v4)
|
||||
├── types/index.ts FlightPoint, CalculatedPointInfo, MapRectangle, AircraftParams,
|
||||
│ WeatherData, MovingPointInfo, ActionMode, MapType, large
|
||||
│ TranslationStrings interface tree
|
||||
├── constants/
|
||||
│ ├── actionModes.ts points / workArea / prohibitedArea
|
||||
│ ├── maptypes.ts classic / satellite
|
||||
│ ├── tileUrls.ts OSM + Esri ArcGIS tile URLs
|
||||
│ ├── translations.ts English + Ukrainian dictionaries (raw, no i18next)
|
||||
│ ├── languages.ts ISO codes + flag codes for LanguageSwitcher
|
||||
│ └── purposes.ts tank, artillery
|
||||
├── services/
|
||||
│ ├── calculateDistance.ts Haversine + plane climb/cruise/descend
|
||||
│ ├── AircraftService.ts mockGetAirplaneParams (returns hardcoded fixed-wing)
|
||||
│ ├── WeatherService.ts OpenWeatherMap fetch
|
||||
│ └── calculateBatteryUsage.ts Drag + thrust lookup; same algorithm as src/features/flights/flightPlanUtils.calculateBatteryPercentUsed
|
||||
├── icons/
|
||||
│ ├── MapIcons.tsx Leaflet icon factories
|
||||
│ ├── PointIcons.tsx Per-purpose marker icons
|
||||
│ ├── SidebarIcons.tsx MUI-styled side-panel SVGs
|
||||
│ └── PhoneIcon.tsx Rotate-phone overlay (mobile orientation hint)
|
||||
└── flightPlanning/
|
||||
├── flightPlan.tsx Top-level page (369 lines) — owns state, dialogs, JSON I/O
|
||||
├── MapView.tsx MapContainer + draw handlers + click-to-add (414 lines)
|
||||
├── MiniMap.tsx Floating thumbnail; cyclic edge with MapView
|
||||
├── MapPoint.tsx Draggable waypoint + popup
|
||||
├── DrawControl.tsx Rectangle draw tool
|
||||
├── PointsList.tsx Reorderable waypoint list
|
||||
├── LeftBoard.tsx Side panel composing list + chart + totals + lang switcher
|
||||
├── AltitudeChart.tsx Chart.js altitude visualizer
|
||||
├── AltitudeDialog.tsx Add/Edit waypoint modal
|
||||
├── JsonEditorDialog.tsx Edit-as-JSON modal
|
||||
├── TotalDistance.tsx Total distance + time + battery readout
|
||||
├── LanguageContext.tsx React Context for current locale (NOT i18next)
|
||||
├── LanguageSwitcher.tsx Locale dropdown
|
||||
├── WindEffect.tsx Wind heading / speed inputs + arrow preview
|
||||
└── Aircraft.ts Aircraft helper (filename casing odd — TypeScript file, capitalised)
|
||||
```
|
||||
|
||||
## Mapping `mission-planner/` ↔ `src/features/flights/`
|
||||
|
||||
The React 19 port translates module-for-module wherever possible. Status as of this commit:
|
||||
|
||||
| `mission-planner/src/...` | Ported to `src/features/flights/...` | Status |
|
||||
|---|---|---|
|
||||
| `flightPlanning/flightPlan.tsx` | `FlightsPage.tsx` | Ported with backend wiring (Flights API + SSE). MP-side has none. |
|
||||
| `flightPlanning/MapView.tsx` | `FlightMap.tsx` | Ported. |
|
||||
| `flightPlanning/MiniMap.tsx` | `MiniMap.tsx` | Ported. |
|
||||
| `flightPlanning/MapPoint.tsx` | `MapPoint.tsx` | Ported. |
|
||||
| `flightPlanning/DrawControl.tsx` | `DrawControl.tsx` | Ported. |
|
||||
| `flightPlanning/PointsList.tsx` | `WaypointList.tsx` | Ported (renamed for parity with backend `Waypoint` entity). |
|
||||
| `flightPlanning/LeftBoard.tsx` | `FlightParamsPanel.tsx` | Partial — MP-side hosts `LanguageSwitcher`, the SPA delegates language to global `Header` + `react-i18next`. |
|
||||
| `flightPlanning/AltitudeChart.tsx` | `AltitudeChart.tsx` | Ported. |
|
||||
| `flightPlanning/AltitudeDialog.tsx` | `AltitudeDialog.tsx` | Ported (file name kept; should be `WaypointDialog`). |
|
||||
| `flightPlanning/JsonEditorDialog.tsx` | `JsonEditorDialog.tsx` | Ported. |
|
||||
| `flightPlanning/WindEffect.tsx` | `WindEffect.tsx` | Ported. |
|
||||
| `flightPlanning/TotalDistance.tsx` | (inlined into `FlightParamsPanel`) | Ported as a `<div>` strip in the params panel; no separate module. |
|
||||
| `flightPlanning/LanguageContext.tsx` + `LanguageSwitcher.tsx` | (replaced by `react-i18next`) | Not ported as such — language is global via i18next. |
|
||||
| `flightPlanning/Aircraft.ts` | (no equivalent) | Aircraft is server-side; the SPA fetches `/api/flights/aircrafts`. |
|
||||
| `services/calculateDistance.ts` | `flightPlanUtils.calculateDistance` | Ported. |
|
||||
| `services/calculateBatteryUsage.ts` | `flightPlanUtils.calculateBatteryPercentUsed` + `calculateAllPoints` | Ported. |
|
||||
| `services/WeatherService.ts` | `flightPlanUtils.getWeatherData` | Ported (with the same hardcoded API key — Step 4 fix). |
|
||||
| `services/AircraftService.ts` | `flightPlanUtils.getMockAircraftParams` (mock only) | Real fetch is `/api/flights/aircrafts` in `FlightsPage`. |
|
||||
| `constants/translations.ts` + `LanguageContext.tsx` | `src/i18n/{en,ua}.json` + `i18n/i18n.ts` | Migrated to i18next. |
|
||||
| `constants/{actionModes,maptypes,tileUrls,purposes,languages}.ts` | `features/flights/types.ts` (`PURPOSES`, `TILE_URLS`, `ActionMode`) | Consolidated into one file. |
|
||||
| `icons/{MapIcons,PointIcons,SidebarIcons,PhoneIcon}.tsx` | `features/flights/mapIcons.ts` | Only the marker icons survived; SidebarIcons + PhoneIcon dropped (no rotate-phone overlay in the SPA today). |
|
||||
| `utils.ts` (`newGuid`) | `flightPlanUtils.newGuid` | Ported. |
|
||||
| `config.ts` | `features/flights/types.COORDINATE_PRECISION` | Single constant migrated. |
|
||||
| `App.tsx` | (none) | Was already an unused CRA stub in MP; nothing to port. |
|
||||
| `main.tsx` | (none) | Replaced by the workspace `src/main.tsx`. |
|
||||
| `setupTests.ts`, `test/jsonImport.test.ts` | (none) | Cannot run; not migrated. |
|
||||
|
||||
## Things still in MP that are NOT in the SPA port
|
||||
|
||||
- **Rotate-phone overlay** (`icons/PhoneIcon.tsx`): MP shows a rotate-phone hint when held in portrait. The SPA does not.
|
||||
- **Per-purpose marker icons** (`icons/PointIcons.tsx`): MP draws a different marker per `meta` purpose. The SPA uses three colour-coded icons (start / mid / end).
|
||||
- **`Aircraft.ts` helper class**: never used in the SPA — aircraft state is fetched and treated as a plain DTO.
|
||||
- **OpenWeather call directly from `WeatherService.ts`**: same flaw as the SPA port (hardcoded key, no proxy). Both flagged for Step 4.
|
||||
- **MUI 5**: MP uses MUI for dialogs / inputs / icons. The SPA replaced everything with hand-rolled Tailwind components matching `_docs/ui_design/README.md`. MUI is not a dep of the workspace.
|
||||
|
||||
## Findings carried into Step 4 / 6 / 8
|
||||
|
||||
1. **`mission-planner/src/App.tsx` is an unused CRA stub** — `main.tsx` mounts `FlightPlan` directly. Deletion candidate but only after the port is complete (per `00_discovery.md §11.6`). Step 8.
|
||||
2. **`mission-planner/src/test/jsonImport.test.ts` cannot run** (Jest not installed; no test script). Out of scope. Step 8 deletion or migration to the suite-level e2e harness.
|
||||
3. **`flightPlanning/MapView.tsx ↔ MiniMap.tsx`** import each other (`MiniMap` imports the *named* `UpdateMapCenter` helper from `MapView`; `MapView` imports `MiniMap` as a JSX child). Module-level execution is non-circular because each side only uses the type/handle exposed at call time. Ported to `src/features/flights/FlightMap.tsx + MiniMap.tsx` without the cycle.
|
||||
4. **MP uses raw translation tables** keyed by ISO code, not i18next. The SPA correctly migrated to `react-i18next`; the legacy Russian-language references (if any in `translations.ts`) are out of scope.
|
||||
5. **`mission-planner/.env.example`** declares `VITE_SATELLITE_TILE_URL` — same env-driven pattern that the workspace `src/` should adopt for the Esri tile URL (currently hardcoded). Carry idea to Step 4.
|
||||
6. **`mission-planner/package.json`** lockfile is uncommitted (`bun.lock` is workspace-only; MP uses npm without a committed lock). Reproducibility risk if anyone runs MP. Step 8 — when MP is deleted this becomes moot.
|
||||
7. **Dependency divergence**: MP uses `react-leaflet` 4.2 vs workspace 5.x; `@hello-pangea/dnd` 16 vs 18; `chart.js` shared. None of this affects the deployed bundle. Step 8 — delete MP.
|
||||
|
||||
## Tests
|
||||
|
||||
The single `jsonImport.test.ts` cannot run. None of the other 36 modules have tests.
|
||||
|
||||
## Cross-doc references
|
||||
|
||||
- `_docs/02_document/00_discovery.md §1, §2b, §7b, §10, §11` — discovery-level facts about MP.
|
||||
- Workspace `README.md` — declares MP as not-deployed.
|
||||
- `mission-planner/README.md` — stale CRA boilerplate, do not trust.
|
||||
- The 14 `src/features/flights/` modules — see consolidated `src__features__flights.md`.
|
||||
@@ -0,0 +1,55 @@
|
||||
# Modules: `src/App.tsx` + `src/main.tsx`
|
||||
|
||||
> Compact combined doc — both modules are tiny, top-of-tree wiring only.
|
||||
|
||||
## `src/main.tsx` (entry)
|
||||
|
||||
Mounts the React tree:
|
||||
|
||||
- Calls `createRoot(document.getElementById('root')!)` — the non-null assertion will throw at boot if `<div id="root">` is missing from `index.html` (it is present).
|
||||
- Wraps in `<StrictMode>` (double-renders effects in dev) and `<BrowserRouter>` (HTML5 history).
|
||||
- Imports `./i18n/i18n` for **side effects only** — that file calls `i18n.init({...})` at import time. See `src__i18n__i18n.md` for the locked-language finding (lng:'en' hardcoded).
|
||||
- Imports `./index.css` — the Tailwind 4 stylesheet plus the `az-*` token definitions consumed by every component.
|
||||
|
||||
No props, no state, nothing testable.
|
||||
|
||||
## `src/App.tsx` (route tree)
|
||||
|
||||
Top-level routes:
|
||||
|
||||
| Path | Element | Notes |
|
||||
|---|---|---|
|
||||
| `/login` | `<LoginPage />` | Public; outside auth + flight providers. |
|
||||
| `/*` | `<ProtectedRoute><FlightProvider><Header />...nested Routes...</FlightProvider></ProtectedRoute>` | Auth-gated container. Mounts `Header` once across all child routes. |
|
||||
| `/flights` | `<FlightsPage />` | (default redirect target) |
|
||||
| `/annotations` | `<AnnotationsPage />` | |
|
||||
| `/dataset` | `<DatasetPage />` | |
|
||||
| `/admin` | `<AdminPage />` | (no extra role gate — see Findings) |
|
||||
| `/settings` | `<SettingsPage />` | (no extra role gate — see Findings) |
|
||||
| `*` | `<Navigate to="/flights" replace />` | catch-all under the protected branch. |
|
||||
|
||||
Outside everything: `<AuthProvider>`. So:
|
||||
- `LoginPage` can call `useAuth()`.
|
||||
- `FlightProvider` only mounts after `ProtectedRoute` has confirmed an authenticated user — `FlightContext` queries `/api/flights` only once we know we're logged in. This avoids the 401-then-401-loop on first paint.
|
||||
|
||||
Layout: `flex flex-col h-screen` — header at top, content fills the rest with `overflow-hidden`. Each page owns its own scroll/resize.
|
||||
|
||||
## Findings carried into Step 4 / 6
|
||||
|
||||
1. **`/admin` is reachable by users without ADM permission (defence-in-depth gap)**: `App.tsx:30` route has no permission check. `Header.tsx:88` filters menu visibility via `hasPermission('ADM')`, but typing `/admin` directly bypasses the menu hide. Users without ADM see a partially-working Admin page until the server returns 403 on each write. Per parent `../../../../_docs/00_roles_permissions.md` only Admin / ApiAdmin holds ADM. **PRIORITY** for Step 4. Note: `/settings` is similarly ungated, but `_docs/00_roles_permissions.md` does NOT define a `SETTINGS` permission code — settings calls land on `/api/admin/...` endpoints which are server-enforced by ADM via 403. Open question for Step 6: should `/settings` also be ADM-gated client-side, or is the per-user-settings subset (`/api/admin/users/me/settings`) intended to be reachable by non-admins?
|
||||
2. **No `<ErrorBoundary>` wrapping the protected branch**: a render error inside any page crashes the whole tree. Step 4 / Step 8.
|
||||
3. **No lazy-loading of route chunks** (`React.lazy` / `Suspense`). The whole app bundles in one chunk. For now the bundle is small enough that this is acceptable — Step 8 candidate when bundle size grows.
|
||||
4. **Default redirect target is `/flights`** even for users whose primary task is annotations or dataset. Could be a per-role default landing page. Step 6.
|
||||
|
||||
(Earlier draft of this doc claimed there was no mobile bottom-nav — that was incorrect. `Header.tsx:113-129` does render a bottom-nav at `< sm`. The whole-app `flex flex-col h-screen` layout is the same at all breakpoints by design.)
|
||||
|
||||
## Tests
|
||||
|
||||
None.
|
||||
|
||||
## Cross-doc references
|
||||
|
||||
- `src__main_tsx` (this doc) ← entry; depended-upon by all others transitively.
|
||||
- `src/auth/AuthContext.tsx`, `src/auth/ProtectedRoute.tsx` — already documented.
|
||||
- `src/components/FlightContext.tsx`, `src/components/Header.tsx` — already documented.
|
||||
- Parent roles spec: `../../../../_docs/00_roles_permissions.md`.
|
||||
@@ -0,0 +1,109 @@
|
||||
# Module: `src/api/client.ts`
|
||||
|
||||
> **Source**: `src/api/client.ts` (65 lines)
|
||||
> **Topo batch**: B2 (leaf — no internal imports)
|
||||
|
||||
## Purpose
|
||||
|
||||
Minimal `fetch` wrapper that injects the JWT bearer token, normalises HTTP errors into `Error` throws, and transparently retries a single time after a 401 by attempting a refresh. Acts as the single HTTP entry point for every page; there is no per-service typed client.
|
||||
|
||||
## Public interface
|
||||
|
||||
Token plumbing:
|
||||
|
||||
```ts
|
||||
export function setToken(token: string | null): void
|
||||
export function getToken(): string | null
|
||||
```
|
||||
|
||||
HTTP API:
|
||||
|
||||
```ts
|
||||
export const api = {
|
||||
get: <T>(url) => Promise<T>
|
||||
post: <T>(url, body?) => Promise<T>
|
||||
put: <T>(url, body?) => Promise<T>
|
||||
patch: <T>(url, body?) => Promise<T>
|
||||
delete: <T>(url) => Promise<T>
|
||||
upload: <T>(url, formData: FormData) => Promise<T>
|
||||
}
|
||||
```
|
||||
|
||||
## Internal logic
|
||||
|
||||
- Module-level mutable variable `let accessToken: string | null` holds the current bearer token.
|
||||
- `request<T>(url, options)`:
|
||||
1. Build a `Headers` from `options.headers`, inject `Authorization: Bearer <token>` if present.
|
||||
2. If `options.body` is a `string`, set `Content-Type: application/json`. (Crucial: `upload()` passes a `FormData` body, which is **not** a string, so `Content-Type` is left to the browser to set with the multipart boundary.)
|
||||
3. `fetch(url, ...)`.
|
||||
4. On `401` *and* a present token: call `refreshToken()`. On success, set the new bearer and retry the same request once. On failure, clear the token and `window.location.href = '/login'`, then throw "Session expired".
|
||||
5. Hand off to `handleResponse<T>`.
|
||||
- `handleResponse<T>(res)`:
|
||||
- `204` → `undefined as T`.
|
||||
- `!res.ok` → throw `new Error(\`${status}: ${text || statusText}\`)`. Body text is read defensively (`.catch(() => '')`).
|
||||
- Otherwise → `res.json()` (no schema validation — caller types the response).
|
||||
- `refreshToken()` — `POST /api/admin/auth/refresh` with `credentials: 'include'`. On 200, expects `{ token: string }` and stores it. Returns boolean.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Internal**: none.
|
||||
- **External**: `fetch`, `Headers`, `FormData`, `Response` (browser globals). No npm runtime dependency.
|
||||
|
||||
## Consumers (intra-repo)
|
||||
|
||||
The module-level `api` object is imported by:
|
||||
|
||||
- `src/auth/AuthContext.tsx` (login / logout / initial refresh)
|
||||
- `src/components/FlightContext.tsx` (flights list, user settings get/put)
|
||||
- `src/components/DetectionClasses.tsx` (admin classes load)
|
||||
- `src/features/admin/AdminPage.tsx`
|
||||
- `src/features/settings/SettingsPage.tsx`
|
||||
- `src/features/dataset/DatasetPage.tsx`
|
||||
- `src/features/flights/FlightsPage.tsx`
|
||||
- `src/features/annotations/{AnnotationsPage,AnnotationsSidebar,MediaList}.tsx`
|
||||
|
||||
`setToken` is imported by `AuthContext` (login / refresh / logout).
|
||||
`getToken` is imported by `src/api/sse.ts` (to append the token to SSE URLs).
|
||||
|
||||
## Data models
|
||||
|
||||
None defined here. The generic `T` parameter is supplied by call sites.
|
||||
|
||||
## Configuration
|
||||
|
||||
URLs are **string literals** at every call site (`/api/admin/...`, `/api/flights?...`, etc.). There is no base-URL constant. The `vite.config.ts` dev proxy and `nginx.conf` production rules forward `/api/*` to per-service backends.
|
||||
|
||||
A `VITE_API_BASE_URL` env-var fix is the canonical Step 4 testability candidate (workspace `README.md` calls this out).
|
||||
|
||||
## External integrations
|
||||
|
||||
Every backend the SPA talks to flows through this module. See `nginx.conf` for the routing table:
|
||||
|
||||
| Path prefix | Backend service |
|
||||
|---|---|
|
||||
| `/api/admin/*` | `admin/` (.NET) |
|
||||
| `/api/annotations/*` | `annotations/` (.NET) |
|
||||
| `/api/flights/*` | `flights/` (.NET) |
|
||||
| `/api/resource/*` | `satellite-provider/` |
|
||||
| `/api/detect/*` | `detections/` (Cython) |
|
||||
| `/api/loader/*` | `loader/` (Cython) |
|
||||
| `/api/gps-denied-desktop/*` | `gps-denied-desktop/` |
|
||||
| `/api/gps-denied-onboard/*` | `gps-denied-onboard/` |
|
||||
| `/api/autopilot/*` | `autopilot/` |
|
||||
|
||||
## Security
|
||||
|
||||
- **Token storage**: in-memory only (`accessToken: string | null` at module scope). Survives in-tab navigations but not full reloads. The refresh path (`POST /api/admin/auth/refresh` with `credentials: 'include'`) implies the refresh token rides in an HttpOnly cookie set by the `admin/` service. The bearer access token is therefore short-lived and never persisted to `localStorage`. Acceptable XSS posture.
|
||||
- **401 handling**: redirects to `/login` via `window.location.href` (full page reload) — clears any in-memory state including the bearer.
|
||||
- **Race condition**: two parallel requests that both 401 will both call `refreshToken()` independently — one will succeed, one may receive a stale token mid-flight. Track for B3/B4 audit; minor under the current usage but should be serialised in Step 8.
|
||||
- **No CSRF token**: relies on the bearer scheme only; `credentials: 'include'` is set only on `/refresh`, so other endpoints don't carry the cookie. Verify with `admin/` service contract during Step 6 `security_approach.md`.
|
||||
|
||||
## Tests
|
||||
|
||||
None.
|
||||
|
||||
## Notes / open questions
|
||||
|
||||
- The `Authorization` header is set BEFORE `refreshToken()` in the retry path, but `refreshToken()` mutates the module-level `accessToken` and the retry then `headers.set('Authorization', \`Bearer ${accessToken}\`)` reads the NEW token. Correct, but worth a comment.
|
||||
- `request` is typed `<T>` and trusts callers; a runtime schema validation layer (Zod, valibot) would be the right Step 8 hardening but is too heavy for testability scope.
|
||||
- `upload(url, formData)` does NOT set `Content-Type`, allowing the browser to compute the multipart boundary. This is intentional and correct.
|
||||
@@ -0,0 +1,73 @@
|
||||
# Module: `src/api/sse.ts`
|
||||
|
||||
> **Source**: `src/api/sse.ts` (25 lines)
|
||||
> **Topo batch**: B3 (depends on B2 leaf: `api/client` for `getToken()` only)
|
||||
|
||||
## Purpose
|
||||
|
||||
A 25-line wrapper around the browser's native `EventSource` that (a) appends the current bearer token as an `access_token` query parameter (since `EventSource` does not let callers set headers), (b) parses each `MessageEvent` payload as JSON, and (c) returns a cleanup function. Used by features that listen for server-pushed updates (annotations queue, flight ingestion progress, etc.).
|
||||
|
||||
## Public interface
|
||||
|
||||
```ts
|
||||
export function createSSE<T>(
|
||||
url: string,
|
||||
onMessage: (data: T) => void,
|
||||
onError?: (err: Event) => void,
|
||||
): () => void
|
||||
```
|
||||
|
||||
The returned function closes the underlying `EventSource`. Callers MUST call it on unmount to avoid leaking long-lived connections.
|
||||
|
||||
## Internal logic
|
||||
|
||||
1. `const token = getToken()` — read the current bearer from `api/client.ts`.
|
||||
2. Build `fullUrl`:
|
||||
- If `token` is non-null: append `access_token=<token>` using `&` if the URL already has a query string, `?` otherwise.
|
||||
- If `token` is null: use `url` as-is.
|
||||
3. `new EventSource(fullUrl)`.
|
||||
4. `source.onmessage = (e) => { try { onMessage(JSON.parse(e.data) as T) } catch { /* ignore */ } }`.
|
||||
- JSON parse errors are silently swallowed. The contract is that the server sends valid JSON; a malformed frame degrades to "skipped".
|
||||
5. `source.onerror = (e) => onError?.(e)` — forwarded straight through. The browser auto-reconnects by default; `onError` lets callers observe the disconnect.
|
||||
6. Return `() => source.close()`.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Internal**: `./client` — `getToken()`.
|
||||
- **External**: `EventSource` (browser global).
|
||||
|
||||
## Consumers (intra-repo)
|
||||
|
||||
From the §7a dependency graph:
|
||||
|
||||
- `src/features/annotations/AnnotationsSidebar.tsx` — subscribes to the annotations stream.
|
||||
- `src/features/flights/FlightsPage.tsx` — subscribes to flight ingestion / state updates.
|
||||
|
||||
## Data models
|
||||
|
||||
None defined here. The generic `T` is supplied by the caller.
|
||||
|
||||
## Configuration
|
||||
|
||||
URLs are passed in by callers (string-literal at call sites). The same testability remark as `api/client.ts` applies: a `VITE_API_BASE_URL` is the natural Step 4 fix.
|
||||
|
||||
## External integrations
|
||||
|
||||
Whichever backend exposes the SSE endpoint at the URL the caller provides. Per `nginx.conf`, the suite's `/api/*` reverse proxy forwards SSE traffic by default (no special EventSource-blocking config) — verify in Step 4.
|
||||
|
||||
## Security
|
||||
|
||||
- **Bearer in query string**: `access_token=<jwt>` ends up in browser-history URLs, server access logs, and proxy logs. This is a **known weakness of the EventSource API** — the API has no headers parameter, so cookie or query are the only options. The trade-off was made knowingly (SSE is a long-lived GET; the bearer is short-lived; nginx access logs are an internal-only artefact). Document in `security_approach.md` (Step 6) and consider rotating to a dedicated SSE-only short-lived token in Step 8.
|
||||
- **`getToken()` on connect, no refresh**: if the bearer rotates mid-session (via `client.ts`'s 401 retry path), the `EventSource` keeps using the old token and will eventually error. Callers must observe `onError` and reconnect. The current consumers (`AnnotationsSidebar`, `FlightsPage`) do NOT do this — they create the source once on mount. Flag for Step 4 / Step 8.
|
||||
- **Silent JSON parse error**: a single malformed frame is skipped without a `console.warn`. Acceptable for production noise reduction but obscures real backend bugs in dev. Defer.
|
||||
|
||||
## Tests
|
||||
|
||||
None.
|
||||
|
||||
## Notes / open questions
|
||||
|
||||
- **No reconnect / backoff logic** — relies on the browser's built-in EventSource auto-reconnect. The default is "keep retrying"; on a flaky connection this may produce a tight loop with backend logs. Confirm acceptable in Step 6 against the `annotations/` and `flights/` service rate-limit posture.
|
||||
- **Cleanup on token-less call**: `getToken()` returning `null` produces an unauthenticated `EventSource`. The backend should reject with `401`, the `EventSource` then errors, and `onError?` fires. The caller is expected to interpret this as "user logged out, stop subscribing". None of the current consumers do that explicitly; instead, the `ProtectedRoute` gate prevents `useEffect` from ever running while logged out, so the path is unreachable in practice. Document but no action needed.
|
||||
- The function is fully synchronous — does not return a `Promise`. The connection is initiated on call but the first message may arrive later. Consumers must handle the "no messages yet" UI state.
|
||||
- The query-string token assembly does NOT URL-encode the token. JWTs are URL-safe Base64 by default and contain only `A–Z, a–z, 0–9, -, _, .`, so this is safe for the current token shape. If the token format ever changes, add `encodeURIComponent`. Note for Step 8.
|
||||
@@ -0,0 +1,116 @@
|
||||
# Module: `src/auth/AuthContext.tsx`
|
||||
|
||||
> **Source**: `src/auth/AuthContext.tsx` (54 lines)
|
||||
> **Topo batch**: B3 (depends on B2 leaves: `api/client`, `types/index`)
|
||||
|
||||
## Purpose
|
||||
|
||||
The single source of truth for the SPA's authentication state. Wraps the bearer-token plumbing from `api/client.ts` in a React context, exposes `useAuth()` for any descendant component, and bootstraps the session on app start by attempting a refresh. Together with `ProtectedRoute.tsx` and `LoginPage.tsx`, this is the WPF-era `LoginWindow.xaml` + auth service replacement (`_docs/legacy/wpf-era.md` §3 / §4).
|
||||
|
||||
## Public interface
|
||||
|
||||
```ts
|
||||
interface AuthState {
|
||||
user: AuthUser | null
|
||||
loading: boolean
|
||||
login: (email: string, password: string) => Promise<void>
|
||||
logout: () => Promise<void>
|
||||
hasPermission: (perm: string) => boolean
|
||||
}
|
||||
|
||||
export function useAuth(): AuthState
|
||||
export function AuthProvider({ children }: { children: ReactNode }): JSX.Element
|
||||
```
|
||||
|
||||
`AuthContext` itself is module-private (`createContext<AuthState>(null!)`). Consumers must go through `useAuth()`.
|
||||
|
||||
## Internal logic
|
||||
|
||||
State:
|
||||
|
||||
- `user: AuthUser | null` — `null` when unauthenticated.
|
||||
- `loading: boolean` — `true` until the initial refresh attempt resolves (success or failure). Renders should gate on this.
|
||||
|
||||
**Bootstrap effect (mount-only)**:
|
||||
|
||||
```ts
|
||||
api.get<{ user: AuthUser; token: string }>('/api/admin/auth/refresh')
|
||||
.then(data => { setToken(data.token); setUser(data.user) })
|
||||
.catch(() => {})
|
||||
.finally(() => setLoading(false))
|
||||
```
|
||||
|
||||
The refresh endpoint is invoked with `credentials: 'include'` only inside `client.ts`'s **internal** `refreshToken()` helper — but here we go through the public `api.get()` path, which does NOT include credentials. **This is a real divergence**: `client.ts`'s internal `refreshToken()` (used in the 401 retry) sends the cookie; the bootstrap call in `AuthContext` does not. The endpoint must therefore accept the refresh either via cookie (then bootstrap fails silently for non-cookie clients — which is everyone after a hard reload) **or** via some other mechanism (a refresh token in `localStorage`, etc.). **Flag for Step 4 verification** against the `admin/` service contract; this is likely a real bug masking by silent `.catch`.
|
||||
|
||||
**`login(email, password)`**:
|
||||
|
||||
```ts
|
||||
const data = await api.post<{ token; user }>('/api/admin/auth/login', { email, password })
|
||||
setToken(data.token); setUser(data.user)
|
||||
```
|
||||
|
||||
Throws to caller (LoginPage) on bad credentials.
|
||||
|
||||
**`logout()`**:
|
||||
|
||||
```ts
|
||||
try { await api.post('/api/admin/auth/logout') } catch {}
|
||||
setToken(null); setUser(null)
|
||||
```
|
||||
|
||||
Network failure on logout is silently swallowed because we want to clear local auth state regardless.
|
||||
|
||||
**`hasPermission(perm)`**: returns `user?.permissions.includes(perm) ?? false`. The permission strings are not constrained at the type level — any string passes. Backend-defined.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Internal**:
|
||||
- `../api/client` — `api`, `setToken`.
|
||||
- `../types` — `AuthUser` type.
|
||||
- **External**: `react` (`createContext`, `useContext`, `useState`, `useCallback`, `useEffect`, `ReactNode`).
|
||||
|
||||
## Consumers (intra-repo)
|
||||
|
||||
From the §7a dependency graph:
|
||||
|
||||
- `src/auth/ProtectedRoute.tsx` — gates routed children on `user !== null`.
|
||||
- `src/components/Header.tsx` — shows current user, exposes Logout.
|
||||
- `src/features/login/LoginPage.tsx` — calls `login(...)`, redirects on success.
|
||||
- `src/App.tsx` — mounts `AuthProvider` near the root.
|
||||
|
||||
(Other features rely on the bearer token implicitly via `api/client.ts` — they don't import `useAuth` directly.)
|
||||
|
||||
## Data models
|
||||
|
||||
`AuthUser` (from `src/types/index.ts`) — see `_docs/02_document/modules/src__types__index.md`. Carries at minimum `id`, `email`, `permissions: string[]`.
|
||||
|
||||
## Configuration
|
||||
|
||||
Endpoints (string-literal): `/api/admin/auth/refresh`, `/api/admin/auth/login`, `/api/admin/auth/logout`. Routed by `nginx.conf` to the `admin/` service.
|
||||
|
||||
No env vars consumed directly — token storage policy is defined in `client.ts` (in-memory; not persisted to `localStorage`).
|
||||
|
||||
## External integrations
|
||||
|
||||
`admin/` (.NET) auth service via `/api/admin/auth/{refresh,login,logout}`.
|
||||
|
||||
## Security
|
||||
|
||||
- **In-memory token only**: the bearer is held by `client.ts` at module scope. Survives intra-tab navigation, lost on hard reload — at which point the refresh path must restore it (currently broken per the bootstrap-effect note above).
|
||||
- **`hasPermission` runs client-side only**: the server is the authority; `hasPermission` is for UI affordances (hide vs. show buttons). The backend MUST re-check permissions on every endpoint. Document in `security_approach.md` (Step 6).
|
||||
- **Silent error swallowing on bootstrap and logout** is intentional but obscures real failures. A dev-only `console.error` would help during the testability pass; do not add a user-visible toast (silent recovery is the correct UX).
|
||||
- **No XSS exfiltration risk for the bearer**: in-memory only, never written to `localStorage` or a non-HttpOnly cookie. (Confirmed in `client.ts` doc.)
|
||||
|
||||
## Tests
|
||||
|
||||
None.
|
||||
|
||||
## Notes / open questions
|
||||
|
||||
- **Bootstrap-vs-refresh divergence** (above) — the highest-priority flag in this module. Either:
|
||||
1. The refresh endpoint accepts an Authorization-less, cookie-bearing call → confirm the `admin/` service sets an HttpOnly cookie on `/login` and the cookie path matches `/api/admin/auth/refresh`. The `api.get()` path in `client.ts` does NOT send `credentials: 'include'`, so this currently CANNOT work. → **likely bug**.
|
||||
2. Or the bootstrap should be calling the internal `refreshToken()` helper, which is currently not exported.
|
||||
Either way, this needs a Step 4 fix (export `refreshToken()` and call it here, or change `api.get()` to allow per-call `credentials`).
|
||||
- **`AuthContext = createContext<AuthState>(null!)`**: the non-null assertion means `useAuth()` will throw at the destructuring site if it's used outside `AuthProvider`. Acceptable given `App.tsx` mounts `AuthProvider` at the top, but a guard `if (!ctx) throw new Error(...)` would be friendlier. Defer.
|
||||
- The `loading` flag is never re-set to `true` after the initial bootstrap. `login` and `logout` complete synchronously from the React tree's perspective (the `await` is inside the callback). If a future requirement demands a "logging in…" indicator, it would need its own state. Note for Step 8.
|
||||
- `useAuth` returns the raw context value (no memoisation wrapper). React 18+ behaviour means `<AuthProvider>` re-renders all `useAuth` consumers on every state update — fine here because there's no high-frequency state.
|
||||
@@ -0,0 +1,101 @@
|
||||
# Module: `src/auth/ProtectedRoute.tsx`
|
||||
|
||||
> **Source**: `src/auth/ProtectedRoute.tsx` (19 lines)
|
||||
> **Topo batch**: B4 (depends on B3: `auth/AuthContext`)
|
||||
|
||||
## Purpose
|
||||
|
||||
A tiny route guard that gates its children behind an authenticated session.
|
||||
While `AuthContext` is bootstrapping (`loading === true`) it shows a spinner;
|
||||
when the bootstrap finishes with no user it redirects to `/login`; otherwise
|
||||
it renders its children. Mounted exactly once in `App.tsx` between
|
||||
`AuthProvider` and `FlightProvider` so every authenticated page benefits
|
||||
from it. WPF parallel: the implicit "no LoginWindow open ⇒ MainWindow"
|
||||
gate (`_docs/legacy/wpf-era.md` §4).
|
||||
|
||||
## Public interface
|
||||
|
||||
```ts
|
||||
interface Props { children: ReactNode }
|
||||
export default function ProtectedRoute(props: Props): JSX.Element
|
||||
```
|
||||
|
||||
Always returns a `JSX.Element` — never `null`. The three rendered shapes
|
||||
are:
|
||||
|
||||
1. Spinner (centered `<div>` with the orange ring) while `loading`.
|
||||
2. `<Navigate to="/login" replace />` when `loading === false && user == null`.
|
||||
3. `<>{children}</>` otherwise.
|
||||
|
||||
`replace` is intentional: it rewrites the history entry so the back
|
||||
button does not return to a protected route the user was bounced off.
|
||||
|
||||
## Internal logic
|
||||
|
||||
- Single hook call: `const { user, loading } = useAuth()`. No local state.
|
||||
- Branch order matters — `loading` is checked before `user` so a freshly
|
||||
reloaded tab never renders the login redirect during the in-flight
|
||||
refresh attempt. (See the open `AuthContext` bootstrap-vs-refresh
|
||||
divergence flagged in `src__auth__AuthContext.md`; if that bug is
|
||||
fixed the spinner duration becomes accurate.)
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Internal**: `./AuthContext` — `useAuth`.
|
||||
- **External**: `react-router-dom` (`Navigate`), `react` (`ReactNode` type only).
|
||||
|
||||
## Consumers (intra-repo)
|
||||
|
||||
From the §7a dependency graph:
|
||||
|
||||
- `src/App.tsx` — wraps the entire authenticated route tree:
|
||||
`AuthProvider → ProtectedRoute → FlightProvider → Header + nested Routes`.
|
||||
|
||||
Not used anywhere else; the SPA has a single protected zone.
|
||||
|
||||
## Data models
|
||||
|
||||
None.
|
||||
|
||||
## Configuration
|
||||
|
||||
The `/login` redirect target is hardcoded. Matches the public route
|
||||
declared in `App.tsx`. If the public route is ever renamed, update both
|
||||
sites.
|
||||
|
||||
The spinner uses Tailwind tokens `bg-az-bg`, `border-az-orange`
|
||||
(defined in `src/index.css`).
|
||||
|
||||
## External integrations
|
||||
|
||||
None directly. Indirectly relies on whatever `AuthContext` calls during
|
||||
bootstrap — currently `GET /api/admin/auth/refresh`.
|
||||
|
||||
## Security
|
||||
|
||||
- **No token check is duplicated here** — relies entirely on `AuthContext`.
|
||||
The component cannot be confused into rendering protected children
|
||||
before the bootstrap resolves because `loading` defaults to `true` in
|
||||
`AuthProvider`.
|
||||
- Backend authority is unchanged — this is a UI affordance only. Every
|
||||
request the children make MUST also be enforced server-side.
|
||||
- The redirect uses `Navigate`, so query params on the original URL are
|
||||
lost. Acceptable today (no protected route relies on them); flag if a
|
||||
future "deep-link after login" UX appears.
|
||||
|
||||
## Tests
|
||||
|
||||
None.
|
||||
|
||||
## Notes / open questions
|
||||
|
||||
- The spinner has no `role="status"` or accessible label — screen readers
|
||||
hear nothing while the bootstrap runs. Cosmetic; flag for Step 4
|
||||
verification against `_docs/ui_design/README.md` accessibility notes.
|
||||
- No timeout on the `loading` state — if `AuthContext`'s bootstrap
|
||||
somehow never resolves (e.g., the refresh endpoint hangs), the user
|
||||
sees an infinite spinner. `client.ts` does not currently set a
|
||||
request timeout either; flag jointly with Step 4.
|
||||
- The `<>{children}</>` Fragment wrap is intentional: returning `children`
|
||||
directly would make the type `ReactNode` rather than `JSX.Element` and
|
||||
would not satisfy the route element slot in `react-router-dom@7`.
|
||||
@@ -0,0 +1,74 @@
|
||||
# Module: `src/components/ConfirmDialog.tsx`
|
||||
|
||||
> **Source**: `src/components/ConfirmDialog.tsx` (47 lines)
|
||||
> **Topo batch**: B3 (uses `react-i18next` only; no intra-repo deps)
|
||||
|
||||
## Purpose
|
||||
|
||||
A controlled, single-message confirm dialog used wherever the SPA needs an "Are you sure?" gate. Replaces the legacy WPF `MessageBox.Show(..., MessageBoxButton.YesNo, ...)` pattern (`_docs/legacy/wpf-era.md` §4 / §"What survived").
|
||||
|
||||
## Public interface
|
||||
|
||||
```ts
|
||||
interface Props {
|
||||
open: boolean
|
||||
title: string
|
||||
message?: string
|
||||
onConfirm: () => void
|
||||
onCancel: () => void
|
||||
}
|
||||
export default function ConfirmDialog(props: Props): JSX.Element | null
|
||||
```
|
||||
|
||||
When `open === false`, returns `null`. When `open === true`, renders a centered modal over a dimmed backdrop. The component is fully controlled — it owns no `open` state itself.
|
||||
|
||||
## Internal logic
|
||||
|
||||
- **Auto-focus**: when `open` flips to `true`, the Cancel button is focused via `cancelRef.current?.focus()` (see `useEffect` keyed on `open`). This makes Cancel the default keyboard target — a common pattern for destructive confirmations.
|
||||
- **Escape-to-cancel**: a `keydown` handler is attached to `window` while `open === true`; pressing `Escape` calls `onCancel()`. The listener is removed on unmount or when `open` flips to `false`. This is the **only** dismiss path other than the explicit Cancel/Confirm buttons (no backdrop click handler).
|
||||
- **Translation**: button labels use `t('common.cancel')` and `t('common.confirm')`. Title and message are passed in by the caller — the caller is responsible for translation.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Internal**: none.
|
||||
- **External**: `react` (`useEffect`, `useRef`), `react-i18next` (`useTranslation`).
|
||||
|
||||
## Consumers (intra-repo)
|
||||
|
||||
From the §7a dependency graph in `_docs/02_document/00_discovery.md`:
|
||||
|
||||
- `src/features/admin/AdminPage.tsx` — confirm before deleting users.
|
||||
- `src/features/annotations/MediaList.tsx` — confirm before deleting media.
|
||||
- `src/features/flights/FlightsPage.tsx` — confirm before deleting a flight.
|
||||
- `src/features/dataset/DatasetPage.tsx` — confirm before deleting dataset items.
|
||||
|
||||
(`HelpModal.tsx` is the *non-confirm* sibling; it does NOT use `ConfirmDialog` and notably does **not** have Escape-to-close — see `src__components__HelpModal.md` §Notes.)
|
||||
|
||||
## Data models
|
||||
|
||||
None.
|
||||
|
||||
## Configuration
|
||||
|
||||
Tailwind tokens used: `bg-az-panel`, `border-az-border`, `text-az-text`, `bg-az-red`, `bg-az-bg`, `text-white`. All defined in `src/index.css` (per `_docs/02_document/00_discovery.md` §2a).
|
||||
|
||||
`z-[100]` is the chosen stacking layer. No other modal currently competes with it; if a third-party library introduces a portal at `z-[200]+`, layering will need a docs entry.
|
||||
|
||||
## External integrations
|
||||
|
||||
None.
|
||||
|
||||
## Security
|
||||
|
||||
- **No backdrop dismissal**: clicking outside the dialog does NOT cancel. Combined with Escape-to-cancel and a default-focused Cancel button, this gives a deliberate, keyboard-safe destructive-action flow.
|
||||
- **No `aria-modal` / role="dialog"**: not annotated for screen readers; flag for Step 4 verification against the `_docs/ui_design/README.md` §"Confirmation dialogs" spec (which specifies modal semantics).
|
||||
|
||||
## Tests
|
||||
|
||||
None.
|
||||
|
||||
## Notes / open questions
|
||||
|
||||
- The "destructive" colour (`bg-az-red`) is hardcoded into the Confirm button. Some callers use `ConfirmDialog` for non-destructive confirms (e.g. flight selection in some flows — verify in B7); a future variant prop (`destructive: boolean`) would be cleaner. Defer to Step 8.
|
||||
- No `width` prop — the dialog is fixed at `w-80` (320px). On the mobile breakpoint defined in `_docs/ui_design/README.md` §"Responsive Breakpoints" (640px), this fits, but very long titles or multi-line messages will overflow. Flag for Step 4 cosmetic verification.
|
||||
- Escape handler attaches to `window`, not the dialog DOM. If two `ConfirmDialog`s are mounted simultaneously (the SPA never does this today, but it's not enforced), both would call their `onCancel()` on a single Escape press. Acceptable under current usage.
|
||||
@@ -0,0 +1,99 @@
|
||||
# Module: `src/components/DetectionClasses.tsx`
|
||||
|
||||
> **Source**: `src/components/DetectionClasses.tsx` (99 lines)
|
||||
> **Topo batch**: B3 (depends on B2 leaves: `api/client`, `features/annotations/classColors`, `types/index`)
|
||||
|
||||
## Purpose
|
||||
|
||||
A side-panel widget that lets the annotator pick a detection class (1–9 or click) and a photo mode (`Regular`, `Winter`, `Night`). Loads the class catalogue from the backend and falls back to a hardcoded list when the API returns empty / errors. Replaces the legacy WPF detection-class picker referenced in `_docs/legacy/wpf-era.md` §"What survived".
|
||||
|
||||
## Public interface
|
||||
|
||||
```ts
|
||||
interface Props {
|
||||
selectedClassNum: number
|
||||
onSelect: (classNum: number) => void
|
||||
photoMode: number
|
||||
onPhotoModeChange: (mode: number) => void
|
||||
}
|
||||
export default function DetectionClasses(props: Props): JSX.Element
|
||||
```
|
||||
|
||||
Fully controlled — the parent owns `selectedClassNum` and `photoMode`. The current contract for `photoMode` values is integer offsets `0` (Regular), `20` (Winter), `40` (Night), matching the `photoMode` field of `DetectionClass` (`src/types/index.ts`) and the offsets baked into `FALLBACK_CLASSES` below.
|
||||
|
||||
## Internal logic
|
||||
|
||||
- **Class catalogue load** (mount-only `useEffect`):
|
||||
- `api.get<DetectionClass[]>('/api/annotations/classes')`.
|
||||
- On a non-empty array → `setClasses(list)`.
|
||||
- On an empty array OR a thrown error → `setClasses(FALLBACK_CLASSES)`.
|
||||
- **`FALLBACK_CLASSES`** is a module-private 3 × |`FALLBACK_CLASS_NAMES`| matrix:
|
||||
- For each mode offset in `[0, 20, 40]`, build one class entry per name in `FALLBACK_CLASS_NAMES` (imported from `features/annotations/classColors.ts`).
|
||||
- Each entry: `{ id: i + modeOffset, name, shortName: name.slice(0, 3), color: getClassColor(i), maxSizeM: 10, photoMode: modeOffset }`.
|
||||
- This means: in offline / API-down mode, the ID range is `0–N-1` (Regular), `20–20+N-1` (Winter), `40–40+N-1` (Night). The backend's class IDs MUST follow the same convention or fallback↔backend handoff yields ID collisions. Confirm in Step 4 via the `annotations/` service contract.
|
||||
- **Numeric hotkeys 1–9** (effect keyed on `[classes, photoMode, onSelect]`):
|
||||
- `keydown` on `window`. `parseInt(e.key)` → if 1–9, picks `classes[(num - 1) + photoMode]`.
|
||||
- **Bug-shaped**: `photoMode` is `0 | 20 | 40` (an *offset*), not a row count. `classes[idx + 0]` is correct for Regular; for Winter/Night the index `idx + 20` / `idx + 40` is meaningful only when `classes` is in the contiguous `[0..N-1, 20..20+N-1, 40..40+N-1]` shape that `FALLBACK_CLASSES` produces. **If the backend returns its classes in a different order**, hotkey 1–9 will pick the wrong class. Verify backend ordering in Step 4 — this is the principal correctness risk in this module. Flag.
|
||||
- **Auto-select first class on mode change** (effect keyed on `[classes, photoMode, selectedClassNum, onSelect]`):
|
||||
- Filter `classes` to the active `photoMode`.
|
||||
- If `selectedClassNum` is not within that filtered set, call `onSelect(modeClasses[0].id)`.
|
||||
- This guarantees the parent always holds a class ID consistent with the selected photo mode.
|
||||
- **Render**:
|
||||
- Class list — only entries whose `photoMode` matches the active mode.
|
||||
- Photo-mode bar — three buttons (Sunny / Snowflake / Moon icons) for Regular / Winter / Night.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Internal**:
|
||||
- `../api/client` — `api.get<T>()`.
|
||||
- `../features/annotations/classColors` — `getClassColor(i)`, `FALLBACK_CLASS_NAMES`.
|
||||
- `../types` — `DetectionClass` type.
|
||||
- **External**: `react`, `react-i18next`, `react-icons/md`, `react-icons/fa`.
|
||||
|
||||
## Consumers (intra-repo)
|
||||
|
||||
From the §7a dependency graph:
|
||||
|
||||
- `src/features/annotations/AnnotationsPage.tsx`
|
||||
- `src/features/dataset/DatasetPage.tsx`
|
||||
|
||||
This is the **canonical example** of the cross-layer import flagged in `_docs/02_document/00_discovery.md` §8: a `components/` (shared) module importing from `features/annotations/`. Two clean fixes are in scope for Step 4 / Step 8:
|
||||
|
||||
1. Lift `classColors.ts` into `src/components/detection/` (or `src/shared/`) and update the two consumers.
|
||||
2. Or: move `DetectionClasses` itself into `src/features/annotations/` since both consumers are in `features/`.
|
||||
|
||||
## Data models
|
||||
|
||||
`DetectionClass` (from `src/types/index.ts`) — see `_docs/02_document/modules/src__types__index.md`.
|
||||
|
||||
`FALLBACK_CLASSES` is module-private; see Internal logic above.
|
||||
|
||||
## Configuration
|
||||
|
||||
Endpoint: `/api/annotations/classes` — string-literal URL (testability fix scheduled for Step 4).
|
||||
|
||||
Photo-mode value set is `{0, 20, 40}` — hardcoded, mirrored by `FALLBACK_CLASSES`. If the backend grows a fourth mode (e.g. thermal, IR), every consumer of `photoMode` will need a coordinated change.
|
||||
|
||||
Tailwind tokens: `bg-az-orange` (Regular), `bg-az-blue` (Winter), `bg-purple-600` (Night). Defined in `src/index.css`.
|
||||
|
||||
## External integrations
|
||||
|
||||
- HTTP `GET /api/annotations/classes` → `DetectionClass[]`. Backed by the `annotations/` service (`.NET`) per `nginx.conf`.
|
||||
|
||||
## Security
|
||||
|
||||
- **Silent failure on class load**: `.catch(() => setClasses(FALLBACK_CLASSES))` swallows the error and the user sees the fallback. Acceptable for UX continuity, but the lack of any user-visible signal means a misconfigured `/api/annotations/classes` deploy could go unnoticed in prod. Flag for Step 6 `security_approach.md` / Step 8.
|
||||
- No input that flows back to the server here.
|
||||
- The `getClassColor(i)` palette is deterministic; no PII.
|
||||
|
||||
## Tests
|
||||
|
||||
None.
|
||||
|
||||
## Notes / open questions
|
||||
|
||||
- **`getPhotoModeSuffix` redundancy** (carry-over from B1): `classColors.ts` exposes `getPhotoModeSuffix()` that derives the same suffix the typed `DetectionClass.photoMode` field already encodes. Once `classColors.ts` is repositioned (see Consumers), `getPhotoModeSuffix` is a deletion candidate. Defer to Step 8.
|
||||
- **`FALLBACK_CLASS_NAMES.length`** is implicitly assumed to be ≤ 9 by the hotkey code (only 1–9 are bound). If the catalogue grows to 10+ entries, hotkeys can no longer cover the tail. Acceptable for now.
|
||||
- **Mode-button colours don't use `az-` tokens for Night** (`bg-purple-600`, `text-purple-400` instead of an `az-purple` token). Cosmetic inconsistency; flag for Step 4 against `_docs/ui_design/README.md` colour palette.
|
||||
- The class list is rendered with `1.`, `2.`, … prefixes derived from `i+1` — so the hotkey number always matches the visible label inside the active mode. Good.
|
||||
- Does not handle modifier keys (`Shift`, `Ctrl`) on numeric hotkeys; pressing `Shift+5` will trigger the `5` branch. Fine for now.
|
||||
@@ -0,0 +1,106 @@
|
||||
# Module: `src/components/FlightContext.tsx`
|
||||
|
||||
> **Source**: `src/components/FlightContext.tsx` (52 lines)
|
||||
> **Topo batch**: B3 (depends on B2 leaves: `api/client`, `types/index`)
|
||||
|
||||
## Purpose
|
||||
|
||||
A React context that holds the SPA's currently-selected flight and the cached flight list, keeps the selection in sync with the per-user backend setting, and exposes a refresh trigger. Sibling of `AuthContext.tsx` — both are mounted near the root (`App.tsx`) so any feature page can access flight state without prop-drilling. Replaces the legacy WPF "current mission" singleton (`_docs/legacy/wpf-era.md` §"What survived").
|
||||
|
||||
## Public interface
|
||||
|
||||
```ts
|
||||
interface FlightState {
|
||||
flights: Flight[]
|
||||
selectedFlight: Flight | null
|
||||
selectFlight: (f: Flight | null) => void
|
||||
refreshFlights: () => Promise<void>
|
||||
}
|
||||
|
||||
export function useFlight(): FlightState
|
||||
export function FlightProvider({ children }: { children: ReactNode }): JSX.Element
|
||||
```
|
||||
|
||||
`FlightContext` itself is module-private. Consumers must go through `useFlight()`.
|
||||
|
||||
## Internal logic
|
||||
|
||||
State:
|
||||
|
||||
- `flights: Flight[]` — most recent list returned by `GET /api/flights?pageSize=1000`.
|
||||
- `selectedFlight: Flight | null` — the active flight, or `null` if none. Survives across pages because the provider is mounted above the route tree.
|
||||
|
||||
**`refreshFlights()`** (`useCallback`, no deps):
|
||||
|
||||
```ts
|
||||
const data = await api.get<{ items: Flight[] }>('/api/flights?pageSize=1000')
|
||||
setFlights(data.items ?? [])
|
||||
```
|
||||
|
||||
Errors are silently swallowed (`try { ... } catch {}`). `pageSize=1000` is a hardcoded ceiling — see Configuration.
|
||||
|
||||
**Bootstrap effect** (`useEffect` keyed on `[refreshFlights]`, runs once because `refreshFlights` is `useCallback([])`):
|
||||
|
||||
1. `refreshFlights()` (no `await` — runs in parallel with #2).
|
||||
2. `api.get<UserSettings>('/api/annotations/settings/user')` →
|
||||
- if `settings?.selectedFlightId` is truthy: `api.get<Flight>('/api/flights/${settings.selectedFlightId}')` → `setSelectedFlight(f)`.
|
||||
- errors at every step silently swallowed.
|
||||
|
||||
The selected flight is therefore looked up by **its own GET**, not by indexing into the cached `flights` list. This is intentional — the user might have a `selectedFlightId` that fell off the first 1000 flights.
|
||||
|
||||
**`selectFlight(f)`** (`useCallback`, no deps):
|
||||
|
||||
```ts
|
||||
setSelectedFlight(f)
|
||||
api.put('/api/annotations/settings/user', { selectedFlightId: f?.id ?? null }).catch(() => {})
|
||||
```
|
||||
|
||||
Optimistic — local state updates immediately; the persisted setting is fire-and-forget. If the PUT fails, the next reload will fall back to the previously-stored ID and the user's selection silently reverts. Flag for Step 4.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Internal**:
|
||||
- `../api/client` — `api`.
|
||||
- `../types` — `Flight`, `UserSettings` types.
|
||||
- **External**: `react` (`createContext`, `useContext`, `useState`, `useEffect`, `useCallback`, `ReactNode`).
|
||||
|
||||
## Consumers (intra-repo)
|
||||
|
||||
From the §7a dependency graph:
|
||||
|
||||
- `src/App.tsx` — mounts `FlightProvider` inside `ProtectedRoute` and above the route tree (so `selectedFlight` survives navigation between `/flights`, `/annotations`, `/dataset`).
|
||||
- `src/components/Header.tsx` — displays the currently-selected flight name.
|
||||
- `src/features/flights/FlightsPage.tsx` — the primary editor; calls `selectFlight` on row click.
|
||||
- `src/features/annotations/MediaList.tsx` — filters media by `selectedFlight.id`.
|
||||
- `src/features/dataset/DatasetPage.tsx` — same.
|
||||
|
||||
## Data models
|
||||
|
||||
- `Flight` and `UserSettings` from `src/types/index.ts` — see `_docs/02_document/modules/src__types__index.md`.
|
||||
|
||||
## Configuration
|
||||
|
||||
Endpoints (string-literal): `/api/flights?pageSize=1000`, `/api/flights/{id}`, `/api/annotations/settings/user`. Routed by `nginx.conf` to the `flights/` and `annotations/` services.
|
||||
|
||||
`pageSize=1000` is a **hardcoded ceiling** — if the system ever has >1000 flights, the cache is silently truncated. The `flights/` service contract probably caps at 1000; verify and document in `data_parameters.md` (Step 6). Flag.
|
||||
|
||||
## External integrations
|
||||
|
||||
- `flights/` (.NET) — `GET /api/flights`, `GET /api/flights/{id}`.
|
||||
- `annotations/` (.NET) — `GET /api/annotations/settings/user`, `PUT /api/annotations/settings/user`. The user-settings store is reused for the selected-flight pointer; this is a slight abstraction leak (selected flight is logically a UI-state preference, not an annotation setting), but it works as long as `UserSettings` keeps a `selectedFlightId` field.
|
||||
|
||||
## Security
|
||||
|
||||
- **No auth checks here** — relies on `api/client.ts` to inject the bearer; backend enforces visibility.
|
||||
- **Silent failure on every async call** — same caveat as `AuthContext`. A misconfigured `/api/flights` will leave the user with an empty list and no error indication. Flag for Step 6 `security_approach.md` and Step 8 hardening.
|
||||
|
||||
## Tests
|
||||
|
||||
None.
|
||||
|
||||
## Notes / open questions
|
||||
|
||||
- **Race**: bootstrap fires `refreshFlights()` AND the user-settings GET in parallel. If the user-settings GET resolves first with a `selectedFlightId` that's not in the 1000 cached flights, the per-flight GET still succeeds. If the 1000 list is somehow stale and the per-flight GET 404s, `selectedFlight` stays `null` and the user sees nothing selected. Acceptable but worth documenting.
|
||||
- **`selectFlight(null)` PUTs `{ selectedFlightId: null }`** — this clears the persisted preference. Confirm the `annotations/` service treats this as "unset" and not as an error or no-op. Flag for Step 4.
|
||||
- **No realtime invalidation**: if another tab / user creates a flight, this client won't know until the next `refreshFlights()` call. The SPA also has SSE (`api/sse.ts`) but does NOT subscribe to flight updates. Mark as a Step 8 / future-feature hook.
|
||||
- **`useCallback([])` for `refreshFlights`** is fine because `setFlights` is stable. The empty deps array means the bootstrap effect fires exactly once (as intended) — but ESLint with `react-hooks/exhaustive-deps` would still flag both `useCallback`s for missing `setFlights` (technically stable, but the linter doesn't know). Acceptable; project-wide ESLint config does not currently enforce.
|
||||
@@ -0,0 +1,152 @@
|
||||
# Module: `src/components/Header.tsx`
|
||||
|
||||
> **Source**: `src/components/Header.tsx` (133 lines)
|
||||
> **Topo batch**: B4 (depends on B3: `auth/AuthContext`, `components/FlightContext`, `components/HelpModal`, `types/index`)
|
||||
|
||||
## Purpose
|
||||
|
||||
The persistent top navigation bar of the authenticated SPA. Combines
|
||||
five concerns into one component: brand mark, currently-selected-flight
|
||||
dropdown, top-level navigation links (permission-gated), session info
|
||||
(user email + Logout), language toggle (EN ↔ UA), and a `?` button that
|
||||
opens `HelpModal`. Also renders a duplicate bottom-nav on the mobile
|
||||
breakpoint. Replaces the legacy WPF top ribbon + window chrome
|
||||
(`_docs/legacy/wpf-era.md` §4 / §"What survived").
|
||||
|
||||
## Public interface
|
||||
|
||||
```ts
|
||||
export default function Header(): JSX.Element
|
||||
```
|
||||
|
||||
No props — Header reads everything it needs from `AuthContext`,
|
||||
`FlightContext`, and `react-i18next`. Mounted exactly once in `App.tsx`
|
||||
above the protected route tree.
|
||||
|
||||
## Internal logic
|
||||
|
||||
- **Local state**:
|
||||
- `showDropdown: boolean` — flight selector open/closed.
|
||||
- `filter: string` — text filter for the flight selector list.
|
||||
- `showHelp: boolean` — controls the `HelpModal` `open` prop.
|
||||
- `dropdownRef: RefObject<HTMLDivElement>` — used to detect outside
|
||||
clicks.
|
||||
- **Outside-click effect**: registers a `mousedown` listener on `document`
|
||||
while mounted; if the event target is not inside `dropdownRef.current`,
|
||||
closes the dropdown. Listener is removed on unmount. (Always-on, even
|
||||
while the dropdown is closed — cheap, but not the most surgical
|
||||
pattern; flag to consider gating on `showDropdown` in Step 8.)
|
||||
- **Filtered flights**: `flights.filter(f => f.name.toLowerCase().includes(filter.toLowerCase()))`
|
||||
— case-insensitive substring match on the flight name. Empty filter
|
||||
shows everything.
|
||||
- **Logout**: `await logout(); navigate('/login')`. Always navigates,
|
||||
even if `logout()` throws (it never does — `AuthContext.logout` swallows
|
||||
network errors by design).
|
||||
- **Language toggle**: `i18n.changeLanguage(i18n.language === 'en' ? 'ua' : 'en')`.
|
||||
Same two-language assumption as `HelpModal` (treats every non-`'ua'`
|
||||
value as English-equivalent). The toggle button label is the
|
||||
*target* language ("UA" while EN is active, "EN" while UA is active).
|
||||
- **Permission-gated nav** (`navItems`):
|
||||
|
||||
| `to` | `label` key | `perm` |
|
||||
|---|---|---|
|
||||
| `/flights` | `nav.flights` | `FL` |
|
||||
| `/annotations` | `nav.annotations` | `ANN` |
|
||||
| `/dataset` | `nav.dataset` | `DATASET` |
|
||||
| `/admin` | `nav.admin` | `ADM` |
|
||||
|
||||
`Settings` (`/settings`) is always rendered — no permission gate.
|
||||
Filter applied via `navItems.filter(n => hasPermission(n.perm))`.
|
||||
- **Layout**: a single `<header>` containing brand → flight dropdown →
|
||||
primary nav (`hidden sm:flex`) → spacer (`flex-1`) → user email
|
||||
(`hidden sm:block`) → language toggle → `?` → `⚙` (settings link) →
|
||||
logout button. A second `<nav>` element below is `sm:hidden` and
|
||||
positions itself fixed at the bottom of the viewport — the mobile
|
||||
nav. Both navs share the same filter logic.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Internal**:
|
||||
- `../auth/AuthContext` — `useAuth` (user, logout, hasPermission).
|
||||
- `./FlightContext` — `useFlight` (flights, selectedFlight, selectFlight).
|
||||
- `./HelpModal` — opens on `?` click.
|
||||
- `../types` — `Flight` type for the dropdown row.
|
||||
- **External**: `react-router-dom` (`NavLink`, `useNavigate`),
|
||||
`react-i18next` (`useTranslation`),
|
||||
`react` (`useState`, `useRef`, `useEffect`).
|
||||
|
||||
## Consumers (intra-repo)
|
||||
|
||||
- `src/App.tsx` — mounted inside `ProtectedRoute → FlightProvider`.
|
||||
|
||||
No other intra-repo consumer; `Header` is a top-level chrome component.
|
||||
|
||||
## Data models
|
||||
|
||||
The `navItems` array is a module-private literal of
|
||||
`{ to: string; label: string; perm: string }`. The filtered `flights`
|
||||
list is `Flight[]` (from `types/index.ts`).
|
||||
|
||||
## Configuration
|
||||
|
||||
- **i18n keys consumed**: `nav.flights`, `nav.annotations`, `nav.dataset`,
|
||||
`nav.admin`, `nav.logout`. (Verified to exist in `src/i18n/en.json`.)
|
||||
The filter placeholder ("Filter…") and the empty-state ("— Select
|
||||
Flight —", "No flights") are hardcoded strings — flag for Step 4.
|
||||
- **Tailwind tokens**: `bg-az-header`, `border-az-border`, `bg-az-panel`,
|
||||
`text-az-text`, `text-az-muted`, `text-az-orange`, `text-az-red`,
|
||||
`bg-az-bg`. Defined in `src/index.css`.
|
||||
- **Breakpoint**: `sm:` from Tailwind defaults to 640px — matches the
|
||||
responsive-breakpoint spec in `_docs/ui_design/README.md`.
|
||||
- **Permission strings**: `FL`, `ANN`, `DATASET`, `ADM`. Backend-defined
|
||||
by the `admin/` service; treated as opaque strings here.
|
||||
|
||||
## External integrations
|
||||
|
||||
None directly. Triggers `logout()` which calls `POST /api/admin/auth/logout`
|
||||
inside `AuthContext`, and `selectFlight()` which calls `PUT /api/annotations/settings/user`
|
||||
inside `FlightContext`.
|
||||
|
||||
## Security
|
||||
|
||||
- `hasPermission(perm)` is **client-side advisory** — a user with the
|
||||
`/admin` route URL can navigate there without going through the nav
|
||||
link. The backend `admin/` service is the authority. Document in
|
||||
`security_approach.md` (Step 6).
|
||||
- The flight-selector dropdown displays every flight returned by
|
||||
`GET /api/flights?pageSize=1000` — there is no permission check here.
|
||||
If `flights/` ever returns flights the user should not see, this
|
||||
component would leak them. Trust the backend filter.
|
||||
- `user?.email` is rendered raw in the header — React JSX-escapes it,
|
||||
so XSS via a malicious email is not possible at this layer, but
|
||||
validate that the `admin/` service enforces email format.
|
||||
|
||||
## Tests
|
||||
|
||||
None.
|
||||
|
||||
## Notes / open questions
|
||||
|
||||
- **Outside-click listener is always attached** — slightly wasteful when
|
||||
the dropdown is closed. Gating on `showDropdown` would also remove a
|
||||
closure capture. Defer to Step 8.
|
||||
- **Dropdown is not keyboard-accessible**: no `role="combobox"`, no
|
||||
`aria-expanded`, no Esc-to-close, focus does not move into the filter
|
||||
input on open beyond `autoFocus` (which works only the first time
|
||||
the input mounts). Flag against `_docs/ui_design/README.md` keyboard
|
||||
shortcuts for Step 4.
|
||||
- **Mobile bottom nav duplicates `navItems`** twice in source — DRY win
|
||||
by extracting a `<NavSet items={...}/>` subcomponent, but a deferral
|
||||
candidate.
|
||||
- **Hardcoded English strings** ("AZAION", "— Select Flight —",
|
||||
"Filter...", "No flights"). Brand mark is intentional; the others
|
||||
are content and should move to `nav.*` keys. Step 4 candidate.
|
||||
- **`/settings` link** is unguarded by `hasPermission`. Per
|
||||
`_docs/ui_design/README.md` settings page is available to every
|
||||
authenticated user — confirmed intent.
|
||||
- **`new Date(f.createdDate).toLocaleDateString()`** uses the browser's
|
||||
default locale, not `i18n.language`. Mild inconsistency; Step 8
|
||||
cosmetic.
|
||||
- **`flights` cache truncation**: the dropdown shows at most 1000
|
||||
flights because of the hardcoded `pageSize=1000` in `FlightContext`.
|
||||
Documented as a flag there; Header inherits the limitation.
|
||||
@@ -0,0 +1,64 @@
|
||||
# Module: `src/components/HelpModal.tsx`
|
||||
|
||||
> **Source**: `src/components/HelpModal.tsx` (62 lines)
|
||||
> **Topo batch**: B2 (uses `react-i18next` for the language flag only; no intra-repo deps)
|
||||
|
||||
## Purpose
|
||||
|
||||
A modal dialog that surfaces annotation guidelines and the keyboard-shortcut cheat-sheet. Triggered from `Header.tsx` → "Help" entry. Replaces the legacy WPF `HelpWindow.xaml` (`_docs/legacy/wpf-era.md` §4).
|
||||
|
||||
## Public interface
|
||||
|
||||
```ts
|
||||
interface Props {
|
||||
open: boolean
|
||||
onClose: () => void
|
||||
}
|
||||
export default function HelpModal(props: Props): JSX.Element | null
|
||||
```
|
||||
|
||||
When `open === false`, returns `null`. Otherwise renders a centered `<div>` overlay.
|
||||
|
||||
## Internal logic
|
||||
|
||||
- Reads `i18n.language` from `useTranslation()`; treats anything other than `'ua'` as English (`lang = i18n.language === 'ua' ? 'ua' : 'en'`).
|
||||
- `GUIDELINES`: a hardcoded array of 6 `{ en, ua }` rules covering annotation quality. **Hardcoded — not loaded via the `i18n` resource bundle**, despite the module already importing `useTranslation`. (Inconsistency vs. the rest of the SPA — flag for Step 4.)
|
||||
- Renders the guidelines as a numbered list and a 12-row keyboard-shortcut grid (`Space`, `← →`, `Ctrl + ← →`, `Enter`, …).
|
||||
- Click on the dim backdrop closes the modal; click inside is `stopPropagation`'d.
|
||||
- `Close` button is a styled `<button>` calling `onClose()`.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Internal**: none.
|
||||
- **External**: `react-i18next` (for `useTranslation()` only — to detect the language; *not* for content lookup).
|
||||
|
||||
## Consumers (intra-repo)
|
||||
|
||||
- `src/components/Header.tsx` — owns `open` state and the trigger button.
|
||||
|
||||
## Data models
|
||||
|
||||
The `GUIDELINES` array — module-private. Each entry: `{ en: string, ua: string }`.
|
||||
|
||||
## Configuration
|
||||
|
||||
The keyboard-shortcut grid hardcodes the same shortcut taxonomy that `_docs/ui_design/README.md` §"Keyboard Shortcuts" enumerates. Verify parity during Step 4.
|
||||
|
||||
## External integrations
|
||||
|
||||
None.
|
||||
|
||||
## Security
|
||||
|
||||
None directly. Note that ESCAPE-key handling appears in the *sibling* `ConfirmDialog` but **not** here — Esc currently does NOT close `HelpModal`. Backdrop click is the only dismiss path beyond the Close button. Inconsistent UX; flag for Step 4 verification against the UI spec.
|
||||
|
||||
## Tests
|
||||
|
||||
None.
|
||||
|
||||
## Notes / open questions
|
||||
|
||||
- The 6 guidelines stored as `{ en, ua }` literals duplicate the Annotation Quality Guidelines documented in `_docs/ui_design/README.md` §"Annotation Quality Guidelines" (which lists six rules with subtly different wording). Choose one source of truth in Step 5; preferred is to lift the strings into `en.json` / `ua.json` like the rest of the SPA.
|
||||
- The `<h2>` "How to Annotate" heading is hardcoded English; should also be translated.
|
||||
- The `lang === 'ua' ? 'ua' : 'en'` branch silently treats every non-Ukrainian language as English — only correct as long as exactly two locales exist. If a third locale is added, this needs to use the `i18n` lookup table.
|
||||
- Width is hardcoded `w-[500px]` and `max-h-[80vh]`. Does not adapt to mobile breakpoints documented in `_docs/ui_design/README.md` §"Responsive Breakpoints" (640px). Flag.
|
||||
@@ -0,0 +1,215 @@
|
||||
# Module: `src/features/admin/AdminPage.tsx`
|
||||
|
||||
> **Source**: `src/features/admin/AdminPage.tsx` (209 lines)
|
||||
> **Topo batch**: B4 (depends on B3: `api/client`, `components/ConfirmDialog`, `types/index`)
|
||||
|
||||
## Purpose
|
||||
|
||||
The administrator console of the SPA. Bundles four management surfaces
|
||||
into a single page: detection-classes catalogue (CRUD-lite),
|
||||
AI-recognition tuning form, GPS-device endpoint config, user
|
||||
list (CRUD-lite), and aircraft default-selector. Replaces the WPF
|
||||
`AdminWindow.xaml` cluster (`_docs/legacy/wpf-era.md` §§4, 5).
|
||||
|
||||
Behind the `/admin` route, gated by `Header`'s `ADM` permission
|
||||
filter (a route-level permission re-check is the responsibility of the
|
||||
`admin/` service — Header gating is UI-only; see Security below).
|
||||
|
||||
## Public interface
|
||||
|
||||
```ts
|
||||
export default function AdminPage(): JSX.Element
|
||||
```
|
||||
|
||||
No props. Reads everything via `api/client` and local state.
|
||||
|
||||
## Internal logic
|
||||
|
||||
- **State**:
|
||||
- `classes: DetectionClass[]` — the detection-class table.
|
||||
- `aircrafts: Aircraft[]` — the aircraft list with `isDefault` flag.
|
||||
- `users: User[]` — the user table.
|
||||
- `newClass: { name; shortName; color; maxSizeM }` — staging buffer
|
||||
for the "add detection class" form (initial: `{ name: '',
|
||||
shortName: '', color: '#FF0000', maxSizeM: 7 }`).
|
||||
- `newUser: { name; email; password; role }` — staging buffer for
|
||||
"add user" (initial: `{ name: '', email: '', password: '', role:
|
||||
'Annotator' }`).
|
||||
- `deactivateId: string | null` — drives the `ConfirmDialog`'s open
|
||||
state for user deactivation.
|
||||
- **Bootstrap effect** (`useEffect([])` — runs once at mount):
|
||||
|
||||
```ts
|
||||
api.get<DetectionClass[]>('/api/annotations/classes').then(setClasses).catch(() => {})
|
||||
api.get<Aircraft[]>('/api/flights/aircrafts').then(setAircrafts).catch(() => {})
|
||||
api.get<User[]>('/api/admin/users').then(setUsers).catch(() => {})
|
||||
```
|
||||
|
||||
Three independent calls, all silently swallowed on error. No retry,
|
||||
no error UI, no loading state — empty arrays render as empty
|
||||
tables. Flag for Step 4 against the user-feedback patterns in
|
||||
`_docs/ui_design/README.md`.
|
||||
- **`handleAddClass()`**:
|
||||
1. Guard: `if (!newClass.name) return`.
|
||||
2. `await api.post('/api/admin/classes', newClass)`.
|
||||
3. Refetch via `api.get('/api/annotations/classes')` — note the
|
||||
**read** path is the public `annotations/` endpoint, while the
|
||||
**write** path is the `admin/` endpoint. Architectural caveat:
|
||||
two different services own the same logical entity. Document in
|
||||
`architecture.md` §integration-points (Step 3a).
|
||||
4. Reset `newClass` to its initial values.
|
||||
No error path — a failed POST throws (because `client.ts` throws on
|
||||
non-2xx); the throw is uncaught and reaches React's error boundary
|
||||
(none configured). Flag.
|
||||
- **`handleDeleteClass(id)`**: optimistic local update —
|
||||
`await api.delete('/api/admin/classes/${id}')` then
|
||||
`setClasses(prev => prev.filter(c => c.id !== id))`. **No
|
||||
ConfirmDialog** despite this being destructive. Inconsistent with
|
||||
the user-deactivation flow which uses ConfirmDialog. Flag for Step 4
|
||||
against `_docs/ui_design/README.md` confirmation-dialog spec.
|
||||
- **`handleAddUser()`** — analogous to `handleAddClass` against
|
||||
`POST /api/admin/users` and `GET /api/admin/users`. Guards on
|
||||
`email && password`.
|
||||
- **`handleDeactivate()`** — fired from the ConfirmDialog confirm:
|
||||
1. `PATCH /api/admin/users/${deactivateId}` with `{ isActive: false }`.
|
||||
2. Optimistic local update: marks the row inactive.
|
||||
3. Closes the dialog (`setDeactivateId(null)`).
|
||||
No "reactivate" path — once `isActive: false`, the row only renders
|
||||
the badge and no Deactivate button. Verify with `admin/` service:
|
||||
is reactivation an admin task or out of scope?
|
||||
- **`handleToggleDefault(a)`** — `PATCH /api/flights/aircrafts/${a.id}`
|
||||
with `{ isDefault: !a.isDefault }`, then optimistic local flip. Note
|
||||
this allows multiple `isDefault: true` aircraft to coexist (the
|
||||
backend should enforce exclusivity; the UI does not).
|
||||
- **Layout** (left → center → right, all in one horizontal flex):
|
||||
- **Left column** (`w-[340px]`): detection-classes table + add row.
|
||||
- **Center column** (`flex-1 max-w-md`): AI settings form, GPS
|
||||
settings form, users table + add row. The AI and GPS forms have
|
||||
`defaultValue` only — there is **no** state, no `Save` handler
|
||||
wired up. The buttons render but do nothing. Flag.
|
||||
- **Right column** (`w-[280px]`): aircraft list with star toggle.
|
||||
- `<ConfirmDialog>` mounted at the end, controlled by `deactivateId`.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Internal**:
|
||||
- `../../api/client` — `api`.
|
||||
- `../../components/ConfirmDialog` — for user deactivation.
|
||||
- `../../types` — `DetectionClass`, `Aircraft`, `User`.
|
||||
- **External**: `react` (`useState`, `useEffect`),
|
||||
`react-i18next` (`useTranslation`).
|
||||
|
||||
## Consumers (intra-repo)
|
||||
|
||||
- `src/App.tsx` — mounted at the `/admin` route inside the protected
|
||||
tree.
|
||||
|
||||
## Data models
|
||||
|
||||
Stateful local copies of `DetectionClass[]`, `Aircraft[]`, `User[]`.
|
||||
The `newClass` and `newUser` buffers are anonymous shapes —
|
||||
intentionally narrower than `DetectionClass` / `User` because the
|
||||
backend assigns `id` and other server-managed fields.
|
||||
|
||||
## Configuration
|
||||
|
||||
- **i18n keys consumed**: `admin.classes`, `admin.aiSettings`,
|
||||
`admin.gpsSettings`, `admin.users`, `admin.aircrafts`,
|
||||
`admin.deactivate`, `common.save`. (Confirmed present in
|
||||
`src/i18n/en.json` admin/common groups.) Plenty of hardcoded
|
||||
English strings — placeholders ("Name", "Email", "Password"), table
|
||||
headers (`#`, `Name`, `Color`, `Email`, `Role`, `Status`), role
|
||||
options (`Annotator`, `Admin`, `Viewer`), the GPS protocol options
|
||||
(`TCP`, `UDP`), the AI tuning labels ("Frame Period Recognition",
|
||||
etc.), and the deactivation confirmation message. Step 4 candidate.
|
||||
- **Hardcoded defaults**:
|
||||
- `maxSizeM: 7` for new detection classes.
|
||||
- `color: '#FF0000'` for new detection classes.
|
||||
- `Frame Period Recognition: 5`, `Frame Recognition Seconds: 1`,
|
||||
`Probability Threshold: 0.5` (`step: 0.05`, `min: 0`, `max: 1`).
|
||||
- `Device Address: 192.168.1.100`, `Port: 5535`, default protocol
|
||||
`TCP`. **Hardcoded internal IP** is a smell; should come from
|
||||
`system_settings` or be a placeholder. Flag for Step 4 / Step 6
|
||||
(`security_approach.md`).
|
||||
- **Tailwind tokens**: `bg-az-panel`, `bg-az-bg`, `bg-az-orange`,
|
||||
`bg-az-blue/20`, `bg-az-green/20`, `text-az-{text,muted,red,green,
|
||||
blue,orange}`, `border-az-border`. Defined in `src/index.css`.
|
||||
|
||||
## External integrations
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| `GET` | `/api/annotations/classes` | List detection classes (read path uses annotations service) |
|
||||
| `POST` | `/api/admin/classes` | Create detection class (write path uses admin service) |
|
||||
| `DELETE` | `/api/admin/classes/{id}` | Delete detection class |
|
||||
| `GET` | `/api/flights/aircrafts` | List aircraft |
|
||||
| `PATCH` | `/api/flights/aircrafts/{id}` | Toggle `isDefault` |
|
||||
| `GET` | `/api/admin/users` | List users |
|
||||
| `POST` | `/api/admin/users` | Create user |
|
||||
| `PATCH` | `/api/admin/users/{id}` | Set `isActive: false` (deactivate) |
|
||||
|
||||
Routed by `nginx.conf` to `admin/`, `annotations/`, `flights/`
|
||||
backends.
|
||||
|
||||
## Security
|
||||
|
||||
- **`/admin` is access-controlled by Header's `ADM` permission filter
|
||||
AND by every backend endpoint** (each `/api/admin/*` is the
|
||||
authority). The page itself does not call `hasPermission` — a user
|
||||
who deep-links to `/admin` would render the page but every fetch
|
||||
would 401/403. Acceptable for production; flag a UX improvement
|
||||
(server-error → friendly redirect) for Step 8.
|
||||
- **Password input has `type="password"`** — masked. The new-user
|
||||
password is held in plaintext component state until the POST
|
||||
resolves. Acceptable; cleared by `setNewUser({...})` after success.
|
||||
- **`color: '#FF0000'`** is a hex string — when posted to
|
||||
`/api/admin/classes`, the backend must validate. UI-side validation
|
||||
(regex / `<input type="color">`) is enforced because the input is
|
||||
a color-picker.
|
||||
- **No CSRF** — relies on the bearer-token scheme. Same posture as the
|
||||
rest of the SPA (see `client.ts` Security section).
|
||||
- **No row-level access checks visible to the UI**: the user list
|
||||
shows every row the backend returns; if the `admin/` service ever
|
||||
filtered by tenant, the UI would not need changes.
|
||||
|
||||
## Tests
|
||||
|
||||
None.
|
||||
|
||||
## Notes / open questions
|
||||
|
||||
- **Detection-class read/write split** between `annotations/` and
|
||||
`admin/` is unusual. Verify with the suite ADRs whether
|
||||
`/api/annotations/classes` and `/api/admin/classes` are the same
|
||||
underlying entity. If yes, the split is a legacy artifact; if no,
|
||||
the UI is conflating two collections. Step 3a / Step 4 verification.
|
||||
- **AI settings & GPS settings forms are wired to nothing** — every
|
||||
`<input>` uses `defaultValue` (uncontrolled), there is no submit
|
||||
handler, and the Save button does nothing. Either:
|
||||
- The legacy WPF AI/GPS settings have not been ported yet (most
|
||||
likely — `_docs/legacy/wpf-era.md` §"What is intentionally NOT
|
||||
being ported" might apply), OR
|
||||
- The backend endpoint exists but the wiring was lost during the
|
||||
port.
|
||||
Flag prominently in Step 4 problem-extraction. Probably a missing
|
||||
feature, not a bug.
|
||||
- **`handleDeleteClass` has no confirmation** — UX inconsistency with
|
||||
user deactivation. Consider unifying via `ConfirmDialog`. Step 4.
|
||||
- **Aircraft default-toggle race**: clicking two aircraft in quick
|
||||
succession will fire two parallel `PATCH`es. The backend may end up
|
||||
with both `isDefault: true` if it does not enforce exclusivity at
|
||||
the persistence layer. Flag for Step 6 problem-extraction. Trust
|
||||
the backend; do not add UI debouncing.
|
||||
- **The "Active" / "Inactive" badge text is hardcoded English** even
|
||||
though the surrounding column header (`Status`) is too. Either
|
||||
localize all of them or accept the inconsistency. Step 4.
|
||||
- **`u.isActive` as the only mutable user field** — no rename, no
|
||||
password reset, no role change. Document the gap; may be a feature
|
||||
cycle item for Phase B.
|
||||
- **`newClass.shortName` is collected but not displayed in the table**
|
||||
— the table only shows `id, name, color, ×`. The `shortName` lives
|
||||
only in the staging buffer and is sent to the backend. Verify the
|
||||
backend stores it.
|
||||
- **Hardcoded GPS device address `192.168.1.100`** is a non-routable
|
||||
RFC1918 default that should not ship with the production bundle.
|
||||
Step 4 flag.
|
||||
@@ -0,0 +1,110 @@
|
||||
# Module group: `src/features/annotations/`
|
||||
|
||||
> Compact doc covering all 5 annotations modules (`classColors.ts` is a shared leaf — see existing `src__features__annotations__classColors.md`). The annotations feature is the **central legacy concern** of the codebase per `_docs/legacy/wpf-era.md §4` (`Azaion.Annotator` window) — what's documented here is the React port. For the canonical product spec see `_docs/ui_design/README.md` (Annotations Tab Layout, Annotation Quality Guidelines, Affiliation Icons, Combat Readiness, Annotation Row Gradient, Keyboard Shortcuts, Video Annotation Time-Window Display) and parent suite `../../../../_docs/01_annotations.md` for the API contract.
|
||||
|
||||
## Scope
|
||||
|
||||
Owns the `/annotations` route. Lets the user:
|
||||
1. Browse media (video / image) for the currently selected flight, with a 300-ms debounced name filter, drag-and-drop / file-picker / folder-picker upload, and right-click delete.
|
||||
2. Play / pause / step a video, scrub the timeline, mute, with frame stepping at 1 / 5 / 10 / 30 / 60 frames in both directions (assumed 30 FPS — see Findings).
|
||||
3. Draw / move / resize / multi-select bounding boxes on a custom canvas overlay, click-and-drag with Ctrl-modifier behaviours, snap to image-normalized coordinates 0–1.
|
||||
4. Pick the active detection class (1–9 hotkeys) and PhotoMode (Regular / Winter / Night) via the shared `DetectionClasses` component.
|
||||
5. Save the per-frame detection set back to `POST /api/annotations/annotations`, with **fall-back to in-memory storage** when the file is a local blob: URL or the backend is unreachable.
|
||||
6. Stream the annotations sidebar from the `GET /api/annotations/annotations/events` SSE feed; show each row with the gradient defined in `_docs/ui_design/README.md`.
|
||||
7. Trigger AI detection via `POST /api/detect/{mediaId}` (modal log overlay).
|
||||
8. Download an annotation as YOLO `.txt` + a PNG of the frame with rectangles burned in.
|
||||
|
||||
## Module map
|
||||
|
||||
| Module | Layer | Responsibility |
|
||||
|---|---|---|
|
||||
| `classColors.ts` | leaf | (already documented separately) Class-number → colour + photoMode-suffix lookup. |
|
||||
| `MediaList.tsx` | sub-component | Left panel media browser. Owns `media[]` state, debounced filter, dropzone upload, blob: local-mode fallback when backend POST fails. Calls `GET /api/annotations/media`, `DELETE /api/annotations/media/{id}`, `POST /api/annotations/media/batch`. |
|
||||
| `VideoPlayer.tsx` | sub-component | Native `<video>` wrapper. `forwardRef` exposes `seek(seconds)` and `getVideoElement()`. Custom progress slider + frame-step toolbar. Global `keydown` handler for Space / ←/→ (Ctrl=±150) / M. |
|
||||
| `AnnotationsSidebar.tsx` | sub-component | Right panel: SSE-driven annotation list (`/api/annotations/annotations/events` filtered by `mediaId`), AI detect button, gradient row background built from per-detection class colour + confidence-modulated alpha, download button (delegates to page). |
|
||||
| `CanvasEditor.tsx` | sub-component | Canvas overlay used in both image-only and video-overlay modes. `forwardRef` exposes `deleteSelected / deleteAll / hasSelection`. Owns zoom (Ctrl+wheel, 0.1–10×), pan (held in `pan` state — there is no Ctrl+drag pan code, only an unused `pan` state — see Findings), 8-handle resize, multi-select, draw-on-Ctrl-mousedown. Renders detections + a "time-window" preview of *other* annotations during video playback. |
|
||||
| `AnnotationsPage.tsx` | page | Orchestrator: 3-panel layout via `useResizablePanel` (left 250 / right 200, min/max bounds). Owns `selectedMedia`, `annotations`, `detections`, `selectedClassNum`, `photoMode`, `currentTime`. Wires `MediaList` → `CanvasEditor` ↔ `VideoPlayer` ↔ `AnnotationsSidebar`. Handles the `Save` POST + local-fallback. Builds the YOLO + PNG download. |
|
||||
|
||||
## Key contracts
|
||||
|
||||
- **`Detection`** (from `src/types/index.ts`): `{ id, classNum, label, confidence ∈ [0,1], affiliation: 0|1|2, combatReadiness, centerX, centerY, width, height }` — all coords normalized 0–1. Matches `_docs/legacy/wpf-era.md §10` and parent suite `_docs/01_annotations.md` Detection DTO.
|
||||
- **`AnnotationListItem`**: `{ id, mediaId, time: 'HH:MM:SS.mmm' | null, createdDate, source: AnnotationSource, status: AnnotationStatus, isSplit, splitTile, detections[] }`. Matches `Annotations` table in parent `_docs/00_database_schema.md` modulo client-side `isSplit / splitTile`.
|
||||
- **AI detect endpoint**: `POST /api/detect/{mediaId}` — matches parent `../../../../_docs/03_detections.md §2` after nginx strips `/api/detect/`. NOTE: UI does NOT forward the `X-Refresh-Token` header that the spec requires for long-running video detection (`_docs/03_detections.md §2 request headers`). Carried as a finding.
|
||||
- **Save body**: `{ mediaId, time: 'HH:MM:SS.mmm' | null, detections: Detection[] }`. .NET `TimeSpan.Parse` accepts that format so the round-trip works for `time → VideoTime`. **Body is missing required `Source` and optional `WaypointId`** required by parent spec `CreateAnnotationRequest` — see Findings.
|
||||
|
||||
## External integrations
|
||||
|
||||
| Endpoint / origin | Where | Direction | Notes |
|
||||
|---|---|---|---|
|
||||
| `GET /api/annotations/media?flightId&name&pageSize=1000` | `MediaList.fetchMedia` | egress | Hardcoded ceiling 1000. |
|
||||
| `GET /api/annotations/media/{id}/file` | `CanvasEditor`, `VideoPlayer`, `AnnotationsPage.handleDownload` | egress | Image / video bytes. |
|
||||
| `POST /api/annotations/media/batch` | `MediaList.uploadFiles` | egress | `multipart/form-data`. |
|
||||
| `DELETE /api/annotations/media/{id}` | `MediaList.handleDelete` | egress | Skipped for local blob: entries. |
|
||||
| `GET /api/annotations/annotations?mediaId&pageSize=1000` | `MediaList.handleSelect`, `AnnotationsSidebar`, `AnnotationsPage.handleSave` | egress | Refresh after save / SSE event. |
|
||||
| `POST /api/annotations/annotations` | `AnnotationsPage.handleSave` | egress | Body: `{ mediaId, time, detections }`. Falls back to in-memory on 4xx/5xx. |
|
||||
| `GET /api/annotations/annotations/{id}/image` | `CanvasEditor.loadImage` | egress | Per-annotation hashed image; preferred over the raw media for image annotations. |
|
||||
| `GET /api/annotations/annotations/events` (SSE) | `AnnotationsSidebar` | egress | Listens for `{ annotationId, mediaId, status }` events; filters client-side by `media.id`. |
|
||||
| `POST /api/detect/{mediaId}` | `AnnotationsSidebar.handleDetect` | egress | Triggers AI inference — endpoint shape unverified vs `_docs/03_detections.md`. |
|
||||
| `URL.createObjectURL(File)` | `MediaList.uploadFiles`, `AnnotationsPage.handleDownload` | browser API | Local-mode blob URLs are revoked on delete or unmount. |
|
||||
|
||||
## Findings carried into Step 4 / 6 / 8
|
||||
|
||||
1. **`VideoPlayer.stepFrames` hardcodes `fps = 30`** — frame stepping is wrong for any other fps (most drone footage is 25 / 30 / 60). UI spec says "Frame duration = 1 / video FPS" (`_docs/ui_design/README.md`). Should read from `video.getVideoPlaybackQuality()` / metadata. Step 4.
|
||||
2. **`VideoPlayer` Ctrl+Left/Right is documented in `_docs/ui_design/README.md` as "skip 5 seconds"** but here it does `±150 frames` (`= 5s @ 30fps` only). Same fps coupling as #1.
|
||||
3. **`VideoPlayer.error` state has no setter call beyond initial `null`/onLoadedMetadata reset** — but the `setError` call on `onError` only sets a string when source fails to load; spec says status messages should appear in a status bar (`_docs/ui_design/README.md`). The status-bar pattern is not implemented.
|
||||
4. **`CanvasEditor` Ctrl+drag pan is documented (`_docs/ui_design/README.md`)** but not implemented — `pan` state exists, only `setPan(...)` calls are inside the (no-op) zoom flow. The canvas always renders at `pan = {0,0}`. Step 4 / Step 6 problem extraction.
|
||||
5. **`CanvasEditor.useEffect[draw]` has missing deps** (`isVideo`, `imgSize` dependency tracked indirectly through other deps; `currentTime`/`annotations` are listed but `getTimeWindowDetections` is recreated each render and is closed-over). Specifically: `draw`'s closure reads `getTimeWindowDetections()` and the inner `getTimeWindowDetections` reads `media`, `currentTime`, `annotations` — those *are* in the dep list, but `media` itself is missing. Step 4 a11y / correctness.
|
||||
6. **`CanvasEditor` time-window threshold is `< 2_000_000` ticks** in `getTimeWindowDetections` — at 10 000 000 ticks/second this is **±200 ms (400 ms total window)**. Spec is **asymmetric 50 ms before + 150 ms after (200 ms total)** per `../../ui_design/README.md`. Implementation window is 4× too wide and centred on the wrong offset. Step 4.
|
||||
7. **`CanvasEditor` `ctx.fillStyle = color; ctx.globalAlpha = 0.1; ctx.fillRect(...)`** — the box "fill" is class colour at 10% opacity, but the **affiliation icon** (NATO MIL-STD-2525 shape) and **combat-readiness indicator** are missing. The current code only renders a tiny green dot for `combatReadiness === 1` (Ready). UI spec demands Friendly/Hostile/Unknown/None affiliation icons and Ready/NotReady/Unknown CR. Step 4 vs `_docs/ui_design/README.md` — significant gap.
|
||||
8. **`CanvasEditor.AFFILIATION_COLORS` constant is dead code** — defined but never used. Likely the seed of the missing affiliation rendering. Step 4.
|
||||
9. **Annotation row gradient cap is wrong by ~9 percentage points**: `AnnotationsSidebar.getRowGradient` uses `Math.round(alpha * 40).toString(16)` — `40` is **decimal**, not hex, so the maximum alpha byte is `0x28` (decimal 40 ≈ **16% opacity**). Spec wireframe `../../ui_design/annotations.html` uses `rgba(...,0.25)` = `0x40` hex (25%). Almost certainly a typo: should be `* 64` (decimal) or `* 0x40` to match the wireframe. Step 4.
|
||||
10. **`AnnotationsSidebar` AI-detect modal**: `setDetectLog` writes "Detection complete" immediately after `await api.post(...)` returns — there is no progress streaming despite the spec ("scrolling log of detection progress" via `DetectionEvent` SSE per `_docs/03_detections.md`). The Detection SSE feed is not subscribed. Step 6.
|
||||
11. **`AnnotationsSidebar` SSE refresh** is fire-and-forget (`.catch(() => {})`) — silent error suppression, violates `coderule.mdc`. Step 4.
|
||||
12. **`AnnotationsPage.formatTicks(seconds)`** produces `HH:MM:SS.mmm` (string). Parent suite `_docs/01_annotations.md` carries `TimeSpan VideoTime` — .NET `TimeSpan.Parse` accepts that format, so the round-trip works, but the API contract is `TimeSpan` ticks, not a string. Verify in Step 4.
|
||||
13. **`AnnotationsPage.handleDownload` never sets `crossOrigin` on the video element** (only on the standalone image fallback) — Canvas `toBlob` will throw "tainted canvas" if the video served from `/api/annotations/media/.../file` doesn't include `Access-Control-Allow-Origin`. Same-origin via the dev proxy and nginx is fine, but cross-origin (CDN / direct) breaks download. Step 4.
|
||||
14. **`AnnotationsPage.handleSelect` annotation flow** does NOT expose `Validate` (V key per UI spec). The Annotations tab shouldn't validate (that's Dataset Explorer), but UI spec keyboard shortcuts list V on Annotations tab too — confirm scope in Step 6.
|
||||
15. **No `R` key for AI detect** in any module here despite UI spec (`R = Trigger AI detection`). The AI Detect button is only reachable by mouse. Step 4.
|
||||
16. **No PageUp / PageDown for prev/next media file** despite UI spec.
|
||||
17. **No Camera config side panel** (altitude / FocalLength / SensorWidth) per `_docs/ui_design/README.md` — completely missing. Documented in Findings of `AdminPage.tsx` too: aircraft camera defaults are global, but per-session override UI is not built. Step 6.
|
||||
18. **`MediaList` uses `alert(...)` for "Unsupported file type"** — not the project modal/toast pattern. Step 4.
|
||||
19. **`MediaList` blob: local-mode is a graceful degradation** that lets the page work without backend — useful for demos but the user has no indication that "you're working offline, save will be lost on reload". Document explicitly in Step 6.
|
||||
20. **`MediaList.fetchMedia` always merges blob: locals on top of backend results** even when filtering — local entries ignore the name filter. Step 4.
|
||||
21. **`AnnotationsSidebar` `try { ... } catch (e: any)`** — `any` cast bypasses TS strict; `e.message` may be `undefined`. Step 4.
|
||||
22. **`AnnotationsPage` left/right panels resize but widths NOT persisted** to `UserSettings` — UI spec says they should be restored per-user across sessions. The `useResizablePanel` hook only owns runtime state. Step 6 / Step 8.
|
||||
23. **`CanvasEditor.handleMouseDown` Ctrl-modifier semantics**: Ctrl+click on a box should multi-select (per spec). Code does this. Ctrl+click on empty space should NOT start a draw — but the current branch starts `dragState = 'draw'` either way, then differentiates inside `handleMouseUp` by drawRect size. Slight UX cost only. Step 4.
|
||||
24. **Tile / split-image annotation rendering**: spec mentions "Tile zoom" — auto-zoom to a tile region when opening a split-image detection. `AnnotationListItem.splitTile` exists but no consumer code reads it. Step 6 problem extraction.
|
||||
25. **`AnnotationsPage.handleSave` 4xx/5xx fallback creates an in-memory `local-${uuid}` annotation** that looks identical to a saved one. The user can't distinguish the two — risk of data loss on reload. Step 6 problem extraction.
|
||||
26. **`AnnotationsPage` does not subscribe to the inference detect SSE** — no AI progress visualization, no update on detect completion, no error if inference returns 5xx. Step 6.
|
||||
27. **[STEP 4 — UI FIX, spec is canonical, user 2026-05-10]** `AnnotationStatus` enum diverges from spec. UI declares `Created=0, Edited=1, Validated=2` (`src/types/index.ts:23`). Spec (`../../../../_docs/09_dataset_explorer.md`) is `None=0, Created=10, Edited=20, Validated=30, Deleted=40`. Action: change `src/types/index.ts` to the spec values. Cascades through every status filter, every PATCH/POST that sends a status, every render. **PRIORITY** — without this fix every dataset status filter and every PATCH `/dataset/{id}/status` from the UI sends a wrong integer.
|
||||
28. **[STEP 4 — UI FIX, spec is canonical, user 2026-05-10]** `Affiliation` enum diverges from spec. UI has 3 values `Unknown=0, Friendly=1, Hostile=2`. Spec (`../../ui_design/README.md` Affiliation Icons + parent `../../../../_docs/03_detections.md`) requires four values `None, Friendly, Hostile, Unknown`. Action: change `src/types/index.ts` to the four-value set; integer values to be confirmed once with the .NET service before patching (likely `None=0, Friendly=1, Hostile=2, Unknown=3`). Without this fix the UI cannot send/render the **None** (no-icon) case.
|
||||
29. **[STEP 4 — UI FIX, spec is canonical, user 2026-05-10]** `CombatReadiness` enum diverges from spec. UI has `NotReady=0, Ready=1`. Spec adds `Unknown` (no indicator rendered). Action: add `Unknown` to `src/types/index.ts`; confirm integer values with the .NET service.
|
||||
30. **[STEP 4 — UI FIX, spec is canonical, user 2026-05-10]** `MediaStatus` enum diverges from spec. UI has `New=0, AiProcessing=1, AiProcessed=2, ManualCreated=3`. Spec (`../../../../_docs/01_annotations.md` SSE + `_docs/03_detections.md §2`) is `None, New, AIProcessing, AIProcessed, ManualCreated, Confirmed, Error`. Action: change `src/types/index.ts` to the seven-value set; confirm integer values with the .NET service. Without this fix the UI cannot render the **Error** SSE event when inference fails.
|
||||
31. **[RESOLVED 2026-05-10 — PARENT-DOC FIX APPLIED]** `AnnotationSource` numeric serialization is canonical; UI is correct (`AI=0, Manual=1`). Parent `../../../../_docs/01_annotations.md` §5 response example and AnnotationSource enum table updated to integer values; `../../../../_docs/09_dataset_explorer.md §1`, §2, §4 examples likewise. Both files also got a "wire format is numeric" header note. No UI change needed.
|
||||
32. **[STEP 4 — UI FIX, user 2026-05-10]** `AnnotationsPage.handleSave` must add `Source` and `WaypointId` to the request body and rename `time` → `videoTime`. Required body shape per parent `../../../../_docs/01_annotations.md §1` `CreateAnnotationRequest`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mediaId": "<string>",
|
||||
"waypointId": "<guid | null>",
|
||||
"source": 1,
|
||||
"videoTime": "HH:MM:SS.mmm",
|
||||
"detections": [ ... ]
|
||||
}
|
||||
```
|
||||
|
||||
Notes: (a) `userId` is supplied server-side from JWT — do not send. (b) `image` is omitted in the save flow; the server reuses the media's frame at `videoTime`. (c) `source` is `Manual` (= `1`) for hand-edited save; AI inference posts use `AI` (= `0`) and are sent server-to-server by the Detections service. (d) `waypointId` must come from `Media.waypointId` (already typed in `src/types/index.ts:16`); the UI currently does not thread waypoint association through to save. (e) Field name `time` must become `videoTime` (.NET PascalCase `VideoTime` → camelCase on the wire).
|
||||
33. **[RESOLVED 2026-05-10 — PARENT-DOC FIX APPLIED]** `DatasetItem.isSplit` is correct on the UI side; parent spec response now includes it. `../../../../_docs/09_dataset_explorer.md §1` `items[]` shape updated with `isSplit: boolean` plus a description tying it to `_docs/03_detections.md §4` Tile-Based Detection. No UI change needed.
|
||||
34. **[STEP 4 — UI FIX, user 2026-05-10]** `Detect` endpoint needs conditional `X-Refresh-Token` header. Spec `../../../../_docs/03_detections.md §2` lists it as required for long-running video detection. Access tokens expire in 3600 s per `../../../../_docs/10_auth.md §1`, so any video that takes >1 h to process loses auth on the server-to-server `POST /annotations` call. Action: when `media.mediaType === MediaType.Video`, attach `X-Refresh-Token: <localStorage refreshToken>` to the `POST /api/detect/{mediaId}` request. Caveat: `/auth/refresh` rotates the refresh token (per `_docs/10_auth.md §2`), so the value can go stale if the UI also refreshes its own token mid-flight. Step 4 must decide whether to (i) cache the refresh token at detect-start, (ii) use a long-lived service token, or (iii) accept the failure mode and surface it to the user. For images and short videos the header is unnecessary — but the UI cannot tell upfront, so default to "always send for video".
|
||||
|
||||
## Tests
|
||||
|
||||
None.
|
||||
|
||||
## Cross-doc references
|
||||
|
||||
- Parent suite Annotations API: `../../../../_docs/01_annotations.md`
|
||||
- Parent suite Detections (AI inference): `../../../../_docs/03_detections.md`
|
||||
- Parent suite Database schema: `../../../../_docs/00_database_schema.md`
|
||||
- Legacy WPF reference: `../../legacy/wpf-era.md` §4 (Annotator window) and §10 (what survived).
|
||||
- UI spec: `../../ui_design/README.md` (Annotations Tab Layout + keyboard shortcuts + time-window + annotation row gradient + affiliation icons + combat readiness).
|
||||
- Shared component used here: `src/components/DetectionClasses.tsx` (already documented).
|
||||
@@ -0,0 +1,73 @@
|
||||
# Module: `src/features/annotations/classColors.ts`
|
||||
|
||||
> **Source**: `src/features/annotations/classColors.ts` (24 lines)
|
||||
> **Topo batch**: B1 (leaf — no internal imports)
|
||||
|
||||
## Purpose
|
||||
|
||||
Pure-function fallbacks for detection-class color and display name. Used when the live `DetectionClass[]` from the admin API hasn't been loaded (initial render) or doesn't include a class for a given `Detection.classNum`.
|
||||
|
||||
Also exposes the **PhotoMode-aware suffix** logic that mirrors the WPF-era `yoloId = classId + photoModeOffset` convention (see `_docs/legacy/wpf-era.md` §10): class numbers in `[0, 19]` are "Regular", `[20, 39]` are "Winter", `[40, 59]` are "Night".
|
||||
|
||||
## Public interface
|
||||
|
||||
```ts
|
||||
export const FALLBACK_CLASS_NAMES: string[] // 12 generic English labels
|
||||
export function getClassColor(classNum: number): string // hex, no '#' alpha
|
||||
export function getPhotoModeSuffix(classNum: number): string // '' | ' (winter)' | ' (night)'
|
||||
export function getClassNameFallback(classNum: number): string // FALLBACK_CLASS_NAMES[base] or '#<n>'
|
||||
```
|
||||
|
||||
A 12-color palette `CLASS_COLORS` is defined module-private and referenced through `getClassColor`.
|
||||
|
||||
## Internal logic
|
||||
|
||||
```
|
||||
base = classNum % 20
|
||||
mode = floor(classNum / 20)
|
||||
color = CLASS_COLORS[base % CLASS_COLORS.length] // wraps if base >= 12
|
||||
name = FALLBACK_CLASS_NAMES[base % FALLBACK_CLASS_NAMES.length]
|
||||
?? `#${classNum}`
|
||||
suffix = mode === 1 ? ' (winter)' : mode === 2 ? ' (night)' : ''
|
||||
```
|
||||
|
||||
The `??` guard exists for the unreachable case `base = 12..19` against an array of length 12 — except `base % length` brings it back into range first, so `?? '#<n>'` is dead. **Flag for Step 4 verification** — either the array is wrong or the `??` is dead code.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Internal**: none.
|
||||
- **External**: none.
|
||||
|
||||
## Consumers (intra-repo)
|
||||
|
||||
- `src/features/annotations/CanvasEditor.tsx` — labels + crosshair color.
|
||||
- `src/features/annotations/AnnotationsPage.tsx` — `getClassColor` for selected class indicator.
|
||||
- `src/features/annotations/AnnotationsSidebar.tsx` — gradient stops in the annotation row.
|
||||
- `src/features/annotations/MediaList.tsx` — *not currently a consumer* despite being adjacent (no import seen).
|
||||
- `src/components/DetectionClasses.tsx` — fallback name + color when admin classes haven't loaded. **This is the cross-layer edge** flagged in `00_discovery.md` §8: a `components/` (shared-layer) file imports from a feature.
|
||||
|
||||
## Data models
|
||||
|
||||
`CLASS_COLORS: string[]` (12 hex strings) and `FALLBACK_CLASS_NAMES: string[]` (12 English strings). Neither is wire-coupled — pure UI defaults.
|
||||
|
||||
## Configuration
|
||||
|
||||
None.
|
||||
|
||||
## External integrations
|
||||
|
||||
None.
|
||||
|
||||
## Security
|
||||
|
||||
None.
|
||||
|
||||
## Tests
|
||||
|
||||
None.
|
||||
|
||||
## Notes / open questions
|
||||
|
||||
- The "+20 winter / +40 night" PhotoMode convention is a direct port of the legacy WPF DetectionClasses contract (`_docs/legacy/wpf-era.md` §10). Verify against the current admin API DTO during component assembly (Step 2) — if the API exposes `photoMode` as a separate field on `DetectionClass` (it does, per `src/types/index.ts`), then computing the suffix from `classNum / 20` here is **redundant** and risks disagreeing with the admin-defined value. Candidate Step 4 testability fix: remove `getPhotoModeSuffix` once consumers have access to the typed `photoMode`.
|
||||
- `FALLBACK_CLASS_NAMES` lists generic English labels (Car, Person, Truck, …) that bear no relation to the actual military classes the legacy doc enumerates (Military Vehicle, Truck, Car, Artillery, Active Mine — see `_docs/ui_design/README.md` §"Detection Classes Table"). Acceptable for a *fallback* only ever shown if the admin classes failed to load; document this in Step 5 (Solution Extraction).
|
||||
- Cross-layer import surfaced in `00_discovery.md` §8 — proper home for these helpers is either `src/components/detection/` (with `DetectionClasses.tsx`) or a new `src/shared/` namespace. Decision deferred to Step 2.5 module-layout derivation.
|
||||
@@ -0,0 +1,69 @@
|
||||
# Module: `src/features/dataset/DatasetPage.tsx`
|
||||
|
||||
> Compact module doc. Spec: `_docs/ui_design/README.md` (Dataset Explorer Layout) and parent suite `../../../../_docs/09_dataset_explorer.md` (API contract). Imports `CanvasEditor` from `../annotations/` — see cross-feature edge in `00_discovery.md §8`.
|
||||
|
||||
## Purpose
|
||||
|
||||
Owns the `/dataset` route. Read-side surface for the `Annotations` table: paginated thumbnail grid, date / class / status / objects-only / name filters, inline editing through the Annotations Tab's `CanvasEditor`, and a class-distribution chart. Mirrors the legacy `Azaion.Dataset.DatasetExplorer` window (`_docs/legacy/wpf-era.md §5`).
|
||||
|
||||
## Public interface
|
||||
|
||||
Default-exported page component, no props. Mounts under `/dataset` in `App.tsx`.
|
||||
|
||||
## Internal logic
|
||||
|
||||
- **Tabs**: `'annotations'` (grid, default) | `'editor'` (hidden until a thumbnail is double-clicked) | `'distribution'` (bar chart). State held in component.
|
||||
- **Filters**: `fromDate`, `toDate`, `statusFilter` (`AnnotationStatus`), `selectedClassNum` (from `DetectionClasses`), `objectsOnly` (boolean), `search` (400 ms debounced via `useDebounce`).
|
||||
- **Pagination**: client `page` state, server `pageSize` fixed at 20, `totalPages = ceil(totalCount / pageSize)`.
|
||||
- **Selection**: `Set<annotationId>`. Plain click replaces; Ctrl+click toggles. Validate button appears when set is non-empty.
|
||||
- **Validate**: `POST /api/annotations/dataset/bulk-status` with `{ annotationIds[], status: Validated }`.
|
||||
- **Distribution**: lazy-loaded on tab switch via `GET /api/annotations/dataset/class-distribution`.
|
||||
- **Editor tab** mounts `<CanvasEditor>` with a synthesised `Media` stub built from `editorAnnotation.mediaId` (most fields blank). Used so `CanvasEditor` can fetch the image via `/api/annotations/annotations/{id}/image`.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Internal: `api/client`, `useDebounce`, `useResizablePanel` (left panel 250 / 200–400), `FlightContext`, `DetectionClasses`, `ConfirmDialog` (imported but not used here — see Findings), `features/annotations/CanvasEditor`, `types/index`.
|
||||
- External: `react`, `react-i18next`.
|
||||
|
||||
## External integrations
|
||||
|
||||
| Endpoint | Where | Notes |
|
||||
|---|---|---|
|
||||
| `GET /api/annotations/dataset?...` | `fetchItems` | Filters: `page`, `pageSize`, `fromDate`, `toDate`, `flightId`, `status`, `classNum`, `hasDetections`, `name`. |
|
||||
| `GET /api/annotations/dataset/{id}` | `handleDoubleClick` | Loads full `AnnotationListItem` for the editor tab. |
|
||||
| `POST /api/annotations/dataset/bulk-status` | `handleValidate` | Body: `{ annotationIds, status }`. |
|
||||
| `GET /api/annotations/dataset/class-distribution` | `loadDistribution` | Class histogram. |
|
||||
| `GET /api/annotations/annotations/{id}/thumbnail` | grid tile `<img src=>` | One HTTP per visible tile. |
|
||||
| `GET /api/annotations/annotations/{id}/image` | `CanvasEditor` (delegated) | When the editor is open. |
|
||||
|
||||
Spec contract is in parent suite `_docs/09_dataset_explorer.md`.
|
||||
|
||||
## Findings carried into Step 4 / 6 / 8
|
||||
|
||||
1. **No keyboard shortcuts implemented**: spec demands `1–9` (class), Enter (save), Del (delete), X (delete all), Esc (close editor), V (validate selected), Up/Down/PageUp/PageDown (navigate). Only Ctrl+click for multi-select works. The editor tab has no Save / Delete buttons either. Step 6 problem extraction.
|
||||
2. **`Refresh thumbnails` button is missing** — spec calls for a status-bar action to regenerate the thumbnail database with progress. Step 6.
|
||||
3. **No virtualisation in the grid**: spec says "virtualized grid" — current code renders all `items` returned by the page (max 20 due to `pageSize`). For larger pages performance would degrade. Today not a problem because `pageSize=20`. Step 8.
|
||||
4. **Editor tab does not Save**: opening an annotation in the editor lets the user edit `editorDetections` locally but there's no Save / Cancel control wired up. Edits are discarded when the user changes tab. Step 6.
|
||||
5. **`editorMedia` synthetic stub** — `mediaType: 1` is a magic number (`MediaType.Image = 1`); should reuse the enum import already present. Step 4.
|
||||
6. **`ConfirmDialog` imported but never used** — dead import. Step 4 cleanup.
|
||||
7. **`fetchItems` does `catch {}`** silently — same `coderule.mdc` violation as elsewhere. Step 4.
|
||||
8. **Empty-state**: when `items.length === 0` the grid renders nothing; no "No matches" message. Step 4.
|
||||
9. **`thumbnail` URL does not include a cache-buster**; if a thumbnail is regenerated server-side, the browser will keep the stale image. Step 4 / Step 8.
|
||||
10. **`isSeed` red-ring is correctly rendered**, but `isSeed` is not in `AnnotationStatus` filters — the user can't filter to seeds-only. Step 6 if intended.
|
||||
11. **Date inputs accept any `<input type="date">` string**; no validation that `fromDate ≤ toDate`. Step 4.
|
||||
12. **Status filter buttons skip status `None`** (spec lists None as one of the four buttons) — current code shows `All`, `Created`, `Edited`, `Validated`, conflating `All` with "include None". Step 4.
|
||||
13. **`selectedClassNum=0` is the "no filter" sentinel** but also a real class number (class 0 exists per `_docs/ui_design/README.md` → military vehicle). Selecting class 0 in `DetectionClasses` is indistinguishable from "no filter". Step 6.
|
||||
14. **Inherits one cross-cutting UI fix and one cross-repo parent-doc fix** (resolved with user 2026-05-10):
|
||||
- **[STEP 4 — UI FIX]** `AnnotationStatus` values must change from UI `0/1/2` to spec `0/10/20/30/40` (`src/types/index.ts:23`). Every status filter button in this page (`null`/`null`/`Created`/`Edited`/`Validated`) currently sends a wrong integer. The "All" button is value `null` (no filter) — keep, but also expose a real "None" filter using the new `AnnotationStatus.None=0`. **PRIORITY** for Step 4. See annotations doc finding #27.
|
||||
- **[RESOLVED 2026-05-10]** `DatasetItem.isSplit` is correct on UI; parent `../../../../_docs/09_dataset_explorer.md §1` response schema now includes it. See annotations doc finding #33.
|
||||
|
||||
## Tests
|
||||
|
||||
None.
|
||||
|
||||
## Cross-doc references
|
||||
|
||||
- Parent suite Dataset Explorer API: `../../../../_docs/09_dataset_explorer.md`
|
||||
- UI spec: `../../ui_design/README.md` (Dataset Explorer Layout, Keyboard Shortcuts).
|
||||
- Imports `CanvasEditor` from `features/annotations/` — see `00_discovery.md §8` cross-feature edge.
|
||||
- Legacy WPF reference: `../../legacy/wpf-era.md §5` (Dataset Explorer window).
|
||||
@@ -0,0 +1,106 @@
|
||||
# Module group: `src/features/flights/`
|
||||
|
||||
> **Note**: this is a deliberately compact doc covering all 15 flights modules. Behaviour is mostly an in-progress port of `mission-planner/` into the React 19 SPA. For the canonical product spec see `_docs/ui_design/README.md` (Flights Page Layout) and `../../../_docs/02_flights.md` / `11_gps_denied.md` in the parent suite repo (Flights API contract + GPS-Denied semantics).
|
||||
|
||||
## Scope
|
||||
|
||||
Owns the `/flights` route. Lets the user:
|
||||
1. Browse / create / delete `Flight` rows (`POST/DELETE /api/flights/...`).
|
||||
2. Plan a mission on a Leaflet map: add waypoints, draw work-area / no-go rectangles, edit altitude + purpose per point, see live total distance, time, battery %.
|
||||
3. Toggle into GPS-Denied mode — opens an SSE stream `/api/flights/{id}/live-gps` (and the panel for orthophoto upload + correction once that backend wiring lands; today only the live-GPS readout is connected).
|
||||
4. Save waypoints back to the Flights API (`/api/flights/{id}/waypoints`).
|
||||
5. Import / export the plan as JSON.
|
||||
|
||||
Currently handles only the planning surface; the gps-denied orthophoto upload / correction inputs in `_docs/ui_design/flights.html` are not yet implemented.
|
||||
|
||||
## Module map
|
||||
|
||||
| Module | Layer | Responsibility |
|
||||
|---|---|---|
|
||||
| `types.ts` | leaf | All flight-feature-only types (`FlightPoint`, `CalculatedPointInfo`, `MapRectangle`, `WindParams`, `AircraftParams`, `MovingPointInfo`, `ActionMode`), plus tile URLs (`TILE_URLS`), `PURPOSES` (`tank` / `artillery`), and `COORDINATE_PRECISION = 8`. |
|
||||
| `mapIcons.ts` | leaf | Three coloured Leaflet `Icon` instances + the default Leaflet pin (loaded from a CDN — see Findings). |
|
||||
| `flightPlanUtils.ts` | leaf | Pure-ish helpers: `newGuid`, haversine `calculateDistance` (with plane climb/cruise/descend profile), OpenWeatherMap fetch, semi-empirical `calculateBatteryPercentUsed`, `calculateAllPoints` (sequential reduce), `parseCoordinates`, `getMockAircraftParams`. |
|
||||
| `WaypointList.tsx` | sub-component | `@hello-pangea/dnd` reorderable list, hover-only Edit/Remove buttons, shows distance / time / battery / altitude per point. |
|
||||
| `AltitudeChart.tsx` | sub-component | `react-chartjs-2` Line chart of altitude over normalized distance; pulls all controllers via `chart.js/auto`. |
|
||||
| `WindEffect.tsx` | sub-component | Two number inputs (heading 0–360°, speed 0–30 m/s) with a small SVG arrow preview. |
|
||||
| `MiniMap.tsx` | sub-component | 240×180 `react-leaflet` thumbnail anchored to a moving point; `attributionControl={false}`. |
|
||||
| `AltitudeDialog.tsx` | sub-component | Add / Edit waypoint modal: lat / lng / altitude / `meta: string[]` purpose multi-select. Fully controlled. |
|
||||
| `MapPoint.tsx` | sub-component | One waypoint marker: draggable, popup with altitude slider, purpose checkboxes, remove button. |
|
||||
| `DrawControl.tsx` | sub-component | Headless Leaflet handler that draws work-area / prohibited-area rectangles via `mousedown / mousemove / mouseup`. |
|
||||
| `FlightListSidebar.tsx` | sub-component | Left rail: flight list, "+ Create", inline-create row, telemetry date stub. |
|
||||
| `JsonEditorDialog.tsx` | sub-component | Modal `<textarea>` over the plan JSON with live `JSON.parse` validation. |
|
||||
| `FlightParamsPanel.tsx` | composite | Hosts `WaypointList` + `AltitudeChart` + `WindEffect` + all per-flight inputs (aircraft, initial altitude, FoV, comm address, action-mode buttons, totals strip, Save / Upload / EditAsJSON / Export). |
|
||||
| `FlightMap.tsx` | composite | Wraps `MapContainer`; mounts `MapPoint` × N, `DrawControl`, `MiniMap` (when a point is moving), polyline + arrow decorator, satellite/classic toggle. |
|
||||
| `FlightsPage.tsx` | page | Orchestrator: owns all state, talks to `api/client`, opens the SSE stream, mediates between sidebar / params panel / map / dialogs. |
|
||||
|
||||
## Key contracts (read by other docs)
|
||||
|
||||
- **`FlightPoint`**: `{ id: string; position: { lat; lng }; altitude: number; meta: string[] }`. `meta` ⊆ `{ 'tank', 'artillery' }`. The shape diverges from the legacy WPF `Point` (radio, single purpose) — the React SPA uses checkboxes (multi).
|
||||
- **`CalculatedPointInfo`**: `{ bat: number /* % */; time: number /* hours */ }`. Index `i` = state at point `i` after the segment from `i-1`. `lastInfo.bat` drives the Good / Caution / Low colour status (`>12 / >5 / ≤5`).
|
||||
- **`PURPOSES = [{ value: 'tank', label: 'options.tank' }, { value: 'artillery', label: 'options.artillery' }]`** — i18n keys are `flights.planner.${label}`.
|
||||
- **JSON plan shape** (`handleEditJson` / `handleExport` / `handleJsonSave`): `{ operational_height: { currentAltitude }, geofences: { polygons: [{ northWest, southEast, fence_type: 'EXCLUSION'|'INCLUSION' }] }, action_points: [{ point: { lat, lon }, height, action: 'search', action_specific: { targets: string[] } }] }`. Used for both export-to-file and the JSON editor.
|
||||
- **Tile URLs**: classic OSM and an Esri ArcGIS `World_Imagery` (in `types.ts`). Both are direct upstream — neither goes through the suite `satellite-provider/` proxy. See Findings.
|
||||
|
||||
## External integrations
|
||||
|
||||
| Endpoint / origin | Where | Direction | Notes |
|
||||
|---|---|---|---|
|
||||
| `GET /api/flights/aircrafts` | `FlightsPage` | egress | Aircraft selector population. |
|
||||
| `GET /api/flights/{id}/waypoints` | `FlightsPage` | egress | On flight select. |
|
||||
| `POST /api/flights` | `FlightsPage` | egress | Create flight from sidebar. |
|
||||
| `DELETE /api/flights/{id}` | `FlightsPage` | egress | After ConfirmDialog. |
|
||||
| `POST/DELETE /api/flights/{id}/waypoints[/{wp}]` | `FlightsPage.handleSave` | egress | Delete-all-then-recreate, sequentially. |
|
||||
| `GET /api/flights/{id}/live-gps` (SSE) | `FlightsPage` | egress | Open while in GPS mode + flight selected. |
|
||||
| `https://api.openweathermap.org/...` | `flightPlanUtils.getWeatherData` | egress | Direct browser→3rd-party. **Hardcoded API key.** See Findings. |
|
||||
| `tile.openstreetmap.org` (`TILE_URLS.classic`) | `FlightMap`, `MiniMap` | egress | Direct, no proxy. |
|
||||
| `server.arcgisonline.com/.../World_Imagery` (`TILE_URLS.satellite`) | `FlightMap`, `MiniMap` | egress | Direct, no proxy. |
|
||||
| `unpkg.com/leaflet@1.7.1/dist/images/marker-icon-2x.png` | `mapIcons.defaultIcon` | egress | CDN, version pinned to 1.7.1 while package is 1.9.4 (drift). |
|
||||
| `navigator.geolocation.getCurrentPosition` | `FlightsPage` mount | browser API | Fallback to hardcoded `47.242, 35.024` (Zaporizhzhia). |
|
||||
|
||||
## Findings carried into Step 4 / 6 / 8
|
||||
|
||||
These are the real findings; the per-module rationale is in git history of the deleted per-file docs. Numbered for cross-reference from `state.json.notes`.
|
||||
|
||||
1. **HARDCODED OPENWEATHER API KEY** — `flightPlanUtils.ts:60`. HIGH severity. Step 4 source-code fix; upstream rotation is a parallel user task.
|
||||
2. **`flightPlanUtils.calculateAllPoints` does N sequential `await`s** to OpenWeatherMap — N × RTT latency. Not parallelisable as-is because `info[i].bat` depends on `info[i-1]`. Step 8 refactor: fetch weather first in parallel, then reduce.
|
||||
3. **`flightPlanUtils.calculateDistance` mixes km and metres** (`R = 6371`, altitudes converted `/1000` inline, returned `time = dist / aircraft.speed` assumes km/h). No type forces correctness. Step 4.
|
||||
4. **`AircraftParams.batteryCapacity` unit is ambiguous** (Wh vs W·s). `calculateBatteryPercentUsed` divides W·s by it × 100 — only correct if W·s. Verify against `mission-planner/src/services/calculateBatteryUsage.ts`. Step 4.
|
||||
5. **`flightPlanUtils.getWeatherData` swallows errors silently** (`catch { return null }`); callers can't distinguish "no wind" from "key revoked". Step 4.
|
||||
6. **`mapIcons.defaultIcon` CDN URL is leaflet@1.7.1** while `package.json` is 1.9.4. Step 4 — switch to bundled assets or match version.
|
||||
7. **`FlightMap` and `MiniMap` bypass the suite `satellite-provider/` proxy** (Esri tiles direct from `server.arcgisonline.com`). Possible licence + rate-limit concern. Step 4 + `architecture.md`.
|
||||
8. **`MiniMap` sets `attributionControl={false}`** — drops OSM / Esri attribution. Possible licence-compliance gap. Step 4.
|
||||
9. **`MiniMap` is fixed 240×180 + zoom 18 hardcoded** — overflows below the 640px mobile breakpoint. Step 4 vs `_docs/ui_design/README.md` responsive specs.
|
||||
10. **`AltitudeDialog` lacks Esc-to-close, backdrop-click-to-cancel, `role="dialog"`, `aria-modal`** — inconsistent with `ConfirmDialog`. Same for `JsonEditorDialog`. Pick one modal convention in Step 4.
|
||||
11. **`AltitudeDialog` accepts any number for lat/lng** (no `[-90,90]` / `[-180,180]` guard). `AltitudeDialog.altitude` and `WindEffect` inputs use `Number('')` → 0 silently — same pitfall noted in `SettingsPage`. Step 4.
|
||||
12. **`AltitudeDialog` purpose multi-select** vs WPF radio (single choice). Confirm intent in Step 6: is the SPA expanding the data model on purpose, or is this a UI bug?
|
||||
13. **`WindEffect` `max=360`** allows duplicate heading at 0 vs 360. Step 4.
|
||||
14. **`WaypointList` drag handle is the entire row** (prevents text selection); Edit/Remove buttons are hover-only (unusable on touch); no a11y reorder announcements. Step 4 / Step 8 a11y.
|
||||
15. **`WaypointList.calculatedPointInfo[i]`** silently degrades to alt-only label if length mismatches; tightly coupled to `FlightsPage` keeping arrays in lockstep.
|
||||
16. **`AltitudeChart` pulls every chart.js controller** via `chart.js/auto` (bundle bloat); colours are duplicated as hex literals (drift from the `az-*` Tailwind tokens). Step 8.
|
||||
17. **`AltitudeDialog` naming**: file is "AltitudeDialog" but the dialog covers lat / lng / altitude / purpose. Port-vestige from `mission-planner/`. Rename to `WaypointDialog` in Step 8.
|
||||
18. **`flightPlanUtils.ts` is single-file** — newGuid + geo + weather + battery + parser + mock all together. Splitting into `geo.ts` / `weather.ts` / `battery.ts` / `mockAircraft.ts` is a Step 8 SRP candidate.
|
||||
19. **`FlightsPage.handleSave`** deletes all existing waypoints then recreates — N+M sequential PUT/DELETE round-trips, not transactional, no progress UI, partial failure leaves the flight half-saved.
|
||||
20. **`FlightsPage.handleSave` body shape does NOT match the Flights API spec — UI will likely 400 on a strict server**. Code POSTs `{ name, latitude, longitude, order }`. Parent `../../../../_docs/02_flights.md §3` `CreateWaypointRequest` requires `{ Geopoint: {Lat, Lon, MGRS}, Source: WaypointSource, Objective: WaypointObjective, OrderNum, Height }`. Mismatches: (a) lat/lon not nested under `Geopoint`; (b) field is `order`, spec is `OrderNum`; (c) `Source`, `Objective`, `Height` not sent at all; (d) UI sends `name` which the spec does not define on `Waypoint` (`Waypoint` interface in `src/types/index.ts:76` invents `name`). This collides with finding #19 — every save will round-trip waypoints in the wrong shape. **PRIORITY** for Step 4. Open question for Step 6: are these columns being added to the Flights API schema, or is the React UI to be aligned to the spec? Same comment for `altitude` and `meta` which have no place in the current spec.
|
||||
21. **`FlightsPage.useEffect` bootstraps `getMockAircraftParams()`** as the active `aircraft` regardless of what the backend returns — the dropdown choice is cosmetic for now. Real wiring is a Step 6 / Step 8 follow-up.
|
||||
22. **GPS-Denied panel is partial** — only the SSE live-GPS readout is wired; orthophoto upload, GPS correction (per `_docs/ui_design/README.md`) are not. Step 6 problem extraction.
|
||||
23. **`handleImport` silently drops the file picker** if the user cancels (`if (!file) return`) — fine. But `handleJsonSave`'s catch uses `alert(...)` for a UX-grade error — replace with the project's modal/toast pattern in Step 4.
|
||||
24. **`MapPoint` popup recomputes the marker DOM offset on every drag move** to choose dx/dy for the moving-point indicator. Acceptable, but the `(marker as unknown as { _icon: HTMLElement })._icon` cast leaks Leaflet internals.
|
||||
25. **`DrawControl` registers global `mousedown`/`mousemove`/`mouseup` on the map** while a draw mode is active and disables `map.dragging` for the duration — fine, but no Esc-to-cancel mid-draw.
|
||||
26. **`FlightContext` ceiling**: `FlightsPage` reads `flights` from `useFlight()` which fetches with `pageSize=1000` (already flagged in `FlightContext` doc). Won't surface here, but `selectFlight` is fire-and-forget — if the PUT to `/api/flights/select` fails the next page reload reverts the choice without notice.
|
||||
|
||||
## What's intentionally NOT here
|
||||
|
||||
- The orthophoto-upload / GPS-correction sub-panel (in `_docs/ui_design/flights.html` but not in source).
|
||||
- Any per-segment annotation-time-window logic (that's the Annotations module).
|
||||
- Any aircraft battery model that respects altitude-dependent air density (constant 1.05 kg/m³ in source).
|
||||
|
||||
## Tests
|
||||
|
||||
None — confirmed by `00_discovery.md §5`. Documented test gap is owned by Steps 3 / 5–7 of autodev (test-spec → implement → run).
|
||||
|
||||
## Cross-doc references
|
||||
|
||||
- Parent suite Flights API contract: `../../../../_docs/02_flights.md` (DTOs, endpoint shapes).
|
||||
- Parent suite GPS-Denied: `../../../../_docs/11_gps_denied.md` (SSE event shape, correction flow).
|
||||
- UI spec: `../../ui_design/README.md` (Flights Page Layout, GPS-Denied panel toggle, mobile breakpoint).
|
||||
- Port-source: `mission-planner/src/flightPlanning/*` — covered separately as one consolidated doc.
|
||||
@@ -0,0 +1,151 @@
|
||||
# Module: `src/features/login/LoginPage.tsx`
|
||||
|
||||
> **Source**: `src/features/login/LoginPage.tsx` (95 lines)
|
||||
> **Topo batch**: B4 (depends on B3: `auth/AuthContext`)
|
||||
|
||||
## Purpose
|
||||
|
||||
The single public route of the SPA. Collects email + password, calls
|
||||
`AuthContext.login(...)`, and on success runs a four-step "unlock"
|
||||
animation (download key → decrypting → starting services → ready)
|
||||
before navigating to `/flights`. Replaces the WPF `LoginWindow.xaml`
|
||||
including its multi-step progress UI (`_docs/legacy/wpf-era.md` §3 / §4).
|
||||
|
||||
## Public interface
|
||||
|
||||
```ts
|
||||
export default function LoginPage(): JSX.Element
|
||||
```
|
||||
|
||||
No props. Reads `useAuth().login` and `react-router-dom`'s `useNavigate`.
|
||||
|
||||
## Internal logic
|
||||
|
||||
- **State machine** — `step: UnlockStep` cycles through:
|
||||
`idle → authenticating → downloadingKey → decrypting → startingServices → ready`,
|
||||
with `idle` also reachable on error from `authenticating`.
|
||||
|
||||
```ts
|
||||
type UnlockStep = 'idle' | 'authenticating' | 'downloadingKey'
|
||||
| 'decrypting' | 'startingServices' | 'ready'
|
||||
```
|
||||
|
||||
- **Local state**:
|
||||
- `email: string`, `password: string` — controlled inputs.
|
||||
- `error: string` — empty unless the previous attempt failed.
|
||||
- `step: UnlockStep` — drives both the form/spinner branch and the
|
||||
spinner caption.
|
||||
- **`handleSubmit(e)`**:
|
||||
1. `preventDefault`, clear `error`, set `step = 'authenticating'`.
|
||||
2. `await login(email, password)` — this throws on bad credentials
|
||||
(`AuthContext.login` rethrows the `api.post` error).
|
||||
3. On success: call `runUnlockSequence()`.
|
||||
4. On failure: reset `step` to `'idle'`, set `error = t('login.error')`.
|
||||
- **`runUnlockSequence()`** — sequentially sets `step` to each of
|
||||
`downloadingKey`, `decrypting`, `startingServices`, `ready`, with a
|
||||
600ms `setTimeout` delay between each. After `ready`, navigates to
|
||||
`/flights`. The unlock steps are **purely presentational** — there is
|
||||
no real downloadKey/decrypt work happening; the SPA's bearer token is
|
||||
already set inside `await login(...)`. The animation reproduces the
|
||||
WPF "vault unlocking" UX for continuity, not for any cryptographic
|
||||
operation. Total minimum wait after a successful auth: 4 × 600 ms =
|
||||
2.4 s. Document explicitly to avoid future "what does this decrypt?"
|
||||
confusion.
|
||||
- **`STEP_KEYS`**: a `Record<UnlockStep, string>` mapping each step to a
|
||||
translation key. `'idle'` maps to the empty string (the spinner
|
||||
caption is not rendered when idle).
|
||||
- **Render**: when `step === 'idle'`, the form is shown (email +
|
||||
password + error + submit). Otherwise the form is hidden and a
|
||||
centered spinner with the localized step caption is shown. Note the
|
||||
spinner is rendered even during `authenticating` (real network), so
|
||||
the user sees a single uninterrupted spinner across the entire
|
||||
auth → animation flow.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Internal**: `../../auth/AuthContext` — `useAuth().login`.
|
||||
- **External**: `react` (`useState`, `FormEvent` type),
|
||||
`react-router-dom` (`useNavigate`),
|
||||
`react-i18next` (`useTranslation`).
|
||||
|
||||
## Consumers (intra-repo)
|
||||
|
||||
- `src/App.tsx` — mounted at the public `/login` route, *outside*
|
||||
`AuthProvider`. (Verify in B8 — currently `App.tsx` puts
|
||||
`AuthProvider` inside the protected branch only, so `LoginPage`
|
||||
reaches `useAuth()` only because `App.tsx` actually wraps everything
|
||||
in `AuthProvider` at a higher level. Confirmed via the §7a graph
|
||||
edge `App → AuthProvider`.)
|
||||
|
||||
## Data models
|
||||
|
||||
`UnlockStep` and `STEP_KEYS` are module-private. No DTOs or shared
|
||||
types.
|
||||
|
||||
## Configuration
|
||||
|
||||
- **i18n keys**: `login.title`, `login.email`, `login.password`,
|
||||
`login.submit`, `login.error`, `login.authenticating`,
|
||||
`login.downloadingKey`, `login.decrypting`, `login.startingServices`,
|
||||
`login.ready`. (All present in `src/i18n/en.json` and `ua.json` —
|
||||
confirmed.)
|
||||
- **Tailwind tokens**: `bg-az-bg`, `bg-az-panel`, `border-az-border`,
|
||||
`text-az-orange`, `text-az-text`, `text-az-muted`, `text-az-red`.
|
||||
Defined in `src/index.css`.
|
||||
- **Hardcoded animation timing**: `600 ms` per step. No env override.
|
||||
|
||||
## External integrations
|
||||
|
||||
None directly. Indirect: `AuthContext.login` calls
|
||||
`POST /api/admin/auth/login` (routed by `nginx.conf` to the `admin/`
|
||||
service).
|
||||
|
||||
## Security
|
||||
|
||||
- Both inputs use the right `type` attribute (`email`, `password`),
|
||||
giving the browser the chance to mask the password and offer
|
||||
password-manager autofill.
|
||||
- The HTML form does NOT have `autoComplete="off"` — autofill is
|
||||
intentionally allowed.
|
||||
- The component does NOT log credentials anywhere. The `error` state
|
||||
carries only the localized "Invalid credentials" string, never the
|
||||
raw backend error.
|
||||
- After successful auth, the bearer is already in memory (`AuthContext`
|
||||
set it). The 2.4s "unlock" animation does NOT extend the auth window
|
||||
— if the bearer expires server-side during the animation the next
|
||||
request retries via `client.ts`'s 401 → refresh path.
|
||||
- The `setError(t('login.error'))` shows a single generic error for
|
||||
every failure mode (wrong password, account locked, server down).
|
||||
Acceptable for security (no user-enumeration leak), but logs an
|
||||
observability flag — backend should keep specific reasons in its
|
||||
audit log.
|
||||
|
||||
## Tests
|
||||
|
||||
None.
|
||||
|
||||
## Notes / open questions
|
||||
|
||||
- **The unlock animation is theatrical** — it suggests cryptographic
|
||||
work that is NOT happening. If a future phase actually adds
|
||||
client-side key derivation, the animation should reflect real
|
||||
progress (`'decrypting'` would block on actual work). Keep the names
|
||||
but document the placeholder status in `solution.md` (Step 5).
|
||||
- **No "loading" while `authenticating`** beyond hiding the form —
|
||||
Submit button shows no spinner of its own; the form simply hides
|
||||
the moment `step` leaves `'idle'`. Mild UX gap (a quick auth
|
||||
failure shows the form blink). Defer to Step 8.
|
||||
- **Caps Lock indicator missing** — the WPF version had one
|
||||
(`_docs/legacy/wpf-era.md`). Not currently a goal; flag if the UX
|
||||
spec calls for it.
|
||||
- **No "Forgot password" link** — out of scope; the `admin/` service
|
||||
may or may not support that flow. Verify during Step 6 problem
|
||||
extraction.
|
||||
- **Form does not disable Submit while authenticating** — but the
|
||||
form is unmounted as soon as `step !== 'idle'`, so a double-click
|
||||
cannot fire a second `login(...)` call. Acceptable.
|
||||
- **`runUnlockSequence` resolution race**: if the user navigates
|
||||
away mid-animation (e.g. closes the tab), the pending `setTimeout`s
|
||||
still fire but harmlessly. React's StrictMode double-invokes the
|
||||
effect-mount path in dev — but `runUnlockSequence` is invoked from
|
||||
`handleSubmit`, not an effect, so no duplication.
|
||||
@@ -0,0 +1,181 @@
|
||||
# Module: `src/features/settings/SettingsPage.tsx`
|
||||
|
||||
> **Source**: `src/features/settings/SettingsPage.tsx` (107 lines)
|
||||
> **Topo batch**: B4 (depends on B3: `api/client`, `types/index`)
|
||||
|
||||
## Purpose
|
||||
|
||||
The per-tenant configuration screen. Three side-by-side panels:
|
||||
**Tenant** (system settings: military unit, name, default camera
|
||||
width and FoV), **Directories** (server-side filesystem paths for
|
||||
videos, images, labels, results, thumbnails, GPS sat / route),
|
||||
and **Aircrafts** (read-only list with star-toggle for default
|
||||
selection). Replaces the legacy WPF `SettingsWindow.xaml` plus the
|
||||
"system" tab (`_docs/legacy/wpf-era.md` §4).
|
||||
|
||||
Available to every authenticated user — `Header` does not gate
|
||||
`/settings` behind a permission check. The backend is the authority
|
||||
for who is allowed to write.
|
||||
|
||||
## Public interface
|
||||
|
||||
```ts
|
||||
export default function SettingsPage(): JSX.Element
|
||||
```
|
||||
|
||||
No props.
|
||||
|
||||
## Internal logic
|
||||
|
||||
- **State**:
|
||||
- `system: SystemSettings | null` — loaded from
|
||||
`GET /api/annotations/settings/system`. `null` until the GET
|
||||
resolves; the panel does not render until then (`{system && (...)}`).
|
||||
- `dirs: DirectorySettings | null` — analogous, from
|
||||
`GET /api/annotations/settings/directories`.
|
||||
- `aircrafts: Aircraft[]` — from `GET /api/flights/aircrafts`.
|
||||
- `saving: boolean` — disables the two Save buttons during a PUT.
|
||||
- **Bootstrap effect** (`useEffect([])`):
|
||||
|
||||
```ts
|
||||
api.get<SystemSettings>('/api/annotations/settings/system').then(setSystem).catch(() => {})
|
||||
api.get<DirectorySettings>('/api/annotations/settings/directories').then(setDirs).catch(() => {})
|
||||
api.get<Aircraft[]>('/api/flights/aircrafts').then(setAircrafts).catch(() => {})
|
||||
```
|
||||
|
||||
Three independent calls, all silently swallowed on error. Empty UI
|
||||
on failure (no error banner). Flag for Step 4.
|
||||
- **`saveSystem()`**:
|
||||
1. Guard: `if (!system) return`.
|
||||
2. `setSaving(true)`.
|
||||
3. `await api.put('/api/annotations/settings/system', system)`.
|
||||
4. `setSaving(false)`.
|
||||
|
||||
No optimistic update needed (the PUT body **is** the local state).
|
||||
No re-fetch — assumes the server echoes the same values. **Error
|
||||
path is missing**: a thrown PUT leaves `saving: true` permanently
|
||||
(no `try/finally`). Flag for Step 4.
|
||||
- **`saveDirs()`** — analogous against
|
||||
`PUT /api/annotations/settings/directories`. Same missing
|
||||
`try/finally` issue.
|
||||
- **`handleToggleDefault(a)`** — duplicate of the same handler in
|
||||
`AdminPage`: `PATCH /api/flights/aircrafts/${a.id}` with
|
||||
`{ isDefault: !a.isDefault }` then optimistic local flip. Two copies
|
||||
of the same logic in two pages — extract to a shared helper or to
|
||||
`FlightContext` in Step 8 (the legacy WPF had a single
|
||||
`AircraftService.SetDefault(...)`).
|
||||
- **`field(label, value, onChange, type='text')`** — local helper that
|
||||
renders a labeled `<input>`. Always controlled (`value={value ?? ''}`).
|
||||
Converts numeric inputs via `parseInt(v) || 0` /
|
||||
`parseFloat(v) || 0` at the call site. Note: `parseInt` / `parseFloat`
|
||||
on an empty string returns `NaN`, and `NaN || 0` is `0` — so
|
||||
clearing a numeric field silently writes `0`, not `null`. Flag for
|
||||
Step 4 against the `SystemSettings` type which permits `null`.
|
||||
- **Layout** — three independent flex children:
|
||||
- Tenant (`w-[300px]` shrink-0): `field()` × 4 + Save.
|
||||
- Directories (`w-[300px]` shrink-0): `field()` × 7 + Save.
|
||||
- Aircrafts (`flex-1 max-w-sm`): list with star toggle.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Internal**:
|
||||
- `../../api/client` — `api`.
|
||||
- `../../types` — `SystemSettings`, `DirectorySettings`, `Aircraft`.
|
||||
- **External**: `react` (`useState`, `useEffect`),
|
||||
`react-i18next` (`useTranslation`).
|
||||
|
||||
## Consumers (intra-repo)
|
||||
|
||||
- `src/App.tsx` — mounted at the `/settings` route inside the
|
||||
protected tree.
|
||||
|
||||
## Data models
|
||||
|
||||
- `SystemSettings` includes `id, name, militaryUnit,
|
||||
defaultCameraWidth, defaultCameraFoV, thumbnailWidth, thumbnailHeight,
|
||||
thumbnailBorder, generateAnnotatedImage, silentDetection`. The page
|
||||
exposes only the first four — every other field is read on GET and
|
||||
echoed back on PUT untouched. Flag if a future cycle needs to expose
|
||||
thumbnails / silent-detection toggles.
|
||||
- `DirectorySettings` has all 7 directory fields exposed as text
|
||||
inputs. Path validation is server-side only.
|
||||
- `Aircraft` (`id, model, type, isDefault`) — same shape as in
|
||||
`AdminPage`.
|
||||
|
||||
## Configuration
|
||||
|
||||
- **i18n keys consumed**: `settings.tenant`, `settings.directories`,
|
||||
`settings.aircrafts`, `settings.save`. (Confirmed in
|
||||
`src/i18n/en.json`.) Hardcoded English labels for every form field
|
||||
("Military Unit", "Name", "Default Camera Width", "Default Camera
|
||||
FoV", "Videos Dir", "Images Dir", "Labels Dir", "Results Dir",
|
||||
"Thumbnails Dir", "GPS Sat Dir", "GPS Route Dir"). Flag for Step 4.
|
||||
- **Tailwind tokens**: `bg-az-panel`, `bg-az-bg`, `bg-az-orange`,
|
||||
`text-az-{text,muted,orange}`, `bg-az-blue/20`, `bg-az-green/20`,
|
||||
`text-az-{blue,green}`, `border-az-border`. Defined in
|
||||
`src/index.css`.
|
||||
|
||||
## External integrations
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| `GET` | `/api/annotations/settings/system` | Load tenant config |
|
||||
| `PUT` | `/api/annotations/settings/system` | Save tenant config |
|
||||
| `GET` | `/api/annotations/settings/directories` | Load directory paths |
|
||||
| `PUT` | `/api/annotations/settings/directories` | Save directory paths |
|
||||
| `GET` | `/api/flights/aircrafts` | Load aircraft list |
|
||||
| `PATCH` | `/api/flights/aircrafts/{id}` | Toggle `isDefault` |
|
||||
|
||||
Routed by `nginx.conf` to `annotations/` and `flights/` backends.
|
||||
|
||||
## Security
|
||||
|
||||
- **No client-side write authorization check** — the page renders the
|
||||
Save buttons for every user. The backend (`annotations/` service)
|
||||
is the authority. Document in `security_approach.md` (Step 6).
|
||||
- **Hardcoded internal directory paths** are **not** present in this
|
||||
file (unlike `AdminPage`'s hardcoded GPS device IP) — every value
|
||||
is server-supplied. Good.
|
||||
- **Path inputs are free-text** — server-side path traversal
|
||||
validation is mandatory. Verify the `annotations/` service rejects
|
||||
e.g. `../../etc/passwd`. Flag for Step 6.
|
||||
- **`saving` state can stick on PUT failure** because there is no
|
||||
`try/finally`, leaving the Save button permanently disabled. Step 4
|
||||
candidate (matches the `AdminPage` "AI/GPS save buttons do
|
||||
nothing" pattern — there is a clear lack of UX-level error
|
||||
handling across both admin/settings pages).
|
||||
|
||||
## Tests
|
||||
|
||||
None.
|
||||
|
||||
## Notes / open questions
|
||||
|
||||
- **Numeric clear-to-zero pitfall**: `parseInt('') || 0` writes `0`
|
||||
for an empty input, not `null`. This silently overwrites a
|
||||
legitimate `null` (per the `SystemSettings` type, all four numeric
|
||||
fields are nullable). Step 4 fix: detect empty input and pass
|
||||
`null`.
|
||||
- **Aircraft toggle handler is duplicated** between `AdminPage` and
|
||||
`SettingsPage` — extract to a shared helper. Step 8.
|
||||
- **No optimistic concurrency**: two admins editing system settings
|
||||
simultaneously will overwrite each other. The `id` field is sent
|
||||
back on PUT but no `version` / `etag` / `If-Match` header. Flag for
|
||||
Step 6 problem-extraction. Backend may not support optimistic
|
||||
concurrency yet.
|
||||
- **The Aircrafts panel is read-only-ish here** but allows the
|
||||
star-toggle, same as `AdminPage`. The duplication suggests an open
|
||||
question: is this intentional (settings is "personal preferences",
|
||||
admin is "global config", but default-aircraft is a *global*
|
||||
setting) or accidental? Surface to the user in Step 6 problem
|
||||
extraction.
|
||||
- **`saving` is a single global flag** even though the page has two
|
||||
independent Save buttons (system / dirs). A user who clicks
|
||||
"Save System" then quickly clicks "Save Dirs" while the first PUT
|
||||
is in flight will see the Dirs button disabled too. Acceptable
|
||||
given the latency budget; flag if both saves become slow.
|
||||
- **`thumbnailWidth/Height/Border` and `generateAnnotatedImage`,
|
||||
`silentDetection`** in `SystemSettings` are not exposed in the UI
|
||||
but are echoed back on PUT. If a future cycle adds them, ensure the
|
||||
GET → PUT round-trip preserves any concurrent change made by another
|
||||
client between the GET and the PUT.
|
||||
@@ -0,0 +1,55 @@
|
||||
# Module: `src/hooks/useDebounce.ts`
|
||||
|
||||
> **Source**: `src/hooks/useDebounce.ts` (12 lines)
|
||||
> **Topo batch**: B1 (leaf)
|
||||
|
||||
## Purpose
|
||||
|
||||
Generic React hook that delays propagation of a rapidly-changing value to its consumers, used to throttle search inputs against the backend.
|
||||
|
||||
## Public interface
|
||||
|
||||
```ts
|
||||
export function useDebounce<T>(value: T, delay: number): T
|
||||
```
|
||||
|
||||
Returns the latest `value` only after `delay` milliseconds have elapsed without any further change. Generic in `T`, so callers can debounce strings, numbers, or any reference value (referential identity matters; see notes).
|
||||
|
||||
## Internal logic
|
||||
|
||||
`useState<T>(value)` for the debounced output; `useEffect` registers a `setTimeout(setDebounced, delay)` and returns a `clearTimeout` cleanup. The effect re-runs whenever `value` or `delay` changes — each new input value cancels the pending timeout from the previous render and starts a fresh one.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Internal**: none.
|
||||
- **External**: `react` (`useState`, `useEffect`).
|
||||
|
||||
## Consumers (intra-repo)
|
||||
|
||||
- `src/features/annotations/MediaList.tsx` — debounces the media-name search input.
|
||||
- `src/features/dataset/DatasetPage.tsx` — debounces the dataset name-search filter (specified as 400ms in `_docs/ui_design/README.md` §"Dataset Explorer", but the actual delay is set by the caller).
|
||||
|
||||
## Data models
|
||||
|
||||
None.
|
||||
|
||||
## Configuration
|
||||
|
||||
None.
|
||||
|
||||
## External integrations
|
||||
|
||||
None.
|
||||
|
||||
## Security
|
||||
|
||||
None.
|
||||
|
||||
## Tests
|
||||
|
||||
None.
|
||||
|
||||
## Notes / open questions
|
||||
|
||||
- The hook compares values by referential equality (`useEffect` deps array). Passing a fresh object literal each render — e.g. `useDebounce({ q }, 300)` — would re-trigger the timer endlessly. Current callers pass primitives only; safe.
|
||||
- No "leading edge" / "trailing edge" / "max wait" knobs. Adequate for the two current consumers; if/when richer behaviour is needed, prefer `useDebouncedCallback` from a library over extending this module.
|
||||
@@ -0,0 +1,70 @@
|
||||
# Module: `src/hooks/useResizablePanel.ts`
|
||||
|
||||
> **Source**: `src/hooks/useResizablePanel.ts` (33 lines)
|
||||
> **Topo batch**: B1 (leaf)
|
||||
|
||||
## Purpose
|
||||
|
||||
React hook that backs a draggable splitter between two horizontally-arranged panels. Owns the panel width as state and exposes a mouse handler the host attaches to the splitter element.
|
||||
|
||||
## Public interface
|
||||
|
||||
```ts
|
||||
export function useResizablePanel(
|
||||
initialWidth: number,
|
||||
min?: number, // default 100
|
||||
max?: number, // default 600
|
||||
): {
|
||||
width: number
|
||||
onMouseDown: (e: React.MouseEvent) => void
|
||||
setWidth: React.Dispatch<React.SetStateAction<number>>
|
||||
}
|
||||
```
|
||||
|
||||
`width` is the current panel width (px). `onMouseDown` should be wired to the splitter element. `setWidth` is exposed for programmatic resets — currently unused by callers but kept for parity with the persistence story (see Notes).
|
||||
|
||||
## Internal logic
|
||||
|
||||
1. `useState(initialWidth)` for `width`.
|
||||
2. Drag bookkeeping is held in three `useRef` cells (`dragging`, `startX`, `startWidth`) — kept out of state so the move/up handlers never re-render the host.
|
||||
3. `onMouseDown` (memoized via `useCallback([width])`) snapshots `clientX` and `width`, marks `dragging = true`, and calls `e.preventDefault()` to avoid triggering text selection.
|
||||
4. A `useEffect` registers global `mousemove` / `mouseup` listeners on `window`. While `dragging.current === true`, `mousemove` updates `width` to `clamp(startWidth + (e.clientX - startX), min, max)`. `mouseup` flips `dragging` back to `false`.
|
||||
5. The effect cleans up on unmount.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Internal**: none.
|
||||
- **External**: `react` (`useState`, `useCallback`, `useRef`, `useEffect`).
|
||||
|
||||
## Consumers (intra-repo)
|
||||
|
||||
- `src/features/annotations/AnnotationsPage.tsx` — left + right panel widths.
|
||||
- `src/features/dataset/DatasetPage.tsx` — left + right panel widths.
|
||||
|
||||
Both pages persist their layout server-side via `UserSettings.{annotationsLeftPanelWidth, annotationsRightPanelWidth, datasetLeftPanelWidth, datasetRightPanelWidth}` (see `src/types/index.ts`). The persistence read/write happens in the page, not in this hook.
|
||||
|
||||
## Data models
|
||||
|
||||
None.
|
||||
|
||||
## Configuration
|
||||
|
||||
None.
|
||||
|
||||
## External integrations
|
||||
|
||||
DOM only — `window.addEventListener('mousemove' / 'mouseup')`.
|
||||
|
||||
## Security
|
||||
|
||||
None.
|
||||
|
||||
## Tests
|
||||
|
||||
None.
|
||||
|
||||
## Notes / open questions
|
||||
|
||||
- The hook is keyboard- and touch-blind: only mouse drag is supported, so accessibility for non-pointer input is missing. Track for the broader a11y pass; out of scope for `/document`.
|
||||
- `setWidth` is exposed but no current caller hydrates `initialWidth` from `UserSettings` via it — they pass the persisted width directly to `useResizablePanel(persistedWidth)` on mount. If the persisted width arrives **after** mount (asynchronous load), the panel jumps. Flag for the consumers' module docs (B8).
|
||||
- Default bounds (100 / 600) are arbitrary; consumer pages may want different ceilings (e.g., the annotations sidebar). Currently both consumers accept the defaults.
|
||||
@@ -0,0 +1,64 @@
|
||||
# Module: `src/i18n/i18n.ts`
|
||||
|
||||
> **Source**: `src/i18n/i18n.ts` (13 lines)
|
||||
> **Topo batch**: B2 (depends only on JSON data files)
|
||||
|
||||
## Purpose
|
||||
|
||||
Module-load-time initialisation of `i18next` with the `react-i18next` adapter. Imports the English and Ukrainian translation tables and registers them as the available `resources`. Exporting the configured singleton lets call sites use `useTranslation()` directly.
|
||||
|
||||
## Public interface
|
||||
|
||||
```ts
|
||||
export default i18n // configured i18next instance
|
||||
```
|
||||
|
||||
## Internal logic
|
||||
|
||||
```ts
|
||||
i18n.use(initReactI18next).init({
|
||||
resources: { en: { translation: en }, ua: { translation: ua } },
|
||||
lng: 'en',
|
||||
fallbackLng: 'en',
|
||||
interpolation: { escapeValue: false },
|
||||
})
|
||||
```
|
||||
|
||||
- `lng: 'en'` is hardcoded at boot. There is **no** runtime mechanism to detect the user's locale or to read a saved preference. Switching language at runtime works (via `i18n.changeLanguage(...)`) but the page reload always lands on English first.
|
||||
- `escapeValue: false` is the documented default for React (which already escapes JSX text).
|
||||
- Module side-effect at top level: `init()` runs as soon as `src/main.tsx` imports this file.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Internal**: `./en.json`, `./ua.json` (JSON imports — Vite handles).
|
||||
- **External**: `i18next`, `react-i18next`.
|
||||
|
||||
## Consumers (intra-repo)
|
||||
|
||||
- `src/main.tsx` — side-effect import (`import './i18n/i18n'`).
|
||||
- Indirectly: every component that calls `useTranslation()` from `react-i18next` (e.g. `ConfirmDialog`, `HelpModal`, `JsonEditorDialog`, …).
|
||||
|
||||
## Data models
|
||||
|
||||
The two JSON resource files (`en.json`, `ua.json`) define the key namespace. Per `_docs/ui_design/README.md` §"Localization" and `_docs/legacy/wpf-era.md` §10, the SPA must support EN + UA at parity. Inspection of the JSON files (deferred to Step 4 verification) will confirm whether parity is held.
|
||||
|
||||
## Configuration
|
||||
|
||||
`lng: 'en'` and `fallbackLng: 'en'` are inlined. `localStorage` persistence (e.g., via `i18next-browser-languagedetector`) would be the natural Step 8 enhancement for "remember user choice"; deferred.
|
||||
|
||||
## External integrations
|
||||
|
||||
None.
|
||||
|
||||
## Security
|
||||
|
||||
`escapeValue: false` is correct in React but would be unsafe if any consumer rendered translation values via `dangerouslySetInnerHTML`. None do (verify in Step 4).
|
||||
|
||||
## Tests
|
||||
|
||||
None.
|
||||
|
||||
## Notes / open questions
|
||||
|
||||
- The `mission-planner/` sub-project does NOT use `react-i18next` — it has its own `LanguageContext` + raw `translations` table (see `00_discovery.md` §11 finding 8). The port to `src/features/flights/` should consume this module instead. Track for MP-B3.
|
||||
- Adding a third language is a one-line edit (`resources: { en, ua, <new> }`) plus a JSON file. Document the procedure in the final `solution.md`.
|
||||
@@ -0,0 +1,83 @@
|
||||
# Module: `src/types/index.ts`
|
||||
|
||||
> **Source**: `src/types/index.ts` (161 lines)
|
||||
> **Topo batch**: B1 (leaf — no internal imports)
|
||||
|
||||
## Purpose
|
||||
|
||||
Shared TypeScript contract surface for the SPA: pure type aliases, interfaces, and numeric enums describing the DTOs that travel between the React UI and the suite backends (`admin/`, `annotations/`, `flights/`, `loader/`, etc.).
|
||||
|
||||
## Public interface
|
||||
|
||||
Generic shape:
|
||||
|
||||
| Symbol | Kind | Notes |
|
||||
|---|---|---|
|
||||
| `PaginatedResponse<T>` | `interface` | `{ items, totalCount, page, pageSize }`. Returned by paged list endpoints (e.g., `GET /api/flights?pageSize=...`). |
|
||||
|
||||
Domain entities (mirroring backend DTOs):
|
||||
|
||||
| Symbol | Kind | Backing concept |
|
||||
|---|---|---|
|
||||
| `Media` | `interface` | A media file (image / video) attached to a flight. Fields: `id, name, path, mediaType, mediaStatus, duration, annotationCount, waypointId, userId`. |
|
||||
| `Detection` | `interface` | A bounding box. Fields: `id, classNum, label, confidence, affiliation, combatReadiness, centerX, centerY, width, height` (normalized 0–1 coords, see `_docs/legacy/wpf-era.md` §10). |
|
||||
| `AnnotationListItem` | `interface` | A frame's annotation set. `time` is `string \| null` (ISO duration), `splitTile` carries tile zoom info for split-image detections. Embeds `Detection[]`. |
|
||||
| `DetectionClass` | `interface` | Admin-managed detection class metadata (`id, name, shortName, color, maxSizeM, photoMode`). Drives the Detection Classes panel + GSD validation. |
|
||||
| `Flight`, `Aircraft`, `Waypoint` | `interface` | Flight feature entities. `Aircraft.type` is union `'Plane' \| 'Copter'`. |
|
||||
| `SystemSettings`, `DirectorySettings`, `CameraSettings`, `UserSettings` | `interface` | Settings domain. `UserSettings` carries the global `selectedFlightId` plus per-page panel widths persisted server-side via the annotations API (see `src/components/FlightContext.tsx`). |
|
||||
| `DatasetItem` | `interface` | Row in the Dataset Explorer grid (`annotationId, imageName, thumbnailPath, status, createdDate, createdEmail, flightName, source, isSeed, isSplit`). |
|
||||
| `ClassDistributionItem` | `interface` | Aggregate row for the Class Distribution chart. |
|
||||
| `User` | `interface` | Admin user list row. |
|
||||
| `AuthUser` | `interface` | Authenticated session user (`id, email, name, role, permissions[]`); used by `AuthContext`. |
|
||||
|
||||
Numeric enums (must match backend wire values bit-for-bit):
|
||||
|
||||
| Enum | Members | Used by |
|
||||
|---|---|---|
|
||||
| `MediaType` | `None=0, Image=1, Video=2` | media list, video player branching |
|
||||
| `MediaStatus` | `New=0, AiProcessing=1, AiProcessed=2, ManualCreated=3` | media list state |
|
||||
| `AnnotationSource` | `AI=0, Manual=1` | annotation provenance |
|
||||
| `AnnotationStatus` | `Created=0, Edited=1, Validated=2` | dataset filter buttons |
|
||||
| `Affiliation` | `Unknown=0, Friendly=1, Hostile=2` | bounding-box icon (see `_docs/legacy/wpf-era.md` §10) |
|
||||
| `CombatReadiness` | `NotReady=0, Ready=1` | bounding-box readiness dot |
|
||||
|
||||
## Internal logic
|
||||
|
||||
None. Declarations file only.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Internal**: none (true leaf).
|
||||
- **External**: none.
|
||||
|
||||
## Consumers (intra-repo)
|
||||
|
||||
`src/auth/AuthContext.tsx`, `src/components/FlightContext.tsx`, `src/components/Header.tsx`, `src/components/DetectionClasses.tsx`, `src/api/*` (none directly — API calls are typed at call sites), every page under `src/features/*` except `src/features/login/LoginPage.tsx`. Roughly 15 importing files.
|
||||
|
||||
## Data models
|
||||
|
||||
The whole module **is** the data-model surface for the SPA. Two implicit constraints:
|
||||
|
||||
1. **Numeric enum values are wire-coupled** — changing them silently breaks every backend that returns the same number. Treated as a public contract; downstream changes must coordinate with the corresponding `.NET` / Cython service.
|
||||
2. **`*.id` is `string`** for every entity (suite uses GUIDs), but `Detection.classNum` and the four enums are `number`. Mixed-key shapes are intentional.
|
||||
|
||||
## Configuration
|
||||
|
||||
None.
|
||||
|
||||
## External integrations
|
||||
|
||||
None directly. The types are the *contract* surface for HTTP responses from `/api/admin/*`, `/api/annotations/*`, `/api/flights/*`. Ground truth for shapes lives in the respective backend submodule (`suite/admin/`, `suite/annotations/`, `suite/flights/`).
|
||||
|
||||
## Security
|
||||
|
||||
`AuthUser.permissions: string[]` is the only security-relevant field — checked by `AuthContext.hasPermission(perm)`. The permission strings are not enumerated here; they are defined by the `admin/` service.
|
||||
|
||||
## Tests
|
||||
|
||||
None.
|
||||
|
||||
## Notes / open questions
|
||||
|
||||
- `Media.duration` is `string | null` rather than `number | null` — this matches a `TimeSpan`-style ISO duration the backend returns. Document the format precisely once the consumer (`VideoPlayer`) is reached in B7.
|
||||
- `UserSettings` mixes "selected flight" with "per-page panel widths" — possibly a candidate for splitting along ownership lines, but the API endpoint (`/api/annotations/settings/user`) treats them as one document. Out of scope for `/document`.
|
||||
@@ -0,0 +1,126 @@
|
||||
{
|
||||
"current_step": "complete",
|
||||
"completed_steps": ["discovery", "module-analysis", "component-assembly", "module-layout", "system-synthesis", "verification-pass", "glossary-and-vision", "solution-extraction", "problem-extraction", "final-report"],
|
||||
"focus_dir": null,
|
||||
"scope": {
|
||||
"included": ["src/", "mission-planner/"],
|
||||
"excluded": ["node_modules/", "dist/", ".cursor/", "_docs/legacy/", "_docs/ui_design/", "mission-planner/public/"],
|
||||
"mode": "merge"
|
||||
},
|
||||
"modules_total": 77,
|
||||
"modules_documented_count": 77,
|
||||
"modules_documented": [
|
||||
"src/types/index.ts",
|
||||
"src/hooks/useDebounce.ts",
|
||||
"src/hooks/useResizablePanel.ts",
|
||||
"src/features/annotations/classColors.ts",
|
||||
"src/api/client.ts",
|
||||
"src/api/sse.ts",
|
||||
"src/i18n/i18n.ts",
|
||||
"src/components/HelpModal.tsx",
|
||||
"src/components/ConfirmDialog.tsx",
|
||||
"src/components/DetectionClasses.tsx",
|
||||
"src/auth/AuthContext.tsx",
|
||||
"src/components/FlightContext.tsx",
|
||||
"src/auth/ProtectedRoute.tsx",
|
||||
"src/components/Header.tsx",
|
||||
"src/features/login/LoginPage.tsx",
|
||||
"src/features/admin/AdminPage.tsx",
|
||||
"src/features/settings/SettingsPage.tsx",
|
||||
"src/features/flights/* (15 modules: types, mapIcons, flightPlanUtils, AltitudeChart, AltitudeDialog, MiniMap, WaypointList, WindEffect, MapPoint, DrawControl, FlightListSidebar, JsonEditorDialog, FlightParamsPanel, FlightMap, FlightsPage) — consolidated into src__features__flights.md",
|
||||
"src/features/annotations/* (5 modules: CanvasEditor, VideoPlayer, AnnotationsSidebar, MediaList, AnnotationsPage) — consolidated into src__features__annotations.md",
|
||||
"src/features/dataset/DatasetPage.tsx",
|
||||
"src/App.tsx + src/main.tsx — combined into src__App-and-main.md",
|
||||
"mission-planner/* (37 modules across services/, flightPlanning/, icons/, constants/, types/, utils.ts, config.ts, main.tsx) — consolidated into mission-planner.md"
|
||||
],
|
||||
"modules_remaining": [],
|
||||
"module_doc_files": 22,
|
||||
"module_doc_total_lines": 2225,
|
||||
"consolidation_decisions": {
|
||||
"src/features/flights/": "single doc — was over-weighted with 8 individual docs averaging ~100 lines each; user feedback 2026-05-10",
|
||||
"src/features/annotations/": "single doc — central concern but compact format",
|
||||
"mission-planner/": "single doc — port-source not deployed, deletion candidate after parity"
|
||||
},
|
||||
"components_written": [
|
||||
"00_foundation",
|
||||
"01_api-transport",
|
||||
"02_auth",
|
||||
"03_shared-ui",
|
||||
"04_login",
|
||||
"05_flights",
|
||||
"06_annotations",
|
||||
"07_dataset",
|
||||
"08_admin",
|
||||
"09_settings",
|
||||
"10_app-shell",
|
||||
"11_class-colors"
|
||||
],
|
||||
"component_11_class-colors_extracted_2026-05-10": "Per user direction at the Step 2 BLOCKING gate, classColors is its own component (Layer 1 shared kernel). It is consumed by 03_shared-ui (DetectionClasses), 06_annotations, and 07_dataset. The physical file still lives at src/features/annotations/classColors.ts; the misplaced location is a Step 4 testability candidate, not a Step 2 concern.",
|
||||
"component_05_flights_merge_2026-05-10": "Per user direction at the Step 2 BLOCKING gate, mission-planner/ is documented INSIDE 05_flights as the port-source for src/features/flights/. The previously drafted 11_mission-planner/ component was deleted. GPS-Denied is now an explicit sub-feature of 05_flights with two tabs (Operations + Test Mode); Test Mode is the unimplemented tlog+video→SITL→onboard flow per _docs/how_to_test.md.",
|
||||
"legacy_coverage_gaps_2026-05-10": "Per user direction at the Step 2 BLOCKING gate, cross-checked the React port against suite/annotations-research/ (legacy WPF source, commit 22529c2 — see _docs/legacy/wpf-era.md). Per-component delta tables added to components/06_annotations/description.md §6b (~17 entries) and components/07_dataset/description.md §6b (~12 entries). Single-page rollup at _docs/02_document/01_legacy_coverage_gaps.md. Highest-impact gaps: (a) keyboard shortcuts entirely missing (Space/Left/Right/Enter/Del/X/M/R/K), (b) volume slider + status-bar clock + status-bar help-text missing in Annotations, (c) Class Distribution chart tab entirely missing in Dataset, (d) Sound Detections + Drone Maintenance features unmentioned in legacy doc §10 — port-or-drop decision required at Step 4.5. The 4× wide time-window (finding #6) and 16% gradient cap (finding #9) are confirmed via WPF source: WPF uses _thresholdBefore=50ms / _thresholdAfter=150ms.",
|
||||
"module_layout_2026-05-10": "Step 2.5 produced _docs/02_document/module-layout.md. Status: derived-from-code. Layering: L0={00_foundation,11_class-colors}; L1={01_api-transport}; L2={02_auth,03_shared-ui}; L3={04_login,05_flights,06_annotations,07_dataset,08_admin,09_settings}; L4={10_app-shell}. 8 verification questions surfaced for user (file-move scheduling for class-colors and CanvasEditor; barrel exports; mission-planner/ ownership; cycle inside port-source; foundation multi-dir; app-shell file list; test layout TBD).",
|
||||
"system_synthesis_2026-05-10": "Step 3 produced architecture.md, system-flows.md, data_model.md, deployment/{containerization,ci_cd_pipeline,environment_strategy,observability}.md. 12 system flows documented (F1-F12); F7 (video AI detect SSE) and F12 (GPS-Denied Test Mode) flagged as planned/broken. 10 ADRs recorded (SPA over SSR, REST+SSE only, HTML5 video, React Context only, Tailwind+az-* tokens, nginx /api proxy, bilingual UI, bearer-in-query SSE, mission-planner port-source, GPS-Denied Test Mode as sub-feature). Data model captures full enum drift (AnnotationStatus, MediaStatus, Affiliation, CombatReadiness, Waypoint shape) for Step 4 fix.",
|
||||
"step_4_5_glossary_vision": "confirmed",
|
||||
"last_updated": "2026-05-10T15:55:00+03:00",
|
||||
"notes": [
|
||||
"2026-05-10 02:25Z — Inline enum comments added to all numeric enum fields in parent-suite JSON examples (user feedback). Files: _docs/01_annotations.md §5, _docs/09_dataset_explorer.md §1/§2/§4. Code fences switched from `json` to `jsonc` for syntactic validity of the // comments. Column-aligned style for readability. Total numeric enum sites annotated: 11.",
|
||||
"2026-05-10 02:18Z — Parent-suite-doc fixes APPLIED (cross-repo edits):",
|
||||
" - /Users/obezdienie001/dev/azaion/suite/_docs/01_annotations.md: AnnotationSource enum table got Wire-value column (AI=0, Manual=1); added top-of-file 'wire format is numeric' note; §5 response example rewritten with numeric source/status/affiliation/combatReadiness + inline name comments.",
|
||||
" - /Users/obezdienie001/dev/azaion/suite/_docs/09_dataset_explorer.md: AnnotationStatus table column renamed Value→Wire value; added 'wire format is numeric' note; §1 response example added isSplit:false + numeric status/source + paragraph linking isSplit to 03_detections.md §4 Tile-Based Detection; §2 response example numeric; §4 bulk-status request numeric.",
|
||||
" - _docs/_process_leftovers/2026-05-10_parent-suite-doc-fixes.md DELETED (replayed).",
|
||||
" - Findings #31 and #33 in src__features__annotations.md retagged [RESOLVED 2026-05-10 — PARENT-DOC FIX APPLIED]. DatasetPage finding #14 isSplit half retagged RESOLVED.",
|
||||
" - Two git commits will need to land (separately) on this repo and the parent suite repo. Asking the user before committing.",
|
||||
"2026-05-10 02:13Z — User decisions applied to enum-drift findings:",
|
||||
" - DECISION: AnnotationStatus spec wins → UI fix (Step 4). Change src/types/index.ts to None=0, Created=10, Edited=20, Validated=30, Deleted=40.",
|
||||
" - DECISION: Affiliation spec wins → UI fix (Step 4). UI must add 'None' value; integers TBD via .NET service inspection.",
|
||||
" - DECISION: CombatReadiness spec wins → UI fix (Step 4). UI must add 'Unknown'; integers TBD.",
|
||||
" - DECISION: MediaStatus spec wins → UI fix (Step 4). UI must add 'None', 'Confirmed', 'Error'; integers TBD.",
|
||||
" - DECISION: AnnotationSource numeric (UI) wins → cross-repo PARENT-DOC FIX. Parent suite _docs/01_annotations.md §5 response example shows strings; rewrite as numerics. NO UI change. Recorded in _docs/_process_leftovers/2026-05-10_parent-suite-doc-fixes.md.",
|
||||
" - DECISION: handleSave required parameters → UI fix (Step 4). Body must add Source, WaypointId; rename time→videoTime. Full target body shape now in finding #32.",
|
||||
" - DECISION: DatasetItem.isSplit → cross-repo PARENT-DOC FIX. Parent suite _docs/09_dataset_explorer.md §1 response schema must add isSplit. NO UI change. Recorded in _docs/_process_leftovers/2026-05-10_parent-suite-doc-fixes.md.",
|
||||
" - DECISION: X-Refresh-Token is conditionally required (long video > 1h access-token TTL per _docs/10_auth.md). UI fix (Step 4). Send for all video detect requests; flag the rotation caveat for Step 4 design.",
|
||||
"Findings #27-30, #32, #34 in src__features__annotations.md retagged [STEP 4 — UI FIX]. Findings #31 and #33 retagged [NO UI CHANGE — PARENT-DOC FIX]. DatasetPage.md finding #14 split into the two cross-link halves.",
|
||||
"2026-05-10 02:01Z — Consistency cross-check pass complete. Verified every claim in the 5 newly-created consolidated docs against _docs/ui_design/{README.md,annotations.html,flights.html,dataset_explorer.html} and against parent suite _docs/{00_roles_permissions, 00_top_level_architecture, 01_annotations, 02_flights, 03_detections, 09_dataset_explorer, 11_gps_denied}.md. Patches applied:",
|
||||
" - PATCH src__features__annotations.md #6: time-window math corrected — implementation is ±200 ms (400 ms total), 4× wider than spec's asymmetric 50 ms+150 ms (200 ms total). Earlier draft said 'symmetric 200 ms' — wrong on both width and centring.",
|
||||
" - PATCH src__features__annotations.md #9: gradient cap math corrected — `* 40` is decimal, max alpha = 0x28 = 16% opacity, not 0x40 = 25% as the wireframe demands. Spec drift is worse than originally written.",
|
||||
" - PATCH src__features__annotations.md endpoint paragraph: removed the 'POST /api/detect/{mediaId} does NOT match suite' claim — it does match after nginx proxy strip. Replaced with the genuine gap: missing X-Refresh-Token header for long-running video.",
|
||||
" - PATCH src__features__annotations.md added 8 new findings (#27–34) for HIGH-PRIORITY enum drift between src/types/index.ts and parent suite spec: AnnotationStatus (UI 0/1/2 vs spec 0/10/20/30 — wire payloads will be wrong), Affiliation (UI missing 'None'), CombatReadiness (UI missing 'Unknown'), MediaStatus (UI missing 'None'/'Confirmed'/'Error' — cannot render error state), AnnotationSource numeric vs spec string serialization risk, handleSave body missing Source/WaypointId, DatasetItem.isSplit not in spec response, Detect missing X-Refresh-Token header.",
|
||||
" - PATCH src__features__flights.md #20: waypoint POST shape mismatch is severe — UI sends {name, latitude, longitude, order}; spec wants {Geopoint:{Lat,Lon,MGRS}, Source, Objective, OrderNum, Height}. Likely 400s on a strict server; collides with finding #19 (delete-then-recreate). Marked PRIORITY for Step 4.",
|
||||
" - PATCH src__App-and-main.md: removed the 'No mobile bottom-nav route layout' finding — Header.tsx:113-129 DOES render a mobile bottom nav. Refined the role-gate finding: /admin gap is real and PRIORITY; /settings is more nuanced (no SETTINGS permission code in spec; server-enforced via 403). Renumbered findings 1-4.",
|
||||
" - PATCH src__features__dataset__DatasetPage.md added finding #14: cross-link to the AnnotationStatus enum drift and DatasetItem.isSplit type-vs-spec gap (these surface as wrong status filter values on the wire).",
|
||||
"ENUM DRIFT IS THE BIGGEST CROSS-CUTTING FINDING: 4 enums (AnnotationStatus, Affiliation, CombatReadiness, MediaStatus) and one type (Waypoint) have value sets and shapes that do NOT match the parent suite contract. Any wire payload using these will be wrong. Owner of fix: src/types/index.ts (single file). Step 4 will need to confirm via .NET service before patching to avoid making the UI 'right' against a server that's actually using the UI's shape. Open for Step 6.",
|
||||
"(All other findings below are pre-cross-check and remain valid.)",
|
||||
"Module count 77 = 40 (src/) + 37 (mission-planner/). All 77 covered across 22 doc files.",
|
||||
"Doc consolidation 2026-05-10 (user feedback): 8 individual flights/* docs deleted and replaced with one src__features__flights.md; brevity standard tightened (no code blocks, ≤200 lines per doc except for two large pages — admin 215, settings 181 — pre-consolidation).",
|
||||
"Findings flagged during B1+B2+B3 (carry into Step 4 verification + Step 6 security_approach):",
|
||||
" - HARDCODED OPENWEATHER API KEY in src/features/flights/flightPlanUtils.ts:60 ('335799082893fad97fa36118b131f919') — committed secret, must rotate at OpenWeatherMap + remove + proxy via suite. Source-code fix scheduled for autodev Step 4. Upstream rotation is a user action (parallel track).",
|
||||
" - src/features/flights/flightPlanUtils.ts: silently swallows weather errors; sequential await per segment (perf trap); ambiguous battery-capacity unit (Wh vs Ws); mixes km / m altitudes.",
|
||||
" - src/features/flights/mapIcons.ts: defaultIcon CDN URL pinned to leaflet@1.7.1 while package uses 1.9.4.",
|
||||
" - src/i18n/i18n.ts: lng:'en' hardcoded; no detector / persistence.",
|
||||
" - src/components/HelpModal.tsx: GUIDELINES hardcoded in source instead of i18n bundle; Esc does NOT close (inconsistent with ConfirmDialog).",
|
||||
" - src/features/annotations/classColors.ts: getPhotoModeSuffix duplicates the typed DetectionClass.photoMode field — likely redundant; possible deletion after typed propagation.",
|
||||
" - Cross-layer imports (00_discovery.md §8): components/DetectionClasses ← features/annotations/classColors; features/dataset ← features/annotations/CanvasEditor.",
|
||||
" - B3: src/auth/AuthContext.tsx bootstrap calls api.get('/api/admin/auth/refresh') WITHOUT credentials:'include' — likely a real bug. PRIORITY for Step 4.",
|
||||
" - B3: src/components/DetectionClasses.tsx number-key shortcut (1–9) indexes classes[idx + photoMode] — verify ordering against the annotations/ service contract in Step 4.",
|
||||
" - B3: src/components/FlightContext.tsx hardcodes pageSize=1000 ceiling; selectFlight is fire-and-forget PUT.",
|
||||
" - B3: src/api/sse.ts puts bearer in query string — accepted trade-off but document in security_approach.md (Step 6); EventSource holds onto the token captured at create time and will error after a refresh-rotation, no consumer reconnects today (Step 8 hardening).",
|
||||
" - B3: ConfirmDialog.tsx has no aria-modal / role=dialog — flag for Step 4 against ui_design/README.md confirmation-dialogs spec.",
|
||||
"Findings flagged during B4 (carry into Step 4 + Step 6):",
|
||||
" - B4: src/features/admin/AdminPage.tsx — AI Settings & GPS Settings forms render with defaultValue only; NO state, NO submit handler, the Save button does nothing. PRIORITY surface in Step 6 problem-extraction.",
|
||||
" - B4: src/features/admin/AdminPage.tsx — hardcoded GPS device default '192.168.1.100' / port '5535' shipped in production bundle. Step 4.",
|
||||
" - B4: src/features/admin/AdminPage.tsx — handleDeleteClass has NO ConfirmDialog despite being destructive. Flag for Step 4 vs ui_design/README.md.",
|
||||
" - B4: src/features/admin/AdminPage.tsx — detection-class read uses /api/annotations/classes (annotations/ service) but write uses /api/admin/classes (admin/ service). Verify with suite ADRs in Step 3a.",
|
||||
" - B4: src/features/admin/AdminPage.tsx + SettingsPage.tsx — handleToggleDefault duplicated; aircraft default is global config, page also exists in both /admin and /settings. Surface intent in Step 6.",
|
||||
" - B4: src/features/admin/AdminPage.tsx — many hardcoded English strings. Step 4.",
|
||||
" - B4: src/features/settings/SettingsPage.tsx — saveSystem / saveDirs lack try/finally; PUT failure leaves saving:true permanently. Step 4.",
|
||||
" - B4: src/features/settings/SettingsPage.tsx — numeric inputs use parseInt(v) || 0 — clearing a field silently writes 0. Step 4.",
|
||||
" - B4: src/features/settings/SettingsPage.tsx — no optimistic concurrency. Step 6 problem-extraction.",
|
||||
" - B4: src/features/login/LoginPage.tsx — runUnlockSequence is theatrical (4×600ms). Document in Step 5 solution.md.",
|
||||
" - B4: src/components/Header.tsx — outside-click handler always attached; flight dropdown lacks role=combobox / aria-expanded / Esc-to-close / focus trap. Step 4 + Step 8.",
|
||||
" - B4: src/auth/ProtectedRoute.tsx — spinner has no role='status' / accessible label; no timeout on loading state. Joint with Step 4 client.ts timeout flag.",
|
||||
"Findings consolidated into src__features__flights.md (26 numbered items): flightPlanUtils.ts security/perf/units, MiniMap licence/responsive, AltitudeDialog/JsonEditorDialog modal a11y, WaypointList drag/touch a11y, AltitudeChart bundle bloat, FlightsPage save N+M round-trips + lossy waypoint POST, GPS-Denied panel partial, mock aircraft override, etc.",
|
||||
"Findings consolidated into src__features__annotations.md (26 numbered items): VideoPlayer hardcoded fps=30, CanvasEditor missing pan / wrong time-window / missing affiliation icons / missing CR indicator / dead AFFILIATION_COLORS, AnnotationsSidebar AI-detect doesn't stream progress / silent catches, AnnotationsPage no SSE detect subscription / no panel-width persistence / handleDownload tainted-canvas risk / handleSave fallback hides save loss, MediaList alert() / blob: locals ignore filter, missing keyboard shortcuts (R, V, PageUp/Down), missing Camera config side panel, missing Tile zoom for splitTile.",
|
||||
"Findings consolidated into src__features__dataset__DatasetPage.md (13 numbered items): no keyboard shortcuts, no Refresh thumbnails, no virtualisation, editor tab doesn't save, magic mediaType=1, dead ConfirmDialog import, silent catches, status filter conflates None with All, classNum=0 sentinel collides with real class 0.",
|
||||
"Findings consolidated into src__App-and-main.md (5 items): no role-based route guards on /admin or /settings (PRIORITY — security), no mobile bottom-nav route layout, no ErrorBoundary, no lazy chunks, /flights default for everyone."
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,656 @@
|
||||
# Azaion UI — System Flows
|
||||
|
||||
> Synthesis output of `/document` Step 3b. Each flow is grounded in component
|
||||
> specs (`components/*/description.md`) and module docs (`modules/*.md`). When a
|
||||
> step references a finding (e.g., #14), the source is one of:
|
||||
> `_docs/02_document/modules/src__features__annotations.md`,
|
||||
> `..__flights.md`, `..__dataset__DatasetPage.md`, or `..__App-and-main.md`.
|
||||
|
||||
## Flow Inventory
|
||||
|
||||
| # | Flow Name | Trigger | Primary Components | Criticality |
|
||||
|---|-----------|---------|--------------------|-------------|
|
||||
| F1 | Login | User submits `/login` form | `04_login`, `02_auth`, `admin/` | High |
|
||||
| F2 | Bearer auto-refresh on 401 | Any authenticated fetch returns 401 | `02_auth`, `01_api-transport`, `admin/` | High |
|
||||
| F3 | Select active flight | User picks a flight in Header dropdown | `03_shared-ui` (FlightContext + Header), `flights/` + `annotations/settings/user` | High |
|
||||
| F4 | Create / save flight + waypoints | User clicks Save in `FlightsPage` | `05_flights`, `flights/` | High |
|
||||
| F5 | Annotate media (manual bbox) | User drags on canvas | `06_annotations`, `annotations/` | High |
|
||||
| F6 | AI Detect — image (sync) | User clicks AI Detect with image selected | `06_annotations`, `detect/` | Medium |
|
||||
| F7 | AI Detect — video (async) — **NOT WIRED** | User clicks AI Detect with video selected | (target) `06_annotations`, `detect/`, `01_api-transport/sse.ts` | High |
|
||||
| F8 | Dataset browse + filter | User opens `/dataset` | `07_dataset`, `annotations/` | Medium |
|
||||
| F9 | Dataset bulk-validate | User selects thumbnails + Validate (planned, missing today) | `07_dataset`, `annotations/` | Medium |
|
||||
| F10 | Admin: detection class CRUD | User edits in `/admin` | `08_admin`, `admin/` (write) + `annotations/` (read) | High |
|
||||
| F11 | Settings: persist user prefs | User saves panel widths / system / camera | `09_settings`, `annotations/` (system/dirs/user) + `flights/` (aircraft) | Medium |
|
||||
| F12 | GPS-Denied Test Mode (planned) | User uploads `.tlog` + video | `05_flights` (Test Mode tab), `gps-denied-desktop/`, `gps-denied-onboard/` | Medium (planned) |
|
||||
| F13 | Live-GPS aircraft telemetry (SSE) | User opens FlightsPage with selected flight | `05_flights/FlightsPage`, `flights/` (`/api/flights/${id}/live-gps` SSE) | Medium |
|
||||
| F14 | Annotation-status events (SSE) | User opens AnnotationsPage with selected media | `06_annotations/AnnotationsSidebar`, `annotations/` (`/api/annotations/annotations/events` SSE) | Medium |
|
||||
|
||||
## Flow Dependencies
|
||||
|
||||
| Flow | Depends On | Shares Data With |
|
||||
|------|-----------|------------------|
|
||||
| F1 | — (entry) | F2 (auth state cycles forever afterwards) |
|
||||
| F2 | F1 (initial bearer must exist) | every authenticated flow |
|
||||
| F3 | F1 | F4–F11 (selected flight scopes most lists) |
|
||||
| F4 | F3 | F5 (annotations are scoped per media → per flight) |
|
||||
| F5 | F3, media exists | F6, F7 (manual edits coexist with AI runs) |
|
||||
| F6 | F3, image media exists | F5 |
|
||||
| F7 | F3, video media exists | F5 |
|
||||
| F8 | F3, F5/F6/F7 produced data | F9 |
|
||||
| F9 | F8 | F10 (validation status feeds class metrics) |
|
||||
| F10 | F1 (admin role) | F5 (class definitions are inputs to drawing) |
|
||||
| F11 | F1 | F5 (panel widths are read by `useResizablePanel`, but persistence is missing today — finding #11) |
|
||||
| F12 | F4 (a flight context for the test) | F7 (output detections may be cross-checked) |
|
||||
| F13 | F3 (selected flight) | F4 (live-GPS overlays the planned route) |
|
||||
| F14 | F5 (an annotation must exist for an event to fire) | F8 (dataset reflects status changes pushed via this stream) |
|
||||
|
||||
---
|
||||
|
||||
## Flow F1: Login
|
||||
|
||||
### Description
|
||||
|
||||
Operator submits credentials at `/login`. On success, the Admin service issues a JWT bearer (response body) and a `Secure; HttpOnly; SameSite=Strict` refresh-token cookie. `AuthContext` stores the bearer in memory; `ProtectedRoute` lets the user enter the app.
|
||||
|
||||
### Preconditions
|
||||
|
||||
- The Admin service is reachable through the nginx `/api/admin/*` proxy (or Vite dev proxy).
|
||||
- The user has not yet authenticated (or their bearer + refresh cookie are both expired).
|
||||
|
||||
### Sequence Diagram
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor User
|
||||
participant LoginPage as 04_login/LoginPage
|
||||
participant AuthCtx as 02_auth/AuthContext
|
||||
participant ApiClient as 01_api-transport/client
|
||||
participant AdminApi as admin/ service
|
||||
|
||||
User->>LoginPage: Enter email + password, click Submit
|
||||
LoginPage->>AuthCtx: login(email, password)
|
||||
AuthCtx->>ApiClient: api.post('/api/admin/auth/login', {email, password})
|
||||
ApiClient->>AdminApi: POST /admin/auth/login (credentials:'include')
|
||||
AdminApi-->>ApiClient: 200 {bearer, user} + Set-Cookie: refresh=...
|
||||
ApiClient-->>AuthCtx: {bearer, user}
|
||||
AuthCtx-->>LoginPage: ok
|
||||
LoginPage-->>User: Redirect to '/' (= '/flights' default)
|
||||
```
|
||||
|
||||
### Flowchart
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([User submits login form]) --> ValidateForm{Both fields filled?}
|
||||
ValidateForm -->|No| ShowFormError[Show inline error]
|
||||
ValidateForm -->|Yes| Theatrical[runUnlockSequence: 4×600 ms theatrical animation — finding B4]
|
||||
Theatrical --> CallApi[POST /api/admin/auth/login]
|
||||
CallApi --> Resp{200 OK?}
|
||||
Resp -->|Yes| StoreBearer[AuthContext stores bearer in memory]
|
||||
StoreBearer --> Redirect([Navigate to '/'])
|
||||
Resp -->|401| ShowAuthError[Show 'Invalid credentials']
|
||||
Resp -->|5xx / network| ShowGenericError[Show 'Try again']
|
||||
ShowAuthError --> Start
|
||||
ShowGenericError --> Start
|
||||
ShowFormError --> Start
|
||||
```
|
||||
|
||||
### Data Flow
|
||||
|
||||
| Step | From | To | Data | Format |
|
||||
|------|------|----|------|--------|
|
||||
| 1 | User | LoginPage | email + password | form input |
|
||||
| 2 | LoginPage | AuthContext | `{ email, password }` | function args |
|
||||
| 3 | AuthContext | admin/ via api/client | `POST /api/admin/auth/login` | JSON body |
|
||||
| 4 | admin/ | AuthContext | `{ bearer, user: AuthUser }` + Set-Cookie | JSON + cookie |
|
||||
| 5 | AuthContext | LoginPage | success | promise resolution |
|
||||
| 6 | LoginPage | router | `navigate('/')` | client-side redirect |
|
||||
|
||||
### Error Scenarios
|
||||
|
||||
| Error | Where | Detection | Recovery |
|
||||
|-------|-------|-----------|----------|
|
||||
| Invalid credentials | step 4 | 401 from admin/ | Show inline message; let user retry |
|
||||
| Network failure | step 3 | fetch reject | Show generic error; let user retry |
|
||||
| Theatrical animation hides server error | step 2 (theatrical waits 2.4 s) | none | UX cost — finding (B4) suggests removing the animation entirely |
|
||||
| Refresh cookie blocked by browser | step 4 | next F2 immediately fails | User must log in again — accepted today |
|
||||
|
||||
### Performance Expectations
|
||||
|
||||
| Metric | Target | Notes |
|
||||
|--------|--------|-------|
|
||||
| End-to-end latency | < 1 s server-side + 2.4 s artificial delay | Artificial delay is the dominant cost — Step 4 fix |
|
||||
|
||||
---
|
||||
|
||||
## Flow F2: Bearer auto-refresh on 401 (TWO refresh paths exist in code)
|
||||
|
||||
### Description
|
||||
|
||||
There are **two distinct refresh code paths** in the source — the verification pass (Step 4) caught both:
|
||||
|
||||
1. **Bootstrap path** — `AuthContext.tsx:24` calls `api.get('/api/admin/auth/refresh')` on app mount. This **does NOT have `credentials:'include'`** because `api/client.ts` doesn't add it on GET. Result: the cookie is not sent, the bootstrap silently fails, the user starts unauthenticated even when they have a valid refresh cookie.
|
||||
2. **401-retry path** — `api/client.ts:44` calls `fetch('/api/admin/auth/refresh', { method: 'POST', credentials: 'include' })` automatically when any authenticated fetch returns 401. This path IS correct.
|
||||
|
||||
The bootstrap path is the bug surfaced as finding B3 PRIORITY. The 401-retry path is the silent fallback that does work but only after the user has already hit a 401.
|
||||
|
||||
### Preconditions
|
||||
|
||||
- A valid refresh-cookie exists on the browser.
|
||||
- The 401 came from a request that should be retryable (idempotent or annotated as retry-safe).
|
||||
|
||||
### Sequence Diagram (401-retry path inside `api/client.ts` — works correctly)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Page
|
||||
participant ApiClient as 01_api-transport/client
|
||||
participant AdminApi as admin/ service
|
||||
|
||||
Page->>ApiClient: api.get('/api/...')
|
||||
ApiClient->>AdminApi: GET /... (with bearer)
|
||||
AdminApi-->>ApiClient: 401 (bearer expired)
|
||||
ApiClient->>AdminApi: POST /admin/auth/refresh (credentials:'include')
|
||||
AdminApi-->>ApiClient: 200 {bearer} + Set-Cookie: refresh=...
|
||||
ApiClient->>AdminApi: GET /... (retry with new bearer)
|
||||
AdminApi-->>ApiClient: 200 OK
|
||||
ApiClient-->>Page: response
|
||||
```
|
||||
|
||||
### Sequence Diagram (Bootstrap path on app mount — broken)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant App
|
||||
participant AuthCtx as 02_auth/AuthContext
|
||||
participant AdminApi as admin/ service
|
||||
|
||||
App->>AuthCtx: <AuthProvider> mounts
|
||||
AuthCtx->>AdminApi: GET /admin/auth/refresh (NO credentials:'include' — finding B3)
|
||||
AdminApi-->>AuthCtx: 401 (no cookie sent)
|
||||
AuthCtx->>AuthCtx: setLoading(false), user stays null
|
||||
AuthCtx-->>App: ProtectedRoute sees null user → redirects to /login
|
||||
```
|
||||
|
||||
### Error Scenarios
|
||||
|
||||
| Error | Where | Detection | Recovery |
|
||||
|-------|-------|-----------|----------|
|
||||
| Bootstrap GET refresh missing `credentials:'include'` | `AuthContext.tsx:24` | server returns 401 because cookie was not sent | **Bug today** — finding B3 PRIORITY. Symptom: a user with a valid refresh cookie still gets bounced to `/login` on every fresh tab. Step 4 fix: change to POST with `credentials:'include'` (matching the 401-retry path), or just delete the bootstrap GET and let the first authenticated fetch's 401 trigger the retry path. |
|
||||
| 401-retry path | `api/client.ts:44` | works | (no fix needed) |
|
||||
| Refresh cookie expired or revoked | refresh call | 401 | UI redirects to `/login`. |
|
||||
| SSE subscription holds a stale bearer | active EventSource | server closes the SSE stream | No reconnect logic today (Step 8 hardening). |
|
||||
|
||||
---
|
||||
|
||||
## Flow F3: Select active flight (CORRECTED Step 4)
|
||||
|
||||
### Description
|
||||
|
||||
Most pages are scoped to a "currently selected flight". `FlightContext` loads the flight list AND the user's stored selection on mount, then lets the user switch via the Header dropdown. The selection is **persisted as part of `UserSettings`** via the `annotations/` service — there is **no `/api/flights/select` endpoint**; this was a Step 3 documentation error caught at Step 4 verification.
|
||||
|
||||
### Sequence Diagram
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor User
|
||||
participant Header as 03_shared-ui/Header
|
||||
participant FlightCtx as 03_shared-ui/FlightContext
|
||||
participant ApiClient
|
||||
participant FlightsApi as flights/ service
|
||||
participant AnnotationsApi as annotations/ service
|
||||
|
||||
Note over FlightCtx: On mount
|
||||
FlightCtx->>FlightsApi: GET /api/flights?pageSize=1000
|
||||
FlightsApi-->>FlightCtx: { items: Flight[] }
|
||||
Note over FlightCtx: Flights with index > 1000 are silently dropped (finding B3)
|
||||
FlightCtx->>AnnotationsApi: GET /api/annotations/settings/user
|
||||
AnnotationsApi-->>FlightCtx: UserSettings { selectedFlightId }
|
||||
alt selectedFlightId is set
|
||||
FlightCtx->>FlightsApi: GET /api/flights/{selectedFlightId}
|
||||
FlightsApi-->>FlightCtx: Flight
|
||||
end
|
||||
|
||||
User->>Header: Click flight in dropdown
|
||||
Header->>FlightCtx: selectFlight(flight)
|
||||
FlightCtx->>FlightCtx: setSelectedFlight(flight) immediately (optimistic)
|
||||
FlightCtx->>AnnotationsApi: PUT /api/annotations/settings/user { selectedFlightId }
|
||||
Note over FlightCtx,AnnotationsApi: Fire-and-forget — error swallowed (finding B3)
|
||||
```
|
||||
|
||||
### Error Scenarios
|
||||
|
||||
| Error | Where | Detection | Recovery |
|
||||
|-------|-------|-----------|----------|
|
||||
| Flights list > 1000 | initial load | not detected | **Silent ceiling** — finding B3. Step 4 fix: paginate or stream. |
|
||||
| `selectFlight` PUT fails | step | none — fire-and-forget | UI keeps the local selection but the server does not — next reload reverts it. Step 4 fix. |
|
||||
|
||||
---
|
||||
|
||||
## Flow F4: Create / save flight + waypoints
|
||||
|
||||
### Description
|
||||
|
||||
User edits a flight in `FlightsPage`: drags waypoints on the map, edits altitudes, types parameters. On Save, the UI sends all changes to the `flights/` service.
|
||||
|
||||
### Sequence Diagram (current implementation — lossy)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor User
|
||||
participant FlightsPage as 05_flights/FlightsPage
|
||||
participant ApiClient
|
||||
participant FlightsApi as flights/ service
|
||||
|
||||
User->>FlightsPage: Drag waypoints, edit fields, click Save
|
||||
FlightsPage->>ApiClient: api.put('/api/flights/{id}', {name, aircraftId, ...})
|
||||
ApiClient->>FlightsApi: PUT /flights/{id}
|
||||
FlightsApi-->>FlightsPage: 200
|
||||
Note over FlightsPage,FlightsApi: Then a delete-then-recreate cycle for waypoints (finding #19)
|
||||
FlightsPage->>FlightsApi: DELETE /flights/{id}/waypoints (loop or bulk)
|
||||
loop for each new waypoint
|
||||
FlightsPage->>FlightsApi: POST /flights/{id}/waypoints {name, lat, lng, order}
|
||||
end
|
||||
Note over FlightsPage,FlightsApi: But the suite spec wants {Geopoint:{Lat,Lon,MGRS}, Source, Objective, OrderNum, Height} — finding #20 (server may return 400)
|
||||
FlightsApi-->>FlightsPage: per-waypoint result
|
||||
FlightsPage-->>User: Saved (or partial-failure UI not built today)
|
||||
```
|
||||
|
||||
### Error Scenarios
|
||||
|
||||
| Error | Where | Detection | Recovery |
|
||||
|-------|-------|-----------|----------|
|
||||
| Waypoint shape mismatch (UI vs spec, finding #20) | waypoint POST | server 400 | UI does not surface server errors well today — Step 4 priority |
|
||||
| Partial failure (some waypoints created, some failed) | step (per-waypoint loop) | server returns mixed status | UI does not detect — Step 4 priority |
|
||||
| Network drop mid-save | any | timeout | UI does not retry — Step 4 priority |
|
||||
|
||||
### Performance Expectations
|
||||
|
||||
| Metric | Target | Notes |
|
||||
|--------|--------|-------|
|
||||
| Save latency | < 1 s for ≤ 50 waypoints | Currently degrades with the N+M round-trip pattern (1 PUT + 1 DELETE + N POSTs). Bulk endpoint is a Step 5 solution candidate. |
|
||||
|
||||
---
|
||||
|
||||
## Flow F5: Annotate media (manual bbox)
|
||||
|
||||
### Description
|
||||
|
||||
User drags on the canvas to draw a bounding box, picks a class via 1–9 keyboard or DetectionClasses strip, and saves. The annotation persists to the `annotations/` service.
|
||||
|
||||
### Sequence Diagram
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor User
|
||||
participant CanvasEditor as 06_annotations/CanvasEditor
|
||||
participant Sidebar as 06_annotations/AnnotationsSidebar
|
||||
participant Page as 06_annotations/AnnotationsPage
|
||||
participant ApiClient
|
||||
participant AnnotationsApi as annotations/ service
|
||||
|
||||
User->>CanvasEditor: Mouse drag (draw bbox)
|
||||
User->>CanvasEditor: Press [1]–[9] (pick class)
|
||||
CanvasEditor-->>Sidebar: New detection added (in-memory)
|
||||
User->>Page: Click Save
|
||||
Page->>ApiClient: api.post('/api/annotations/annotations', body)
|
||||
Note over Page,ApiClient: Endpoint is doubly-prefixed (suite-service + resource path)
|
||||
Note over Page,ApiClient: handleSave body today: {classNum, x, y, w, h, time} — finding #32
|
||||
Note over Page,ApiClient: Spec wants: {classNum, x, y, w, h, videoTime, Source, WaypointId} — Step 4
|
||||
ApiClient->>AnnotationsApi: POST /annotations/annotations
|
||||
AnnotationsApi-->>Page: 200 {id}
|
||||
Page-->>User: Saved
|
||||
```
|
||||
|
||||
### Error Scenarios
|
||||
|
||||
| Error | Where | Detection | Recovery |
|
||||
|-------|-------|-----------|----------|
|
||||
| Save body shape wrong (finding #32) | save call | server 400 | Today the UI logs `console.error` and the user sees nothing — Step 4 priority |
|
||||
| Time-window math (50/150 ms vs implementation 200/200, finding #6) | overlay render | wrong annotations show during playback | Step 4 fix |
|
||||
| Gradient cap (16 % vs 25 % spec, finding #9) | sidebar render | visual drift only | Step 4 fix |
|
||||
| Cross-origin video tainted canvas (finding #12) | export image | browser CSP error | Step 4 fix or Step 5 design (server-side render) |
|
||||
|
||||
---
|
||||
|
||||
## Flow F6: AI Detect — image (sync)
|
||||
|
||||
### Description
|
||||
|
||||
User clicks AI Detect with an image selected. The detect service runs YOLO inference synchronously and returns detections inline.
|
||||
|
||||
### Sequence Diagram
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor User
|
||||
participant Sidebar as 06_annotations/AnnotationsSidebar
|
||||
participant ApiClient
|
||||
participant DetectApi as detect/ service
|
||||
participant AnnotationsApi as annotations/ service
|
||||
|
||||
User->>Sidebar: Click AI Detect (image selected)
|
||||
Sidebar->>ApiClient: api.post('/api/detect/{mediaId}')
|
||||
ApiClient->>DetectApi: POST /detect/{mediaId}
|
||||
DetectApi-->>ApiClient: 200 {detections[]}
|
||||
ApiClient-->>Sidebar: detections
|
||||
Note over Sidebar,AnnotationsApi: Detections may auto-persist (server-side) or require client save — verify in Step 4
|
||||
Sidebar-->>User: Render detections on canvas
|
||||
```
|
||||
|
||||
### Error Scenarios
|
||||
|
||||
| Error | Where | Detection | Recovery |
|
||||
|-------|-------|-----------|----------|
|
||||
| Inference timeout | step | fetch timeout | None today — finding #21 (errors silently `console.error`'d) |
|
||||
| Class not in admin list | render | `getClassNameFallback` falls back to `#<n>` | Acceptable; covered by `11_class-colors` |
|
||||
|
||||
---
|
||||
|
||||
## Flow F7: AI Detect — video (async, with SSE) — NOT WIRED TODAY
|
||||
|
||||
### Description (target — what should exist)
|
||||
|
||||
User clicks AI Detect with a video. The detect service kicks off an async job and returns a job ID. The UI subscribes to `GET /api/detect/stream/{jobId}` (SSE) for progress + final results.
|
||||
|
||||
### What's actually in code (Step 4 verification)
|
||||
|
||||
The async-video flow is **completely absent** from the codebase. `AnnotationsSidebar.tsx:39` only does `POST /api/detect/${media.id}` — the same endpoint, regardless of whether the media is an image or a video. There are NO calls to `/api/detect/video/...` and NO EventSource subscriptions to `/api/detect/stream/...`. The only annotation-related SSE in the codebase is `createSSE('/api/annotations/annotations/events', ...)` in the same file (line 25), which streams annotation-**status** events, not detect progress.
|
||||
|
||||
The previously cited finding #21 ("AI-detect doesn't stream progress") is therefore stronger than originally documented: the async path does not exist at all. The fix in Step 4 must build:
|
||||
- `POST /api/detect/video/${mediaId}` request (with `X-Refresh-Token` header, finding #30)
|
||||
- `createSSE('/api/detect/stream/${jobId}', ...)` subscription
|
||||
- progress UI in AnnotationsSidebar.
|
||||
|
||||
### Sequence Diagram (target — what should happen)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor User
|
||||
participant Sidebar as 06_annotations/AnnotationsSidebar
|
||||
participant Page as 06_annotations/AnnotationsPage
|
||||
participant ApiClient
|
||||
participant SseClient as 01_api-transport/sse
|
||||
participant DetectApi as detect/ service
|
||||
|
||||
User->>Sidebar: Click AI Detect (video selected)
|
||||
Sidebar->>ApiClient: api.post('/api/detect/video/{mediaId}', {}, headers={X-Refresh-Token})
|
||||
ApiClient->>DetectApi: POST /detect/video/{mediaId}
|
||||
DetectApi-->>ApiClient: 202 {jobId}
|
||||
Page->>SseClient: subscribeSSE(`/api/detect/stream/${jobId}?token=...`)
|
||||
SseClient-->>DetectApi: GET /detect/stream/{jobId}?token=... (EventSource)
|
||||
loop progress events
|
||||
DetectApi-->>SseClient: data: {progress: 0..100}
|
||||
SseClient-->>Page: onMessage(progress)
|
||||
Page-->>User: Update progress bar
|
||||
end
|
||||
DetectApi-->>SseClient: data: {detections[], status: 'done'}
|
||||
SseClient-->>Page: onMessage(final)
|
||||
Page-->>User: Render detections; close stream
|
||||
```
|
||||
|
||||
### Error Scenarios
|
||||
|
||||
| Error | Where | Detection | Recovery |
|
||||
|-------|-------|-----------|----------|
|
||||
| No SSE subscription today (finding #10) | step | user sees "AI Detect" go silent forever | Build the subscription — Step 4 PRIORITY |
|
||||
| Bearer expires mid-job (no `X-Refresh-Token`, finding #30) | server side | job aborts | Send `X-Refresh-Token` so server can rotate transparently — Step 4 |
|
||||
| EventSource holds stale token (finding cross-link) | refresh-rotation occurs while subscribed | server closes stream | Reconnect with new token — Step 8 hardening |
|
||||
| Network blip | mid-stream | `onerror` | Reconnect with backoff — Step 8 |
|
||||
|
||||
---
|
||||
|
||||
## Flow F8: Dataset browse + filter
|
||||
|
||||
### Description
|
||||
|
||||
User opens `/dataset`, filters by class / status / search; thumbnails appear in a grid.
|
||||
|
||||
### Sequence Diagram
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor User
|
||||
participant DatasetPage as 07_dataset/DatasetPage
|
||||
participant ApiClient
|
||||
participant AnnotationsApi as annotations/ service
|
||||
|
||||
User->>DatasetPage: Type in filter
|
||||
Note over DatasetPage: 300 ms debounce via useDebounce
|
||||
DatasetPage->>ApiClient: api.get('/api/annotations/dataset?status=...&classNum=...&q=...')
|
||||
ApiClient->>AnnotationsApi: GET ...
|
||||
AnnotationsApi-->>DatasetPage: PaginatedResponse<DatasetItem>
|
||||
DatasetPage-->>User: Render thumbnails (NOT virtualised — finding #3)
|
||||
```
|
||||
|
||||
### Error Scenarios
|
||||
|
||||
| Error | Where | Detection | Recovery |
|
||||
|-------|-------|-----------|----------|
|
||||
| Status filter sentinels collide (finding #8) | client query build | wrong items returned | Step 4 fix after enum-drift resolution |
|
||||
| `classNum=0` collides with real class 0 (finding #9) | client query build | class 0 selectable but matches "All" | Step 4 fix |
|
||||
| Long lists render all thumbnails (finding #3) | render | UI lag | Add virtualisation — Step 4 / Step 8 |
|
||||
|
||||
---
|
||||
|
||||
## Flow F9: Dataset bulk-validate (Step 4 CORRECTED — partially wired)
|
||||
|
||||
### Description
|
||||
|
||||
User multi-selects thumbnails (Ctrl+click) and clicks the **Validate** button — `DatasetPage.tsx:142-146` only renders this button when `selectedIds.size > 0`, so it's discoverable. On click, the page POSTs `/api/annotations/dataset/bulk-status` with `{annotationIds, status: AnnotationStatus.Validated}`. The selection is then cleared and the items re-fetched.
|
||||
|
||||
**The earlier doc draft claimed this was missing**. It's not; only the **`[V]` keyboard shortcut** is missing (finding #1 — keyboard shortcuts as a category).
|
||||
|
||||
### Sequence Diagram (actual)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor User
|
||||
participant DatasetPage as 07_dataset/DatasetPage
|
||||
participant ApiClient
|
||||
participant AnnotationsApi as annotations/ service
|
||||
|
||||
User->>DatasetPage: Ctrl+click thumbnails (build selectedIds)
|
||||
User->>DatasetPage: Click Validate button (visible when selectedIds.size > 0)
|
||||
DatasetPage->>ApiClient: api.post('/api/annotations/dataset/bulk-status', {annotationIds, status: AnnotationStatus.Validated})
|
||||
ApiClient->>AnnotationsApi: POST /dataset/bulk-status
|
||||
AnnotationsApi-->>DatasetPage: 200
|
||||
DatasetPage->>DatasetPage: setSelectedIds(new Set()); fetchItems()
|
||||
DatasetPage-->>User: Refresh visible thumbnails (status badge updated)
|
||||
```
|
||||
|
||||
### Error Scenarios
|
||||
|
||||
| Error | Where | Detection | Recovery |
|
||||
|-------|-------|-----------|----------|
|
||||
| `[V]` keyboard shortcut missing | finding #1 (Dataset) | only mouse click works | Step 4 — add `useEffect` keydown listener on the page when `tab === 'annotations'` |
|
||||
| `bulk-status` request body uses string instead of numeric (finding #11) | server payload | server may reject | Step 4 — verify the suite spec then fix the client side to match |
|
||||
| Bulk action fails partway | server | `handleValidate` has no try/catch | Step 4 — surface a toast, keep selection so the user can retry |
|
||||
|
||||
---
|
||||
|
||||
## Flow F10: Admin — detection class CRUD
|
||||
|
||||
### Description
|
||||
|
||||
Admin user opens `/admin`, edits detection classes (color, name, photoMode, maxSizeM). Deletes are destructive but currently lack a confirm dialog (finding B4). Read uses `annotations/classes`; write uses `admin/classes` (finding B4 — verify with suite ADRs).
|
||||
|
||||
### Sequence Diagram (Step 4 corrected — no PUT/edit endpoint exists)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor Admin
|
||||
participant AdminPage as 08_admin/AdminPage
|
||||
participant ApiClient
|
||||
participant AnnotationsApi as annotations/ service
|
||||
participant AdminApi as admin/ service
|
||||
|
||||
AdminPage->>ApiClient: api.get('/api/annotations/classes')
|
||||
ApiClient->>AnnotationsApi: GET /classes
|
||||
AnnotationsApi-->>AdminPage: DetectionClass[]
|
||||
Admin->>AdminPage: Click "Add Class"
|
||||
AdminPage->>ApiClient: api.post('/api/admin/classes', newClass)
|
||||
ApiClient->>AdminApi: POST /classes
|
||||
AdminApi-->>AdminPage: 200
|
||||
AdminPage->>ApiClient: api.get('/api/annotations/classes') (re-read)
|
||||
Admin->>AdminPage: Click Delete
|
||||
Note over AdminPage: NO ConfirmDialog today (finding B4) — destructive action goes through immediately
|
||||
AdminPage->>ApiClient: api.delete('/api/admin/classes/{id}')
|
||||
ApiClient->>AdminApi: DELETE /classes/{id}
|
||||
AdminApi-->>AdminPage: 200
|
||||
```
|
||||
|
||||
> **Step 4 verification finding**: there is no edit-class endpoint in the codebase today. Admins can only **add** new classes and **delete** existing ones — they cannot modify an existing class's color / name / maxSizeM / photoMode. This is a real gap, not just a documentation drift; the WPF era supported in-place edits via the same DataGrid. Surface for Step 4 (decide: add a `PATCH /api/admin/classes/{id}` and a UI form, or accept add-and-delete as the only mutation path).
|
||||
|
||||
### Error Scenarios
|
||||
|
||||
| Error | Where | Detection | Recovery |
|
||||
|-------|-------|-----------|----------|
|
||||
| `/admin` route lacks RBAC gate | route entry | non-admin can browse | **Security PRIORITY** (App+main finding #1) — Step 4 |
|
||||
| AI Settings + GPS Settings forms don't save (finding B4 PRIORITY) | save click | nothing happens | Step 4 PRIORITY |
|
||||
| Hardcoded GPS device defaults (`192.168.1.100:5535`) shipped to prod (finding B4) | bundle | leaks internal network shape | Step 4 |
|
||||
|
||||
---
|
||||
|
||||
## Flow F11: Settings — persist user prefs (Step 4 CORRECTED)
|
||||
|
||||
### Description
|
||||
|
||||
User edits System / Directory / Camera / User settings, clicks Save. **PUTs go to `annotations/` (`/api/annotations/settings/{system,directories,user}`) — NOT `admin/` as initially drafted.** The aircraft default-toggle hits `flights/` (`PATCH /api/flights/aircrafts/${id}`). The "settings" name is a misnomer — what the UI calls "settings" is split across two services.
|
||||
|
||||
Panel widths (annotations / dataset, left / right) are typed fields in `UserSettings` (`00_foundation/types/index.ts`) but **`useResizablePanel` does not write them back today** — finding #11. The wire endpoint exists; the client wiring is the gap.
|
||||
|
||||
### Error Scenarios
|
||||
|
||||
| Error | Where | Detection | Recovery |
|
||||
|-------|-------|-----------|----------|
|
||||
| `saveSystem` / `saveDirs` lack try/finally (finding B4) | PUT failure | `saving:true` stays forever | Step 4 fix |
|
||||
| Numeric inputs `parseInt(v) ‖ 0` (finding B4) | input clear | silent zero write | Step 4 fix |
|
||||
| No optimistic concurrency (finding B4) | concurrent admin edits | last-write-wins, no conflict UI | Step 6 problem-extraction surface |
|
||||
|
||||
---
|
||||
|
||||
## Flow F12: GPS-Denied Test Mode (planned, not implemented)
|
||||
|
||||
### Description (target — per `_docs/how_to_test.md`)
|
||||
|
||||
The operator wants to validate the GPS-Denied onboard system without a real flight. They upload a `.tlog` file + a synced video (or one that the system will auto-sync via IMU analysis). The system feeds the simulated frames + IMU/GPS into the SITL pipeline and the onboard service consumes them as if they were live.
|
||||
|
||||
### Sequence Diagram (target)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor Operator
|
||||
participant TestMode as 05_flights/GPS-Denied/Test Mode (planned)
|
||||
participant ApiClient
|
||||
participant GpsDeskApi as gps-denied-desktop/ service
|
||||
participant GpsBoardApi as gps-denied-onboard/ service
|
||||
|
||||
Operator->>TestMode: Upload tlog + video (drag-drop)
|
||||
TestMode->>ApiClient: api.post('/api/gps-denied-desktop/test/sync', files)
|
||||
ApiClient->>GpsDeskApi: POST /test/sync (multipart)
|
||||
GpsDeskApi-->>TestMode: {sessionId, syncOffset, imuChart}
|
||||
Note over GpsDeskApi: Server-side: extract timestamps + IMU + GPS from tlog,<br/>auto-sync video by detecting takeoff in IMU + video duration
|
||||
|
||||
Operator->>TestMode: Confirm sync, click Start SITL
|
||||
TestMode->>ApiClient: api.post('/api/gps-denied-desktop/test/run', {sessionId})
|
||||
ApiClient->>GpsDeskApi: POST /test/run
|
||||
GpsDeskApi->>GpsBoardApi: stream IMU + frames (in-cluster)
|
||||
GpsBoardApi-->>GpsDeskApi: positioning estimates
|
||||
GpsDeskApi-->>TestMode: SSE stream of positioning estimates
|
||||
TestMode-->>Operator: Render trajectory overlay + comparison chart
|
||||
```
|
||||
|
||||
### Preconditions
|
||||
|
||||
- A flight context exists (Test Mode is scoped within a flight).
|
||||
- The `.tlog` and video are valid; the IMU chart in the tlog is "drone-on-ground → take-off → land" so auto-sync can find the take-off event.
|
||||
|
||||
### Open architectural questions for Test Mode
|
||||
|
||||
1. Where does the IMU-based sync analysis live — in `gps-denied-desktop/`, in a new Cython worker, or client-side?
|
||||
2. Is SITL state persisted across page reloads (= server-side session), or is it in-memory client-side only?
|
||||
3. Output rendering — overlay on the GPS-Denied tab's existing map, or a dedicated comparison chart view?
|
||||
|
||||
These belong in Step 4.5 (Architecture Vision); Test Mode is in this flow inventory only as a **planned** flow so downstream consumers don't lose it.
|
||||
|
||||
---
|
||||
|
||||
## Flow F13: Live-GPS aircraft telemetry (SSE) — added at Step 4
|
||||
|
||||
### Description
|
||||
|
||||
When the user has a flight selected and FlightsPage is open, the page subscribes to a per-flight live-GPS event stream so the map can render the aircraft's current position in real time. Discovered at Step 4 verification (`FlightsPage.tsx:67`).
|
||||
|
||||
### Sequence Diagram
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor User
|
||||
participant FlightsPage as 05_flights/FlightsPage
|
||||
participant SseClient as 01_api-transport/sse
|
||||
participant FlightsApi as flights/ service
|
||||
|
||||
User->>FlightsPage: Select a flight (Header dropdown)
|
||||
FlightsPage->>SseClient: createSSE(`/api/flights/${flightId}/live-gps`, onEvent)
|
||||
SseClient-->>FlightsApi: GET /api/flights/{flightId}/live-gps?token=... (EventSource)
|
||||
loop while flight is selected
|
||||
FlightsApi-->>SseClient: data: { lat, lon, satellites, status }
|
||||
SseClient-->>FlightsPage: onEvent(payload)
|
||||
FlightsPage-->>User: Update aircraft marker on map
|
||||
end
|
||||
User->>FlightsPage: Switch flight or navigate away
|
||||
FlightsPage->>SseClient: source.close()
|
||||
```
|
||||
|
||||
### Error Scenarios
|
||||
|
||||
| Error | Where | Detection | Recovery |
|
||||
|-------|-------|-----------|----------|
|
||||
| Bearer expires mid-stream | server | server closes the stream | EventSource auto-reconnects with **stale token** — same Step 8 hardening as F7 |
|
||||
| Aircraft offline | data shape | `status: 'offline'` payload | UI should grey out the marker — verify in Step 4 |
|
||||
| User switches flights rapidly | client | new `createSSE` before old `.close()` | Memory leak risk — verify cleanup in Step 4 |
|
||||
|
||||
---
|
||||
|
||||
## Flow F14: Annotation-status events (SSE) — added at Step 4
|
||||
|
||||
### Description
|
||||
|
||||
When the user opens AnnotationsPage with media selected, `AnnotationsSidebar.tsx:25` subscribes to `/api/annotations/annotations/events` to receive **annotation-status events** (created / edited / validated). This is the SSE that exists today; it is **NOT** the detect-progress SSE (F7), which doesn't exist yet.
|
||||
|
||||
### Sequence Diagram
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor User
|
||||
participant Sidebar as 06_annotations/AnnotationsSidebar
|
||||
participant SseClient as 01_api-transport/sse
|
||||
participant AnnotationsApi as annotations/ service
|
||||
|
||||
User->>Sidebar: Open AnnotationsPage (media selected)
|
||||
Sidebar->>SseClient: createSSE('/api/annotations/annotations/events', onEvent)
|
||||
SseClient-->>AnnotationsApi: GET /api/annotations/annotations/events?token=... (EventSource)
|
||||
loop while page mounted
|
||||
AnnotationsApi-->>SseClient: data: { annotationId, mediaId, status }
|
||||
SseClient-->>Sidebar: onEvent(payload)
|
||||
Sidebar->>Sidebar: refetch annotations for current media
|
||||
end
|
||||
User->>Sidebar: Navigate away
|
||||
Sidebar->>SseClient: source.close()
|
||||
```
|
||||
|
||||
### Notes
|
||||
|
||||
- The stream is **not scoped per media** — every connected user receives all annotation-status events. Filtering happens client-side (`event.mediaId === selectedMedia.id`). Acceptable for low-volume admin use; flag as a Step 6 problem-extraction surface for scale.
|
||||
- Bearer-rotation issue applies here too (Step 8 hardening).
|
||||
|
||||
---
|
||||
|
||||
## Mermaid Diagram Conventions
|
||||
|
||||
- **Participants**: matched to component IDs `NN_name` (e.g., `04_login`, `02_auth`, `01_api-transport`).
|
||||
- **External services**: named after their suite-service folder (`admin/`, `flights/`, `annotations/`, `detect/`, `gps-denied-desktop/`, `gps-denied-onboard/`).
|
||||
- **Decision nodes**: `{Question?}`.
|
||||
- **Start/End**: `([label])` stadium shape.
|
||||
- **No styling** — let the renderer theme handle it.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,212 @@
|
||||
# Test Environment
|
||||
|
||||
## Overview
|
||||
|
||||
**System under test**: the Azaion UI single-page application — a React 19 + Vite 6 static bundle served by `nginx:alpine` (port 80) that talks to the parent suite microservices through the same nginx instance (reverse-proxied `/api/<service>/` routes per `nginx.conf`). The SPA's observable surface is everything reachable from a browser: outgoing HTTP requests (URL, method, headers, body), incoming responses (rendered DOM, console, errors), outgoing EventSource streams, browser storage (`localStorage` / `sessionStorage` / `document.cookie`), and the built artifact (`dist/`).
|
||||
|
||||
**Consumer app purpose**: the test runners are the consumer. They drive a real browser (or jsdom) at the SPA's public surface, capture every outbound request/event, and assert against `_docs/00_problem/input_data/expected_results/results_report.md` (95 rows).
|
||||
|
||||
**Black-box discipline**: the consumer MUST NOT import from `src/` (except for the typed enum shapes that ARE part of the wire contract per `P9`), MUST NOT bypass the React tree to call internal hooks, and MUST NOT inspect React component state directly. Assertions are made on the rendered DOM, ARIA roles, outgoing network activity, EventSource state machine, console output, and built artifacts.
|
||||
|
||||
## Test Execution Profiles
|
||||
|
||||
Two profiles share the artifact directory but address different black-box levels. Runner selection is deferred to the Decompose Tests step (`autodev` Step 5) — this document specifies the **environment requirements**, not the runner choice.
|
||||
|
||||
| Profile | Scope | Black-box level | Backing services | Browser |
|
||||
|---------|-------|----------------|------------------|---------|
|
||||
| `fast` | Unit + component + static checks | DOM + network requests issued by a mounted component or by a code-level helper, captured at the `fetch` / `EventSource` boundary | Stubbed (request interception layer, e.g. MSW or equivalent). No real services. | jsdom or headless Chromium (component renderer). |
|
||||
| `e2e` | Browser smoke + cross-service flows | Real browser → real nginx (UI image) → real suite docker-compose stack | Full suite docker-compose stack (`admin/`, `flights/`, `annotations/`, `detect/`, `gps-denied-desktop/`, `gps-denied-onboard/`, `autopilot/`, `resource/`, `loader/`). | Headless Chromium + Firefox latest 2 versions per AC-18. |
|
||||
| `static` | Source / config / bundle checks | The repo + the `dist/` artifact | None (no runtime). | None (CLI). |
|
||||
|
||||
Tests in `blackbox-tests.md`, `performance-tests.md`, etc. tag themselves with `Profile: fast | e2e | static` to make runner routing unambiguous.
|
||||
|
||||
## Docker Environment
|
||||
|
||||
The Azaion UI image carries no DB. The "Docker environment" is the test-time choreography of UI + suite services + stubs.
|
||||
|
||||
### Services (e2e profile)
|
||||
|
||||
| Service | Image / Build | Purpose | Ports |
|
||||
|---------|--------------|---------|-------|
|
||||
| `azaion-ui` | Built from this repo (`Dockerfile`, ARM64 per H1 / S5) — final stage `nginx:alpine` | The SPA under test | `80` |
|
||||
| `admin` | Suite `admin/` image (auth + users + classes write + GPS settings) | Auth + RBAC; cookie issuer per E3 | per suite compose |
|
||||
| `flights` | Suite `flights/` image | Flight CRUD + waypoints + aircraft + live-GPS SSE | per suite compose |
|
||||
| `annotations` | Suite `annotations/` image | Media + annotations + dataset + class read + settings + status SSE | per suite compose |
|
||||
| `detect` | Suite `detect/` image | Sync image detect (and future async video detect F7) | per suite compose |
|
||||
| `gps-denied-desktop`, `gps-denied-onboard`, `autopilot`, `resource`, `loader` | Suite microservice images | Auxiliary services hit by the SPA (only `loader/` and `resource/` are hit on production paths today; `gps-denied-*` is target-only F12) | per suite compose |
|
||||
| `owm-stub` | Tiny HTTP server returning canned OpenWeatherMap responses | Replace direct OWM HTTPS (E10) so tests are deterministic and rate-limit-free | `8081` |
|
||||
| `tile-stub` | Tiny HTTP server returning a 256x256 PNG | Replace OSM tile servers | `8082` |
|
||||
| `test-db` | Suite-managed (Postgres per suite default) | Backs `admin/`, `flights/`, `annotations/` | Internal |
|
||||
|
||||
### Networks
|
||||
|
||||
| Network | Services | Purpose |
|
||||
|---------|----------|---------|
|
||||
| `azaion-test-net` | all of the above | Isolated test network; no internet egress (OWM + tile stubs replace the only external hops). |
|
||||
|
||||
### Volumes
|
||||
|
||||
| Volume | Mounted to | Purpose |
|
||||
|--------|-----------|---------|
|
||||
| `test-db-data` | `test-db:/var/lib/postgresql/data` | Suite DB persistence — wiped between e2e runs (see Data Isolation below). |
|
||||
| `seed-fixtures` | `admin:/seed`, `flights:/seed`, `annotations:/seed` (read-only) | Bootstrap data loaded at service start (users, flights, classes, sample media). See `test-data.md`. |
|
||||
| `test-output` | `playwright-runner:/output` | Where the consumer writes CSV reports, screenshots, traces. |
|
||||
|
||||
### docker-compose structure (outline)
|
||||
|
||||
```yaml
|
||||
services:
|
||||
azaion-ui:
|
||||
build: .
|
||||
ports: ["80:80"]
|
||||
depends_on: [admin, flights, annotations, detect]
|
||||
environment:
|
||||
AZAION_REVISION: ${CI_COMMIT_SHA:-test}
|
||||
|
||||
admin:
|
||||
image: azaion/admin:test
|
||||
depends_on: [test-db]
|
||||
|
||||
flights:
|
||||
image: azaion/flights:test
|
||||
depends_on: [test-db]
|
||||
|
||||
annotations:
|
||||
image: azaion/annotations:test
|
||||
depends_on: [test-db]
|
||||
|
||||
detect:
|
||||
image: azaion/detect:test
|
||||
|
||||
test-db:
|
||||
image: postgres:16-alpine
|
||||
|
||||
owm-stub:
|
||||
build: ./testing/stubs/owm
|
||||
tile-stub:
|
||||
build: ./testing/stubs/tile
|
||||
|
||||
playwright-runner:
|
||||
build: ./testing/runner
|
||||
depends_on: [azaion-ui]
|
||||
environment:
|
||||
BASE_URL: http://azaion-ui:80
|
||||
OWM_BASE_URL: http://owm-stub:8081
|
||||
TILE_BASE_URL: http://tile-stub:8082
|
||||
```
|
||||
|
||||
The compose file is part of the test-spec output; its concrete shape lands when the Decompose Tests step picks the runner (Step 5).
|
||||
|
||||
## Consumer Application
|
||||
|
||||
### `fast` profile
|
||||
|
||||
**Tech stack** (target — chosen at Step 5): a component-testing harness in TypeScript (Vitest or Jest + React Testing Library) plus a request-interception layer (MSW or equivalent) and jsdom (or headless Chromium component renderer).
|
||||
|
||||
**Entry point**: `npm run test:fast` (or `bun test`) — runs all `*.test.ts(x)` files under the test root.
|
||||
|
||||
#### Communication with system under test
|
||||
|
||||
| Interface | Protocol | Endpoint / Topic | Authentication |
|
||||
|-----------|----------|-----------------|----------------|
|
||||
| Mounted React component under test | direct mount via the testing library | n/a — observe the DOM + outbound requests captured by MSW | Stubbed bearer / cookie in test helpers |
|
||||
| Outgoing `fetch` (under test) | HTTP via MSW handlers | mock `/api/<service>/...` per test | per handler |
|
||||
| Outgoing `EventSource` (under test) | SSE via MSW or `EventSourcePolyfill` test double | mock `/api/<service>/...` per test | bearer in query string (ADR-008) |
|
||||
| Static check | `bun run` script + filesystem regex (e.g. via `ripgrep`) | n/a | n/a |
|
||||
|
||||
### `e2e` profile
|
||||
|
||||
**Tech stack** (target — chosen at Step 5): Playwright (Chromium + Firefox per AC-18) driving the deployed `azaion-ui` nginx; assertion library is the runner's built-in expectations + a small request-interception adapter that logs every outbound request for assertion.
|
||||
|
||||
**Entry point**: `bun run test:e2e` — runs all `*.e2e.ts` files under the test root against the live compose stack.
|
||||
|
||||
#### Communication with system under test
|
||||
|
||||
| Interface | Protocol | Endpoint / Topic | Authentication |
|
||||
|-----------|----------|-----------------|----------------|
|
||||
| Browser navigation | HTTPS | `${BASE_URL}/login`, `/flights`, `/annotations`, `/dataset`, `/admin`, `/settings` | login via the public `/login` flow |
|
||||
| Suite REST | HTTPS via SPA's nginx proxy | `/api/admin/*`, `/api/flights/*`, `/api/annotations/*`, `/api/detect/*`, `/api/loader/*`, `/api/resource/*`, `/api/gps-denied-{desktop,onboard}/*`, `/api/autopilot/*` | bearer in `Authorization` header + cookie (HttpOnly) |
|
||||
| Suite SSE | HTTPS | `/api/flights/<id>/live-gps`, `/api/annotations/annotations/events`, `/api/detect/stream/<jobId>` (F7 target) | bearer in `?token=` per ADR-008 |
|
||||
| Bundle / image inspection | filesystem / `docker inspect` | n/a | n/a |
|
||||
| OpenWeatherMap | HTTPS via `owm-stub` | per stub | none |
|
||||
| OSM tiles | HTTPS via `tile-stub` | per stub | none |
|
||||
|
||||
### What the consumer does NOT have access to
|
||||
|
||||
- No direct DB access to `test-db`. Suite DB queries are forbidden from the test runner; the consumer asserts only through the suite's REST + SSE.
|
||||
- No internal `src/` imports beyond the typed enum shapes that ARE part of the wire contract (`AnnotationStatus`, `MediaStatus`, `Affiliation`, `CombatReadiness`, `MediaType`, `AnnotationSource` per `data_parameters.md` §1) — these are the spec the test asserts against per `P9`.
|
||||
- No React component state read via hooks or test-only escape hatches; only the DOM + outbound network surface is observable.
|
||||
- No shared memory or filesystem with the SPA.
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
**When to run**:
|
||||
|
||||
- `fast` profile: on every commit (planned addition to `.woodpecker/build-arm.yml`; currently absent — O14).
|
||||
- `e2e` profile: on PR merge to `dev` / `stage` and pre-release on `main`. Long-running; not gating regular commits.
|
||||
- `static` profile: on every commit (lints + bundle / config checks run as part of the build).
|
||||
|
||||
**Pipeline stage**:
|
||||
|
||||
- `fast` + `static`: between `bun install` and `bun run build`.
|
||||
- `e2e`: after `bun run build`, against the just-built image, in a separate compose job.
|
||||
|
||||
**Gate behavior**:
|
||||
|
||||
- `fast` + `static`: block merge on failure.
|
||||
- `e2e`: block merge on failure for `dev` / `stage`. On `main`, manual approval is allowed for known-quarantined tests (e.g., the Phase B target tests for AC-11 / AC-24 / AC-40 that assert "when implemented").
|
||||
|
||||
**Timeout**: `fast` ≤ 5 min suite total. `e2e` ≤ 30 min suite total. Individual tests timeout per the `Max execution time` field in each scenario.
|
||||
|
||||
## Reporting
|
||||
|
||||
**Format**: CSV (and JUnit XML for CI consumption when the runner produces it).
|
||||
|
||||
**Columns**: `Test ID, Test Name, Profile, Execution Time (ms), Result (PASS|FAIL|SKIP|QUARANTINE), Error Message, Traces to AC, Traces to results_report.md row`.
|
||||
|
||||
**Output path**: `./test-output/report.csv` (mounted from the `playwright-runner` / `vitest-runner` container). For `static` checks, `./test-output/static-report.csv`. Suite-level rollup written to `./test-output/summary.csv`.
|
||||
|
||||
## Test Execution
|
||||
|
||||
**Decision**: **Docker (preferred)** for the `e2e` and `static` profiles; **local Bun** for the `fast` profile and as an option for `e2e` on developer machines that already have Playwright + the suite stack running. The project is **not hardware-dependent** — see "Hardware dependencies found" below.
|
||||
|
||||
### Hardware dependencies found
|
||||
|
||||
| Indicator | Found at | Verdict |
|
||||
|-----------|----------|---------|
|
||||
| GPU / CUDA imports | none in `src/` or `mission-planner/` | absent |
|
||||
| CoreML / MPS imports | none | absent |
|
||||
| Camera / sensor / GPIO / V4L2 | none | absent — the SPA reads `<video>` elements rendered from a server-supplied URL |
|
||||
| OS-specific drivers / kernel modules | none | absent |
|
||||
| Platform-gated source branches | none | absent |
|
||||
| Spec-level constraint | `_docs/00_problem/restrictions.md` H3 ("No GPU expectation in UI image") + H4 ("Chromium / Firefox latest 2") | confirms platform-neutral browser surface |
|
||||
|
||||
Conclusion: classify as **Not hardware-dependent**. Docker headless Chromium reproduces the real production runtime; no real-hardware execution path is required.
|
||||
|
||||
### Execution instructions
|
||||
|
||||
#### Docker mode (preferred; CI default)
|
||||
|
||||
1. **Prerequisites**: Docker Engine 24+ with the `azaion-test-net` network reachable, ARM64 or amd64 host (the UI image is ARM64-only per H1 — CI runners on ARM64; multi-arch builds optional for local dev).
|
||||
2. **Build**: `docker buildx build --platform linux/arm64 -t azaion-ui:test .` (or `--platform linux/amd64` on amd64 dev machines).
|
||||
3. **Compose up**: `docker compose -f e2e/docker-compose.suite-e2e.yml up -d` — brings up `azaion-ui`, `admin`, `flights`, `annotations`, `detect`, the auxiliary services, `owm-stub`, `tile-stub`, `test-db`, and the `playwright-runner`.
|
||||
4. **Run tests**: `docker compose -f e2e/docker-compose.suite-e2e.yml run --rm playwright-runner` — the runner image entrypoint is `bun run test:e2e`. Reports land in `./test-output/`.
|
||||
5. **Tear down**: `docker compose -f e2e/docker-compose.suite-e2e.yml down -v` (volumes wiped between runs).
|
||||
6. **Required environment**: `BASE_URL=http://azaion-ui:80`, `OWM_BASE_URL=http://owm-stub:8081`, `TILE_BASE_URL=http://tile-stub:8082`, `CI_COMMIT_SHA=<sha>` (stamped into `AZAION_REVISION`).
|
||||
|
||||
#### Local mode (for `fast` profile + developer-machine `e2e` runs)
|
||||
|
||||
1. **Prerequisites**: Bun 1.3.11 (matches S4), Chromium + Firefox latest two stable lines installed via Playwright (`bunx playwright install --with-deps chromium firefox`).
|
||||
2. **`fast` profile**: `bun install && bun run test:fast` (alias for `bun test`, runs Vitest under jsdom plus MSW handlers).
|
||||
3. **`e2e` profile (local)**: bring up the suite stack via the parent suite's compose file (`../docker-compose.yml`), point `BASE_URL=http://localhost:80`, then `bun run test:e2e`.
|
||||
4. **Required environment**: same as Docker mode plus `OWM_API_KEY=test-key` (passed through the OWM stub).
|
||||
|
||||
#### CI runner mapping
|
||||
|
||||
| Profile | Runner type | Mode | Gate |
|
||||
|---------|------------|------|------|
|
||||
| `static` | ARM64 build runner | local (no browser) | block merge on failure |
|
||||
| `fast` | ARM64 build runner | local Bun (jsdom + MSW) | block merge on failure |
|
||||
| `e2e` | ARM64 e2e runner with Docker | Docker compose stack | block merge on failure for `dev`/`stage`; manual approval allowed for quarantined tests on `main` (per CI/CD Integration above) |
|
||||
|
||||
The decision is consumed by Phase 4 to choose between `scripts/run-tests.sh` (local Bun for `fast` + `static`) and `e2e/docker-compose.suite-e2e.yml` (Docker for `e2e`).
|
||||
@@ -0,0 +1,224 @@
|
||||
# Performance Tests
|
||||
|
||||
The Azaion UI is a thin SPA; the dominant performance concerns are bundle size, auth-refresh transparency, SSE responsiveness, and UI reflection of server-confirmed state changes. Server-side throughput is OUT of scope here — this file covers the UI's observable timing only.
|
||||
|
||||
### NFT-PERF-01: Initial JS bundle ≤ 2 MB gzipped
|
||||
|
||||
**Summary**: The sum of gzipped initial-route JS chunks in `dist/` stays within the architecture's stated budget.
|
||||
**Traces to**: AC-11, O13
|
||||
**Metric**: gzipped byte total of initial JS entries.
|
||||
**Profile**: static
|
||||
|
||||
**Preconditions**:
|
||||
- `bun run build` has produced `dist/`.
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Measurement |
|
||||
|------|----------------|-------------|
|
||||
| 1 | Run `vite build` (or read the build manifest if already built) | `dist/` produced |
|
||||
| 2 | Walk Vite's `manifest.json` to enumerate entry chunks (non-async) | list of initial chunks |
|
||||
| 3 | Gzip-size each chunk (Node `zlib.gzipSync(content, {level:9})` or equivalent) | per-chunk size |
|
||||
| 4 | Sum sizes | total bytes |
|
||||
|
||||
**Pass criteria**: total ≤ 2 097 152 bytes (2 MB). Documentary today — no CI gate (AC-11 status: "target, not currently enforced"). Test exists so the gate flips to blocking the day CI wires it up.
|
||||
**Duration**: ≤ 60 s.
|
||||
**Expected result source**: `results_report.md` row 40.
|
||||
|
||||
---
|
||||
|
||||
### NFT-PERF-02: Auth refresh — exactly one network round trip per cycle
|
||||
|
||||
**Summary**: A single 401-triggered refresh round consists of exactly one `POST /api/admin/auth/refresh` plus one retry of the original request.
|
||||
**Traces to**: AC-01, AC-23
|
||||
**Metric**: count of `/api/admin/auth/refresh` requests per refresh event.
|
||||
**Profile**: fast
|
||||
|
||||
**Preconditions**:
|
||||
- Authenticated session.
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Measurement |
|
||||
|------|----------------|-------------|
|
||||
| 1 | Issue an authenticated request that returns 401 once, then 200 on retry | network log captured |
|
||||
| 2 | Count refresh requests fired in the cycle | exactly 1 |
|
||||
|
||||
**Pass criteria**: refresh count == 1 per cycle (`results_report.md` row 12 — exact).
|
||||
**Duration**: ≤ 5 s.
|
||||
**Expected result source**: `results_report.md` row 12.
|
||||
|
||||
---
|
||||
|
||||
### NFT-PERF-03: SSE bearer-rotation reconnect ≤ 5 s
|
||||
|
||||
**Summary**: When the bearer rotates while N SSE streams are open, all streams close and reopen with the new token within 5 s.
|
||||
**Traces to**: AC-24
|
||||
**Metric**: per-EventSource time from `close()` observed to next `OPEN` readyState (after reconnect with new token).
|
||||
**Profile**: fast — `quarantined` until SSE refresh-reconnect is implemented (Step 8 hardening)
|
||||
|
||||
**Preconditions**:
|
||||
- Two EventSources open (live-GPS + annotation-status).
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Measurement |
|
||||
|------|----------------|-------------|
|
||||
| 1 | Trigger a refresh that rotates the bearer | new bearer in memory |
|
||||
| 2 | For each EventSource: time from old `close` to new `OPEN` | dt_i (ms) |
|
||||
| 3 | Inspect new URLs for new token in query string | new `?token=` value |
|
||||
|
||||
**Pass criteria**: `max(dt_i) ≤ 5 000 ms`; both streams close+open exactly once (`results_report.md` row 13).
|
||||
**Duration**: ≤ 30 s.
|
||||
**Expected result source**: `results_report.md` row 13.
|
||||
|
||||
---
|
||||
|
||||
### NFT-PERF-04: Live-GPS SSE opens within 5 s of flight select
|
||||
|
||||
**Summary**: After clicking a flight in the Header, the live-GPS EventSource reaches `OPEN` quickly.
|
||||
**Traces to**: AC-08
|
||||
**Metric**: time from select-flight click to EventSource `readyState === 1` (OPEN).
|
||||
**Profile**: e2e (suite live-gps simulator emits events at 1 Hz)
|
||||
|
||||
**Preconditions**:
|
||||
- Authenticated; flight selectable.
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Measurement |
|
||||
|------|----------------|-------------|
|
||||
| 1 | Click a flight | one EventSource constructed to `^/api/flights/[0-9]+/live-gps(\?|$)` |
|
||||
| 2 | Wait for `OPEN` | dt (ms) |
|
||||
|
||||
**Pass criteria**: `dt ≤ 5 000 ms` (`results_report.md` row 34).
|
||||
**Duration**: ≤ 10 s.
|
||||
**Expected result source**: `results_report.md` row 34.
|
||||
|
||||
---
|
||||
|
||||
### NFT-PERF-05: Live-GPS SSE closes within 1 s of deselect
|
||||
|
||||
**Summary**: Deselecting the flight tears down the live-GPS stream promptly.
|
||||
**Traces to**: AC-08
|
||||
**Metric**: time from deselect to `CLOSED`.
|
||||
**Profile**: e2e
|
||||
|
||||
**Preconditions**:
|
||||
- Continuation of NFT-PERF-04.
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Measurement |
|
||||
|------|----------------|-------------|
|
||||
| 1 | Deselect the flight | EventSource closes |
|
||||
| 2 | Wait for `CLOSED` | dt (ms) |
|
||||
|
||||
**Pass criteria**: `dt ≤ 1 000 ms` and no remaining open live-GPS sources (`results_report.md` row 35).
|
||||
**Duration**: ≤ 5 s.
|
||||
**Expected result source**: `results_report.md` row 35.
|
||||
|
||||
---
|
||||
|
||||
### NFT-PERF-06: Annotation-status SSE unsubscribes within 1 s on page unmount
|
||||
|
||||
**Summary**: Navigating away from `/annotations` closes the status-events SSE within 1 s.
|
||||
**Traces to**: AC-09
|
||||
**Metric**: time from unmount to `CLOSED`.
|
||||
**Profile**: fast
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Measurement |
|
||||
|------|----------------|-------------|
|
||||
| 1 | Mount `/annotations` then unmount | EventSource transitions |
|
||||
| 2 | Measure dt | ms |
|
||||
|
||||
**Pass criteria**: `dt ≤ 1 000 ms` (`results_report.md` row 25).
|
||||
**Duration**: ≤ 5 s.
|
||||
**Expected result source**: `results_report.md` row 25.
|
||||
|
||||
---
|
||||
|
||||
### NFT-PERF-07: Bulk-validate UI reflects new status within 2 s
|
||||
|
||||
**Summary**: After a successful bulk-validate, every selected row shows `Validated` quickly.
|
||||
**Traces to**: AC-07
|
||||
**Metric**: time from server 200 to last DOM row update.
|
||||
**Profile**: fast
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Measurement |
|
||||
|------|----------------|-------------|
|
||||
| 1 | Select N items, click Validate | request issued |
|
||||
| 2 | Stub responds 200 | UI updates begin |
|
||||
| 3 | Wait for all N rows to show `Validated` | dt (ms) |
|
||||
|
||||
**Pass criteria**: `dt ≤ 2 000 ms` (`results_report.md` row 37).
|
||||
**Duration**: ≤ 5 s.
|
||||
**Expected result source**: `results_report.md` row 37.
|
||||
|
||||
---
|
||||
|
||||
### NFT-PERF-08: Panel-width persistence debounce ≤ 1 s after resize-end
|
||||
|
||||
**Summary**: A drag-end on a resizable panel triggers a single PUT within 1 s (debounced).
|
||||
**Traces to**: AC-21
|
||||
**Metric**: time from `mouseup` (drag-end) to outbound PUT; PUT count per drag.
|
||||
**Profile**: fast — `quarantined` until Step 4 writer is added
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Measurement |
|
||||
|------|----------------|-------------|
|
||||
| 1 | Drag and release a divider | event captured |
|
||||
| 2 | Wait for PUT or 1 s timeout | dt (ms); count |
|
||||
|
||||
**Pass criteria**: exactly 1 PUT within ≤ 1 000 ms; URL = `/api/annotations/settings/user`; body contains `panelWidths` (`results_report.md` row 64).
|
||||
**Duration**: ≤ 5 s.
|
||||
**Expected result source**: `results_report.md` row 64.
|
||||
|
||||
---
|
||||
|
||||
### NFT-PERF-09: Settings save error surfaces within 2 s
|
||||
|
||||
**Summary**: A 500 on settings save produces an error toast and resets the `saving` flag within 2 s.
|
||||
**Traces to**: AC-27
|
||||
**Metric**: time from server 500 to error visibility + state reset.
|
||||
**Profile**: fast — `quarantined` until Step 4 try/finally fix
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Measurement |
|
||||
|------|----------------|-------------|
|
||||
| 1 | Trigger save, stub responds 500 after T ms | failure delivered |
|
||||
| 2 | Wait for error toast and `saving === false` | dt (ms) |
|
||||
|
||||
**Pass criteria**: `dt ≤ 2 000 ms` (`results_report.md` row 68).
|
||||
**Duration**: ≤ 5 s.
|
||||
**Expected result source**: `results_report.md` row 68.
|
||||
|
||||
---
|
||||
|
||||
### NFT-PERF-10: First Contentful Paint on `/flights` ≤ 3 s on mid-range edge hardware
|
||||
|
||||
**Summary**: A warm-cache load of the default authenticated route renders the main pane within 3 s.
|
||||
**Traces to**: AC-11 (target), H2 (edge deploys)
|
||||
**Metric**: `performance.getEntriesByName('first-contentful-paint')[0].startTime`.
|
||||
**Profile**: e2e — documentary (no enforcement today; no AC binds a hard FCP budget)
|
||||
|
||||
**Preconditions**:
|
||||
- Warm browser cache (second visit).
|
||||
- Edge-profile container: 2 vCPU, 4 GB RAM (the hardware-assessment phase confirms the figure).
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Measurement |
|
||||
|------|----------------|-------------|
|
||||
| 1 | Navigate to `/flights` post-login | navigation completes |
|
||||
| 2 | Read FCP entry | ms |
|
||||
|
||||
**Pass criteria**: FCP ≤ 3 000 ms (row 98 — threshold_max).
|
||||
**Duration**: ≤ 30 s.
|
||||
**Expected result source**: `results_report.md` row 98.
|
||||
@@ -0,0 +1,244 @@
|
||||
# Resilience Tests
|
||||
|
||||
Failure / recovery scenarios at the SPA's observable boundary: bearer expiry, refresh cookie loss, upstream 5xx, network partition, oversized uploads, SSE drop. Every fault injection is at the network / browser layer; the UI is observed for graceful behavior and recovery.
|
||||
|
||||
### NFT-RES-01: 401 → refresh → retry recovery is transparent
|
||||
|
||||
**Summary**: An authenticated request that returns 401 mid-session is refreshed and retried without unmounting the routed view.
|
||||
**Traces to**: AC-01, AC-23
|
||||
|
||||
**Preconditions**:
|
||||
- Active session on `/flights`.
|
||||
|
||||
**Fault injection**:
|
||||
- Force a 401 on the next outbound authenticated request.
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Action | Expected Behavior |
|
||||
|------|--------|------------------|
|
||||
| 1 | Stub the next request to return 401 once | first response 401 |
|
||||
| 2 | Observe the SPA's reaction | `POST /api/admin/auth/refresh` with `credentials:'include'`; on 200, original request retried with new bearer |
|
||||
| 3 | Inspect `<ProtectedRoute>` children | not unmounted; re-render delta ≤ 1 |
|
||||
|
||||
**Pass criteria**: row 03 sequence; row 11 re-render bound (≤ 1); row 12 refresh count == 1 — all hold simultaneously.
|
||||
**Expected result source**: `results_report.md` rows 03, 11, 12.
|
||||
|
||||
---
|
||||
|
||||
### NFT-RES-02: SSE bearer-rotation — both streams reconnect within 5 s
|
||||
|
||||
**Summary**: A bearer rotation during open SSE streams (live-GPS + annotation-status) tears them down and reopens them with the new token.
|
||||
**Traces to**: AC-24
|
||||
|
||||
**Preconditions**:
|
||||
- Two EventSources open.
|
||||
|
||||
**Fault injection**:
|
||||
- Trigger a server-driven rotation of the bearer (force a refresh).
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Action | Expected Behavior |
|
||||
|------|--------|------------------|
|
||||
| 1 | Rotate bearer | new token in memory |
|
||||
| 2 | Observe each EventSource | closes, then reopens with new `?token=` |
|
||||
| 3 | Measure max reconnect time | ≤ 5 000 ms |
|
||||
|
||||
**Pass criteria**: both streams close+open exactly once; max reconnect ≤ 5 000 ms (`results_report.md` row 13).
|
||||
**Status**: `quarantined` until SSE reconnect-on-rotation ships (Step 8 hardening).
|
||||
**Expected result source**: `results_report.md` row 13.
|
||||
|
||||
---
|
||||
|
||||
### NFT-RES-03: Network offline at boot — error state, no offline mode
|
||||
|
||||
**Summary**: With network disabled, app boot results in a user-visible error state — NOT a service worker-served cached UI.
|
||||
**Traces to**: AC-N3
|
||||
|
||||
**Preconditions**:
|
||||
- Browser network disabled (or all `/api/*` stubs respond with offline error).
|
||||
|
||||
**Fault injection**:
|
||||
- All outbound requests fail with `net::ERR_INTERNET_DISCONNECTED` (or equivalent).
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Action | Expected Behavior |
|
||||
|------|--------|------------------|
|
||||
| 1 | Load the SPA | static assets served by nginx OK; API calls fail |
|
||||
| 2 | Observe DOM | login or general error surface present |
|
||||
| 3 | Inspect `navigator.serviceWorker.controller` | `null` |
|
||||
|
||||
**Pass criteria**: row 93 — error/login-failed state present; no service worker controller.
|
||||
**Expected result source**: `results_report.md` row 93.
|
||||
|
||||
---
|
||||
|
||||
### NFT-RES-04: ProtectedRoute loading timeout fallback after 10 s
|
||||
|
||||
**Summary**: The `<ProtectedRoute>` spinner has a bounded loading window; a stalled auth bootstrap surfaces a retry CTA / error.
|
||||
**Traces to**: AC-17
|
||||
|
||||
**Preconditions**:
|
||||
- Bootstrap refresh stubbed to never resolve.
|
||||
|
||||
**Fault injection**:
|
||||
- `POST /api/admin/auth/refresh` hangs (no response).
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Action | Expected Behavior |
|
||||
|------|--------|------------------|
|
||||
| 1 | Mount `<ProtectedRoute>` | spinner rendered |
|
||||
| 2 | Advance fake time to 10 s | timeout fires |
|
||||
| 3 | Inspect DOM | retry CTA or error message present; spinner unmounted |
|
||||
|
||||
**Pass criteria**: row 59 — fallback present, spinner absent.
|
||||
**Status**: `quarantined` until timeout fix lands (Step 4).
|
||||
**Expected result source**: `results_report.md` row 59.
|
||||
|
||||
---
|
||||
|
||||
### NFT-RES-05: Settings save with upstream 500 — UI state recovers
|
||||
|
||||
**Summary**: A 500 on settings save surfaces an error and resets the `saving` flag.
|
||||
**Traces to**: AC-27
|
||||
|
||||
**Preconditions**:
|
||||
- Form filled in valid state on `/settings`.
|
||||
|
||||
**Fault injection**:
|
||||
- Upstream `PUT /api/annotations/settings/system` returns 500 after T ms.
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Action | Expected Behavior |
|
||||
|------|--------|------------------|
|
||||
| 1 | Click Save | PUT issued |
|
||||
| 2 | Stub responds 500 within 2 s | failure |
|
||||
| 3 | Inspect within 2 s | toast / inline error; `saving === false`; no route navigation |
|
||||
|
||||
**Pass criteria**: row 68.
|
||||
**Status**: `quarantined` until Step 4 try/finally fix.
|
||||
**Expected result source**: `results_report.md` row 68.
|
||||
|
||||
---
|
||||
|
||||
### NFT-RES-06: Settings save with network drop — try/finally state reset
|
||||
|
||||
**Summary**: When the underlying fetch throws (network drop), `saving` resets and the user sees an error.
|
||||
**Traces to**: AC-27
|
||||
|
||||
**Preconditions**:
|
||||
- Form filled in valid state.
|
||||
|
||||
**Fault injection**:
|
||||
- Network drop mid-PUT (`fetch` rejects).
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Action | Expected Behavior |
|
||||
|------|--------|------------------|
|
||||
| 1 | Click Save | PUT issued |
|
||||
| 2 | Stub throws | rejection delivered |
|
||||
| 3 | Inspect | `saving === false`; error surfaced |
|
||||
|
||||
**Pass criteria**: row 69.
|
||||
**Status**: `quarantined`.
|
||||
**Expected result source**: `results_report.md` row 69.
|
||||
|
||||
---
|
||||
|
||||
### NFT-RES-07: nginx 413 on oversized upload surfaces user-visible error
|
||||
|
||||
**Summary**: An upload that exceeds `client_max_body_size 500M` returns 413; the UI presents a user-facing message (no silent failure, no `alert()`).
|
||||
**Traces to**: AC-10
|
||||
|
||||
**Preconditions**:
|
||||
- Authenticated; `<MediaList>` open.
|
||||
|
||||
**Fault injection**:
|
||||
- Drop a 501 MB synthetic file.
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Action | Expected Behavior |
|
||||
|------|--------|------------------|
|
||||
| 1 | Upload 501 MB | upload starts |
|
||||
| 2 | nginx rejects | 413 delivered |
|
||||
| 3 | Inspect UI | error containing the i18n "file too large" string; no `alert()` invoked |
|
||||
|
||||
**Pass criteria**: row 39.
|
||||
**Expected result source**: `results_report.md` row 39.
|
||||
|
||||
---
|
||||
|
||||
### NFT-RES-08: Refresh cookie expired — redirect to /login
|
||||
|
||||
**Summary**: When the refresh cookie is gone (or expired) and a 401 occurs, the SPA redirects the user to `/login` rather than silently looping refresh.
|
||||
**Traces to**: AC-01, AC-22
|
||||
|
||||
**Preconditions**:
|
||||
- Cookie cleared from the browser jar.
|
||||
|
||||
**Fault injection**:
|
||||
- 401 on any authenticated call; subsequent `POST /api/admin/auth/refresh` returns 401.
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Action | Expected Behavior |
|
||||
|------|--------|------------------|
|
||||
| 1 | Issue authenticated call | 401 |
|
||||
| 2 | Refresh attempted | 401 (no cookie) |
|
||||
| 3 | Observe routing | redirect to `/login` |
|
||||
|
||||
**Pass criteria**: final URL `/login`; no infinite refresh loop (single refresh attempt). Derived from AC-01 + AC-22; no specific results_report row binds the loop bound — Phase 3 flags this and the loop bound is added to row 03 if accepted.
|
||||
|
||||
---
|
||||
|
||||
### NFT-RES-09: Annotation download tainted-canvas fallback
|
||||
|
||||
**Summary**: When `<canvas>.toBlob()` raises a tainted-canvas exception (cross-origin video frame), the user sees an error rather than a silent no-op.
|
||||
**Traces to**: NFR (`04_verification_log.md` finding on `handleDownload` tainted-canvas risk)
|
||||
|
||||
**Preconditions**:
|
||||
- An annotation is loaded from a video sourced with CORS that taints the canvas.
|
||||
|
||||
**Fault injection**:
|
||||
- Cross-origin video source taints the canvas; `toBlob` throws.
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Action | Expected Behavior |
|
||||
|------|--------|------------------|
|
||||
| 1 | Click Download | export attempted |
|
||||
| 2 | toBlob throws | error handled |
|
||||
| 3 | Inspect UI | user-visible error; no `alert()`; no silent swallow |
|
||||
|
||||
**Pass criteria**: row 96 — error surfaced; no silent swallow; no fabricated blob; no `alert()`.
|
||||
**Expected result source**: `results_report.md` row 96.
|
||||
|
||||
---
|
||||
|
||||
### NFT-RES-10: SSE server disconnect — UI surfaces a connection-lost indicator
|
||||
|
||||
**Summary**: When the suite server closes a live-GPS or status-events SSE without rotation, the UI does NOT show stale data and DOES indicate the connection lost.
|
||||
**Traces to**: AC-08, AC-09, AC-24
|
||||
|
||||
**Preconditions**:
|
||||
- One SSE stream open.
|
||||
|
||||
**Fault injection**:
|
||||
- Server force-closes the stream (no rotation).
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Action | Expected Behavior |
|
||||
|------|--------|------------------|
|
||||
| 1 | Drop the stream from the server | `error` fires on EventSource |
|
||||
| 2 | Observe DOM | a connection-lost indicator is rendered (or stale-data badge) |
|
||||
| 3 | Observe reconnect behavior | `EventSource` auto-retries per browser default; if the SPA re-creates it, exactly one new instance |
|
||||
|
||||
**Pass criteria**: row 97 — connection-lost indicator OR reconnect attempt within 10 s; stale data NOT rendered as live; reconnect attempts ≤ 1 in the 10 s window.
|
||||
**Expected result source**: `results_report.md` row 97.
|
||||
@@ -0,0 +1,213 @@
|
||||
# Resource Limit Tests
|
||||
|
||||
The SPA's resource constraints are bundle size (initial JS), upload size cap (server), runtime image footprint (`nginx:alpine` only), and exclusion of the unbundled `mission-planner/` from production output. Long-session memory / CPU behavior is also covered here at a documentary level — no AC binds a hard runtime memory budget today.
|
||||
|
||||
### NFT-RES-LIM-01: Initial JS bundle ≤ 2 MB gzipped
|
||||
|
||||
**Traces to**: AC-11, O13
|
||||
|
||||
**Preconditions**:
|
||||
- `bun run build` has produced `dist/`.
|
||||
|
||||
**Monitoring**:
|
||||
- Sum of gzipped initial-route JS chunk sizes (computed from Vite's `manifest.json`).
|
||||
|
||||
**Duration**: ≤ 60 s (build + measurement).
|
||||
**Pass criteria**: total gzipped initial JS ≤ 2 097 152 bytes (`results_report.md` row 40). Documentary today; CI gate target.
|
||||
**Expected result source**: `results_report.md` row 40.
|
||||
|
||||
---
|
||||
|
||||
### NFT-RES-LIM-02: nginx `client_max_body_size 500M`
|
||||
|
||||
**Traces to**: AC-10, E9
|
||||
|
||||
**Preconditions**:
|
||||
- `nginx.conf` present in the repo (and in the built image's `/etc/nginx/`).
|
||||
|
||||
**Monitoring**:
|
||||
- Read the value of `client_max_body_size` from `nginx.conf`.
|
||||
|
||||
**Duration**: ≤ 5 s.
|
||||
**Pass criteria**: value equals `500M` (`results_report.md` row 38).
|
||||
**Expected result source**: `results_report.md` row 38.
|
||||
|
||||
---
|
||||
|
||||
### NFT-RES-LIM-03: Production image is `nginx:alpine` and carries no Node.js
|
||||
|
||||
**Traces to**: AC-33, S5, O11
|
||||
|
||||
**Preconditions**:
|
||||
- Built image `azaion/ui:<tag>` available locally.
|
||||
|
||||
**Monitoring**:
|
||||
- `docker inspect azaion/ui:<tag>` for the final stage's base image.
|
||||
- Filesystem scan inside the image for a `node` binary.
|
||||
|
||||
**Duration**: ≤ 30 s.
|
||||
**Pass criteria**: base image is `nginx:alpine`; no `node` binary present (`results_report.md` row 42).
|
||||
**Expected result source**: `results_report.md` row 42.
|
||||
|
||||
---
|
||||
|
||||
### NFT-RES-LIM-04: `mission-planner/` is excluded from production bundle
|
||||
|
||||
**Traces to**: AC-31, O12, ADR-009
|
||||
|
||||
**Preconditions**:
|
||||
- `bun run build` has produced `dist/`.
|
||||
|
||||
**Monitoring**:
|
||||
- Vite's build report / manifest for chunk origins.
|
||||
- Static-import graph analysis starting from `src/main.tsx` — verify no edges into `mission-planner/`.
|
||||
|
||||
**Duration**: ≤ 30 s.
|
||||
**Pass criteria**: no `dist/**` file originates from `mission-planner/**`; the import graph from `src/main.tsx` does NOT reach `mission-planner/` (`results_report.md` row 41).
|
||||
**Expected result source**: `results_report.md` row 41.
|
||||
|
||||
---
|
||||
|
||||
### NFT-RES-LIM-05: SPA memory stable across a 30-minute annotation session
|
||||
|
||||
**Traces to**: H2 (edge deploy), AC-09 (SSE)
|
||||
**Status**: documentary — no AC binds a hard runtime memory budget today
|
||||
|
||||
**Preconditions**:
|
||||
- E2E profile; user logged in on `/annotations`; annotation-status SSE open.
|
||||
|
||||
**Monitoring**:
|
||||
- Headless Chromium `performance.memory.usedJSHeapSize` sampled every 60 s for 30 min.
|
||||
|
||||
**Duration**: 30 min.
|
||||
**Pass criteria**: `usedJSHeapSize` does not grow by more than 50 % over the session under steady-state interaction (open/close media, page through dataset). A documentary baseline; if Phase 3 deems it un-anchored to an AC, it is downgraded to a metric-only run.
|
||||
|
||||
---
|
||||
|
||||
### NFT-RES-LIM-06: Live-GPS SSE 1-hour soak — no listener leak, no memory creep
|
||||
|
||||
**Traces to**: AC-08
|
||||
**Status**: documentary
|
||||
|
||||
**Preconditions**:
|
||||
- E2E profile; flight selected; live-GPS simulator emits at 1 Hz.
|
||||
|
||||
**Monitoring**:
|
||||
- `EventSource` instance count sampled every 60 s — must stay at exactly 1.
|
||||
- `usedJSHeapSize` sampled every 60 s.
|
||||
|
||||
**Duration**: 60 min.
|
||||
**Pass criteria**: EventSource count stays at 1 throughout; heap grows by ≤ 30 % (documentary).
|
||||
|
||||
---
|
||||
|
||||
### NFT-RES-LIM-07: 100 sequential flight selections — no leaked SSEs, no leaked Contexts
|
||||
|
||||
**Traces to**: AC-08, P4
|
||||
**Status**: documentary
|
||||
|
||||
**Preconditions**:
|
||||
- E2E profile; ≥ 5 flights in seed.
|
||||
|
||||
**Monitoring**:
|
||||
- Total EventSource instances created over the loop.
|
||||
- Final open EventSource count (after deselect-then-reselect cycles end at "deselected").
|
||||
|
||||
**Duration**: ≤ 5 min.
|
||||
**Pass criteria**: after the loop, open EventSource count is ≤ 1 (only the currently-selected stream if any). No more than `100 + 1 ` EventSources were created in total (one extra for any pre-test state). Documentary; Phase 3 to confirm or downgrade.
|
||||
|
||||
---
|
||||
|
||||
### NFT-RES-LIM-08: Edge-host RAM profile of the UI image at steady state
|
||||
|
||||
**Traces to**: H2
|
||||
**Status**: documentary; hardware-assessment phase will pin the exact numbers
|
||||
|
||||
**Preconditions**:
|
||||
- Production image running on the target edge profile (2 vCPU, 4 GB RAM).
|
||||
|
||||
**Monitoring**:
|
||||
- `docker stats azaion-ui` sampled every 10 s for 5 min while a user is actively on `/annotations` with one open SSE.
|
||||
|
||||
**Duration**: 5 min.
|
||||
**Pass criteria**: RSS of the nginx process under sustained traffic stays under 200 MB (documentary baseline; will be tightened or relaxed at hardware-assessment time).
|
||||
|
||||
---
|
||||
|
||||
### NFT-RES-LIM-09: nginx routes — exactly 9 location blocks for the suite services
|
||||
|
||||
**Traces to**: AC-34, E2
|
||||
|
||||
**Preconditions**:
|
||||
- `nginx.conf` present.
|
||||
|
||||
**Monitoring**:
|
||||
- Parse `nginx.conf` for `location` blocks under the main `server`.
|
||||
|
||||
**Duration**: ≤ 5 s.
|
||||
**Pass criteria**: `location` block set equals `{/api/admin/, /api/flights/, /api/annotations/, /api/detect/, /api/loader/, /api/gps-denied-desktop/, /api/gps-denied-onboard/, /api/autopilot/, /api/resource/}` (`results_report.md` row 43).
|
||||
**Expected result source**: `results_report.md` row 43.
|
||||
|
||||
---
|
||||
|
||||
### NFT-RES-LIM-10: nginx — each route strips its `/api/<service>/` prefix
|
||||
|
||||
**Traces to**: AC-34, E2
|
||||
|
||||
**Preconditions**:
|
||||
- `nginx.conf` present.
|
||||
|
||||
**Monitoring**:
|
||||
- Per `location` block, inspect the `proxy_pass` / `rewrite` directive shape — verify the prefix is stripped before forwarding upstream.
|
||||
|
||||
**Duration**: ≤ 5 s.
|
||||
**Pass criteria**: every block satisfies the strip-prefix regex (per-block check, `results_report.md` row 44).
|
||||
**Expected result source**: `results_report.md` row 44.
|
||||
|
||||
---
|
||||
|
||||
### NFT-RES-LIM-11: CI image tag scheme is `${branch}-arm`
|
||||
|
||||
**Traces to**: AC-32, E7
|
||||
|
||||
**Preconditions**:
|
||||
- `.woodpecker/build-arm.yml` present.
|
||||
|
||||
**Monitoring**:
|
||||
- Parse the push step's `tag` field for branches `dev`, `stage`, `main`.
|
||||
|
||||
**Duration**: ≤ 5 s.
|
||||
**Pass criteria**: pushed tag for branch `main` matches `^main-arm$` (`results_report.md` row 70). Same regex shape for `dev` and `stage` (derived).
|
||||
**Expected result source**: `results_report.md` row 70.
|
||||
|
||||
---
|
||||
|
||||
### NFT-RES-LIM-12: OCI labels present on the pushed image
|
||||
|
||||
**Traces to**: AC-32, E6
|
||||
|
||||
**Preconditions**:
|
||||
- `.woodpecker/build-arm.yml` present.
|
||||
|
||||
**Monitoring**:
|
||||
- Parse the push step's label declarations — count and presence.
|
||||
|
||||
**Duration**: ≤ 5 s.
|
||||
**Pass criteria**: labels `org.opencontainers.image.revision`, `org.opencontainers.image.created`, `org.opencontainers.image.source` are all declared and non-empty; total label count == 3 (`results_report.md` row 71).
|
||||
**Expected result source**: `results_report.md` row 71.
|
||||
|
||||
---
|
||||
|
||||
### NFT-RES-LIM-13: Revision label equals `$CI_COMMIT_SHA`
|
||||
|
||||
**Traces to**: AC-32, E5
|
||||
|
||||
**Preconditions**:
|
||||
- `.woodpecker/build-arm.yml` present.
|
||||
|
||||
**Monitoring**:
|
||||
- Parse the label value template for `org.opencontainers.image.revision`.
|
||||
|
||||
**Duration**: ≤ 5 s.
|
||||
**Pass criteria**: label value template equals `$CI_COMMIT_SHA` (or the pipeline's documented equivalent) (`results_report.md` row 72).
|
||||
**Expected result source**: `results_report.md` row 72.
|
||||
@@ -0,0 +1,246 @@
|
||||
# Security Tests
|
||||
|
||||
Blackbox security assertions against the SPA's observable surface: token storage discipline, refresh cookie attributes, RBAC route gating, credentials flag, secrets-in-source checks, destructive-action policy, dependency hygiene. These complement the server's RBAC and the suite's security_approach (`_docs/00_problem/security_approach.md`); they do NOT replace server-side enforcement (O4).
|
||||
|
||||
### NFT-SEC-01: Bearer is never written to `localStorage` or `sessionStorage`
|
||||
|
||||
**Traces to**: AC-02, O2
|
||||
**Profile**: static + e2e
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected Response |
|
||||
|------|----------------|------------------|
|
||||
| 1 | Static code-search on `src/` and `mission-planner/src/` for `localStorage.|sessionStorage.` near `bearer|token|accessToken` | `match_count == 0` |
|
||||
| 2 | E2E: complete a login; inspect `localStorage` and `sessionStorage` keys | neither contains the bearer value |
|
||||
|
||||
**Pass criteria**: row 04 — `match_count == 0`; runtime storage does not contain the bearer.
|
||||
**Expected result source**: `results_report.md` row 04.
|
||||
|
||||
---
|
||||
|
||||
### NFT-SEC-02: `document.cookie` does not expose the refresh token
|
||||
|
||||
**Traces to**: AC-03
|
||||
**Profile**: e2e + static
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected Response |
|
||||
|------|----------------|------------------|
|
||||
| 1 | Static code-search for `document.cookie` reads against `refreshToken|refresh-cookie` | `match_count == 0` (row 05) |
|
||||
| 2 | E2E: complete login; read `document.cookie` from page context | returned string does NOT contain the refresh-token value (row 06) |
|
||||
|
||||
**Pass criteria**: rows 05 + 06.
|
||||
**Expected result source**: `results_report.md` rows 05, 06.
|
||||
|
||||
---
|
||||
|
||||
### NFT-SEC-03: Refresh cookie attributes — `Secure`, `HttpOnly`, `SameSite=Strict`
|
||||
|
||||
**Traces to**: AC-03, E3, O5
|
||||
**Profile**: e2e
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected Response |
|
||||
|------|----------------|------------------|
|
||||
| 1 | Login via `POST /api/admin/auth/login` against the suite stack | `Set-Cookie` header returned |
|
||||
| 2 | Inspect header value | matches regex `Secure;.*HttpOnly;.*SameSite=Strict` (case-insensitive, attribute-order-tolerant) |
|
||||
|
||||
**Pass criteria**: row 07 — regex match.
|
||||
**Notes**: this is a server-contract assertion; the UI test exists as defence-in-depth so a suite regression is caught before it lands in production.
|
||||
**Expected result source**: `results_report.md` row 07.
|
||||
|
||||
---
|
||||
|
||||
### NFT-SEC-04: `credentials: 'include'` is set on every authenticated fetch
|
||||
|
||||
**Traces to**: AC-01, O3
|
||||
**Profile**: fast (apiClient wrapper) + e2e (live capture)
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected Response |
|
||||
|------|----------------|------------------|
|
||||
| 1 | Issue an authenticated request via `apiClient` | RequestInit captured |
|
||||
| 2 | Inspect | `credentials === 'include'` (row 01) |
|
||||
| 3 | Repeat for the bootstrap refresh | same (row 02 — `quarantined` until Step 4 bootstrap fix) |
|
||||
|
||||
**Pass criteria**: rows 01 + 02.
|
||||
**Expected result source**: `results_report.md` rows 01, 02.
|
||||
|
||||
---
|
||||
|
||||
### NFT-SEC-05: `/admin` route blocks non-admins client-side (defence in depth)
|
||||
|
||||
**Traces to**: AC-22
|
||||
**Profile**: e2e — `quarantined` until role-gate is added (Step 4 / Step 8)
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected Response |
|
||||
|------|----------------|------------------|
|
||||
| 1 | Log in as `op_alice` (Operator, no admin role) | session active |
|
||||
| 2 | Navigate to `/admin` | URL changes |
|
||||
| 3 | Inspect final URL + DOM | URL is `/flights`; `<AdminPage>` NOT mounted |
|
||||
|
||||
**Pass criteria**: row 08.
|
||||
**Notes**: server-side RBAC is authoritative; the UI gate is a usability + leakage layer.
|
||||
**Expected result source**: `results_report.md` row 08.
|
||||
|
||||
---
|
||||
|
||||
### NFT-SEC-06: `/settings` route gate is applied per RBAC
|
||||
|
||||
**Traces to**: AC-22
|
||||
**Profile**: e2e — `quarantined`
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected Response |
|
||||
|------|----------------|------------------|
|
||||
| 1 | Log in as user without SETTINGS permission | session active |
|
||||
| 2 | Navigate to `/settings` | URL changes |
|
||||
| 3 | Inspect | URL is `/flights`; `<SettingsPage>` NOT mounted |
|
||||
|
||||
**Pass criteria**: row 10.
|
||||
**Expected result source**: `results_report.md` row 10.
|
||||
|
||||
---
|
||||
|
||||
### NFT-SEC-07: `alert()` is forbidden anywhere in the SPA
|
||||
|
||||
**Traces to**: AC-14, O10
|
||||
**Profile**: static
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected Response |
|
||||
|------|----------------|------------------|
|
||||
| 1 | Regex sweep `src/` and `mission-planner/src/` for `\balert\(` | `match_count == 0` |
|
||||
|
||||
**Pass criteria**: row 50.
|
||||
**Expected result source**: `results_report.md` row 50.
|
||||
|
||||
---
|
||||
|
||||
### NFT-SEC-08: ConfirmDialog gates every destructive action
|
||||
|
||||
**Traces to**: AC-14, AC-30, O10
|
||||
**Profile**: fast
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected Response |
|
||||
|------|----------------|------------------|
|
||||
| 1 | For each destructive surface in `_docs/ui_design/` (class delete, user deactivate, dataset bulk-overwrite, etc.) | sequence checked |
|
||||
| 2 | Confirm sequence on click → before any HTTP fires | dialog present (row 51) |
|
||||
| 3 | On Confirm in class-delete flow → exactly one DELETE to `^/api/admin/classes/[0-9]+$` | (row 49) |
|
||||
|
||||
**Pass criteria**: rows 49 + 51.
|
||||
**Expected result source**: `results_report.md` rows 49, 51.
|
||||
|
||||
---
|
||||
|
||||
### NFT-SEC-09: OpenWeatherMap API key is not shipped in source or bundle
|
||||
|
||||
**Traces to**: AC-20, P10
|
||||
**Profile**: static (source) + static (bundle)
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected Response |
|
||||
|------|----------------|------------------|
|
||||
| 1 | Regex sweep `src/` and `mission-planner/src/` for the literal current OWM key value | `match_count == 0` (row 63) |
|
||||
| 2 | Regex sweep for `appid=` and `api_key=` literal occurrences in source URLs | `match_count == 0` (row 63) |
|
||||
| 3 | Scan `dist/**/*.js` post-build for the literal key | `match_count == 0` (Phase 3 may downgrade to "until Step 4 fix") |
|
||||
|
||||
**Pass criteria**: row 63.
|
||||
**Status**: `quarantined` for source check until Step 4 fix; the bundle-scan check passes immediately for `src/` (mission-planner not bundled, AC-31).
|
||||
**Expected result source**: `results_report.md` row 63.
|
||||
|
||||
---
|
||||
|
||||
### NFT-SEC-10: No in-browser ML libs
|
||||
|
||||
**Traces to**: AC-N2
|
||||
**Profile**: static
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected Response |
|
||||
|------|----------------|------------------|
|
||||
| 1 | Parse `package.json` and `mission-planner/package.json` dependencies | dependency lists |
|
||||
| 2 | Match against `^(onnxruntime|@?tensorflow(?:js)?(?:/.*)?|tflite|coreml|tfjs|@huggingface/.*|transformers\.js)$` | zero matches |
|
||||
|
||||
**Pass criteria**: row 92.
|
||||
**Expected result source**: `results_report.md` row 92.
|
||||
|
||||
---
|
||||
|
||||
### NFT-SEC-11: No response-signature / JOSE libs on the request path
|
||||
|
||||
**Traces to**: AC-N4
|
||||
**Profile**: static
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected Response |
|
||||
|------|----------------|------------------|
|
||||
| 1 | Parse `package.json` dependencies | list |
|
||||
| 2 | Match against `^(jsrsasign|tweetnacl|@noble/.*|jose)$` | zero matches |
|
||||
|
||||
**Pass criteria**: row 94.
|
||||
**Expected result source**: `results_report.md` row 94.
|
||||
|
||||
---
|
||||
|
||||
### NFT-SEC-12: No service worker — offline mode is explicitly absent
|
||||
|
||||
**Traces to**: AC-N3
|
||||
**Profile**: e2e
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected Response |
|
||||
|------|----------------|------------------|
|
||||
| 1 | Load the SPA in a fresh browser context | app boots |
|
||||
| 2 | Read `navigator.serviceWorker.getRegistrations()` | empty array |
|
||||
|
||||
**Pass criteria**: row 93 — no service worker registered.
|
||||
**Expected result source**: `results_report.md` row 93.
|
||||
|
||||
---
|
||||
|
||||
### NFT-SEC-13: Dropped legacy features are not present in source
|
||||
|
||||
**Traces to**: AC-N5
|
||||
**Profile**: static
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected Response |
|
||||
|------|----------------|------------------|
|
||||
| 1 | Regex sweep `src/` and `mission-planner/src/` for `SoundDetections|DroneMaintenance` | `match_count == 0` |
|
||||
|
||||
**Pass criteria**: row 95.
|
||||
**Expected result source**: `results_report.md` row 95.
|
||||
|
||||
---
|
||||
|
||||
### NFT-SEC-14: Anti-criterion AC-N1 — no concurrent-edit reconciliation surfaces
|
||||
|
||||
**Traces to**: AC-N1
|
||||
**Profile**: e2e + static
|
||||
|
||||
**Steps**:
|
||||
|
||||
| Step | Consumer Action | Expected Response |
|
||||
|------|----------------|------------------|
|
||||
| 1 | Open the same annotation in two browser sessions; edit both | both save individually |
|
||||
| 2 | Inspect each session's DOM | no merge UI; no presence indicator |
|
||||
|
||||
**Pass criteria**: row 91.
|
||||
**Notes**: this is an anti-criterion — the test enforces that the feature is NOT silently added.
|
||||
**Expected result source**: `results_report.md` row 91.
|
||||
@@ -0,0 +1,100 @@
|
||||
# Test Data Management
|
||||
|
||||
The Azaion UI is a thin client over a typed REST + SSE contract — it carries no database of its own (P3 / P4 / `data_parameters.md`). "Test data" therefore means three things:
|
||||
|
||||
1. **Suite-side seed fixtures** loaded into the `e2e` profile's docker-compose stack (users, flights, aircraft, classes, sample media).
|
||||
2. **Stub responses** mounted on the `fast` profile's request-interception layer (canned `/api/<service>/*` payloads, canned OpenWeatherMap and OSM tile responses).
|
||||
3. **Source-level fixtures** committed in this repo: i18n bundles, enum spec snapshots, `nginx.conf`, `vite.config.ts`, `package.json`, and the `dist/` build output.
|
||||
|
||||
There are NO image / video / `.tlog` input files under `_docs/00_problem/input_data/` for this project — the cell `data_parameters.md` and `results_report.md` already make this explicit. Every observable assertion lives in `_docs/00_problem/input_data/expected_results/results_report.md` (95 rows) which the tests reference verbatim.
|
||||
|
||||
## Seed Data Sets
|
||||
|
||||
| Data Set | Description | Used by Tests | How Loaded | Cleanup |
|
||||
|----------|-------------|---------------|-----------|---------|
|
||||
| `seed_users` | 4 users: `op_alice` (Operator), `op_bob` (Operator, no SETTINGS permission), `admin_carol` (Admin), `integrator_dave` (System Integrator). All with known passwords for test login. | All `e2e` tests that authenticate | `admin/` service init script reads `seed-fixtures/users.json` at container start | `docker compose down -v` wipes `test-db-data` between e2e suite runs |
|
||||
| `seed_aircraft` | 3 aircraft with one marked `isDefault: true` | E2E tests touching `/flights`, `/admin` aircraft tab | `flights/` service init script | as above |
|
||||
| `seed_flights` | 5 flights spanning the 4 users; some with waypoints, one with `LiveGpsEvent` simulator wired | E2E tests touching `/flights` and the live-GPS stream | `flights/` service init script | as above |
|
||||
| `seed_classes` | The contract's `[0..N-1, 20..20+N-1, 40..40+N-1]` ordering (per AC-37 / `data_model.md:158`) — N≥9 so number-key hotkeys 1..9 are all hot. | `<DetectionClasses>` component + `<AdminPage>` class CRUD tests | `annotations/` (read path) + `admin/` (write path) init scripts | as above |
|
||||
| `seed_media` | 6 media items (3 images, 3 videos) attached to `seed_flights`, with mediaStatus values exercising the full enum after AC-04 fix lands (`None`, `New`, `AiProcessing`, `AiProcessed`, `ManualCreated`, `Confirmed`, `Error`) | E2E tests touching `/annotations` and `/dataset` | `annotations/` init script | as above |
|
||||
| `seed_annotations` | Annotations for `seed_media`, including: some with `Source: AI`, some `Manual`; one with `isSplit: true` and a valid `splitTile` "3 0.5 0.5 0.2 0.2" (AC-39); one with malformed `splitTile` ("garbage", AC-39 sad path); status values spanning the full `AnnotationStatus` enum after AC-04 fix (`None=0`, `Created=10`, `Edited=20`, `Validated=30`, `Deleted=40`) | E2E tests for `<AnnotationsPage>`, `<CanvasEditor>`, `<DatasetPage>` | `annotations/` init script | as above |
|
||||
| `seed_user_settings` | Known `selectedFlightId` and `panelWidths` for `op_alice` so the rehydration tests assert against a deterministic state | AC-21, AC-06 tests | `annotations/` init script | as above |
|
||||
| `enum_spec_snapshot` | A committed JSON file `_docs/00_problem/input_data/enum_spec_snapshot.json` that pins the contract values for `AnnotationStatus`, `MediaStatus`, `Affiliation`, `CombatReadiness`, `MediaType`, `AnnotationSource`, `WaypointSource`, `WaypointObjective`. Populated from `../_docs/00_database_schema.md` (authoritative) with the UI's current drift documented in `ui_drift_summary`. `CombatReadiness` + `MediaType` are flagged `verification_pending: true` because the schema does not pin numeric values; Step 4 .NET-service inspection finalizes them. | Static checks for AC-04 / AC-29 (Group 2 rows 14-19 of `results_report.md`) | Read directly from the repo at test time. | n/a (committed at Phase 3). |
|
||||
| `bundle_artifact` | The `dist/` produced by `vite build`. | AC-11, AC-31, AC-33 (Group 7 rows 40-44) | Built by the CI step before tests run. | Ephemeral per CI run. |
|
||||
|
||||
## Data Isolation Strategy
|
||||
|
||||
- **`fast` profile**: each test creates its own MSW handlers and tears them down in the test runner's `afterEach`. No process-wide state. React tree is unmounted between tests. Test files MAY share an enum spec snapshot (read-only) since it is a contract pin.
|
||||
- **`e2e` profile**: each `e2e` run gets a fresh suite docker-compose stack (`docker compose down -v` then `up -d`) before the suite executes. Inside a run, tests group into **isolation buckets** by data set; a bucket runs sequentially against a known seed state, then the seeds are reset between buckets via `admin/` service's `POST /test-only/reset` (a test-only endpoint, gated behind a non-production build flag). Buckets across different machines run on independent compose stacks.
|
||||
- **Per-user isolation**: tests that mutate user-scoped state (e.g., `selectedFlightId`, panel widths) use distinct seed users so concurrent tests within a bucket cannot race on the same `UserSettings` row.
|
||||
- **No cross-test order dependencies** — any test must be re-runnable in isolation by booting the bucket's seed snapshot.
|
||||
|
||||
## Input Data Mapping
|
||||
|
||||
The UI has no consumer-side input files (images, videos, `.tlog`s). Every test "input" is a **trigger** classified per `test-spec/SKILL.md` "Behavioral shape" — a user action, a request the SPA initiates, an SSE event, or a static check against the repo / `dist/`. The `Input` column of each test in `blackbox-tests.md` / etc. references a `results_report.md` row (which already defines the trigger and the quantifiable observable).
|
||||
|
||||
| Input Reference | Source Location | Description | Covers Scenarios |
|
||||
|-----------------|----------------|-------------|-----------------|
|
||||
| `results_report.md` rows 1-13 | `_docs/00_problem/input_data/expected_results/results_report.md` | Auth & token-handling triggers | Group 1 tests (FT-P-01..FT-P-13 / FT-N-* per blackbox-tests.md) |
|
||||
| `results_report.md` rows 14-21 | as above | Wire-contract / enum compliance triggers | Group 2 tests |
|
||||
| `results_report.md` rows 22-31 | as above | Annotations endpoint / payload / SSE / overlay-window triggers | Group 3 tests |
|
||||
| `results_report.md` rows 32-35 | as above | Flight selection persistence + live-GPS SSE triggers | Group 4 tests |
|
||||
| `results_report.md` rows 36-37 | as above | Dataset bulk-validate triggers | Group 5 tests |
|
||||
| `results_report.md` rows 38-39 | as above | Upload size cap triggers | Group 6 tests |
|
||||
| `results_report.md` rows 40-44 | as above | Build / bundle / routing triggers | Group 7 tests |
|
||||
| `results_report.md` rows 45-48 | as above | i18n triggers | Group 8 tests |
|
||||
| `results_report.md` rows 49-51 | as above | Destructive-UX triggers | Group 9 tests |
|
||||
| `results_report.md` rows 52-59 | as above | A11y triggers | Group 10 tests |
|
||||
| `results_report.md` rows 60-62 | as above | Browser-support + responsive triggers | Group 11 tests |
|
||||
| `results_report.md` row 63 | as above | OWM secrets check | Group 12 test |
|
||||
| `results_report.md` rows 64-65 | as above | User-settings persistence triggers | Group 13 tests |
|
||||
| `results_report.md` rows 66-69 | as above | Form hygiene triggers | Group 14 tests |
|
||||
| `results_report.md` rows 70-72 | as above | CI / image / labels triggers | Group 15 tests |
|
||||
| `results_report.md` rows 73-84 | as above | Canvas + DetectionClasses + PhotoMode triggers | Group 16 tests |
|
||||
| `results_report.md` rows 85-90 | as above | Tile splitting + tile-zoom triggers | Group 17 tests |
|
||||
| `results_report.md` rows 91-95 | as above | Anti-criteria triggers | Group 18 tests |
|
||||
|
||||
## Expected Results Mapping
|
||||
|
||||
Every test in `blackbox-tests.md`, `performance-tests.md`, `resilience-tests.md`, `security-tests.md`, and `resource-limit-tests.md` carries an `Expected result source: results_report.md row <N>` line in its body. The comparison method, tolerance, and reference file (if any) are inherited from that row — tests do not re-state them. The `traceability-matrix.md` aggregates: AC → results_report row(s) → test ID(s).
|
||||
|
||||
| Test Scenario ID | Input Data | Expected Result | Comparison Method | Tolerance | Expected Result Source |
|
||||
|-----------------|------------|-----------------|-------------------|-----------|----------------------|
|
||||
| (see `blackbox-tests.md` etc.) | (row reference) | (row's Expected Result column) | (row's Comparison column) | (row's Tolerance column) | `results_report.md` row N |
|
||||
|
||||
No reference files (e.g. JSON / CSV) are required at this stage — every observable in `results_report.md` is small enough to fit inline. If a downstream test needs a multi-row expected payload (e.g. the suite's full class-distribution response shape), the file will be added in `_docs/00_problem/input_data/expected_results/` per the naming convention `<input_name>_expected.<ext>` and the row updated to reference it. The Phase 3 Data Validation Gate will surface this if it happens.
|
||||
|
||||
## External Dependency Mocks
|
||||
|
||||
| External Service | Mock/Stub | How Provided | Behavior |
|
||||
|-----------------|-----------|-------------|----------|
|
||||
| OpenWeatherMap (E10) | `owm-stub` HTTP service (e2e) / MSW handler (fast) | Docker service `owm-stub:8081` (e2e) / per-test MSW handler (fast) | Returns canned `/data/2.5/onecall` JSON with deterministic wind/precip values. Tests that exercise wind compute (`flightPlanUtils.ts` once moved into `src/`) assert against these canned values. |
|
||||
| OSM tile servers | `tile-stub` HTTP service (e2e) / never hit in fast | Docker service `tile-stub:8082` returning a fixed 256x256 PNG | Replaces `a.tile.openstreetmap.org` etc.; map tile loads do not depend on internet. |
|
||||
| Suite microservices (`admin/`, `flights/`, `annotations/`, `detect/`, ...) | Real services (e2e) / MSW handlers (fast) | docker-compose (e2e) / per-test handler (fast) | Production-shape responses per `data_parameters.md` §1. Errors injected per resilience tests (5xx, 413, network drop). |
|
||||
| GPS-Denied services (target) | `gps-denied-desktop` + `gps-denied-onboard` real services (e2e); no fast coverage today | docker-compose | F12 Test Mode is target-only — tests for it are quarantined until the feature lands (see Open Items in `results_report.md`). |
|
||||
| LiveGPS simulator | Embedded in `flights/` service test mode | docker-compose | Emits deterministic `LiveGpsEvent` payloads at 1 Hz on `/api/flights/<id>/live-gps` so AC-08 timing assertions are stable. |
|
||||
| Annotation-status events generator | Embedded in `annotations/` service test mode | docker-compose | Allows tests to trigger `AnnotationStatusEvent` SSE deliveries on demand. |
|
||||
|
||||
All mocks are deterministic: same input always yields the same output. Non-determinism (timestamps, IDs assigned by the suite) is bounded to suite-managed fields that tests do not compare directly — tests use field presence + shape, not value equality, for those fields.
|
||||
|
||||
## Data Validation Rules
|
||||
|
||||
| Data Type | Validation | Invalid Examples | Expected System Behavior |
|
||||
|-----------|-----------|-----------------|------------------------|
|
||||
| Bearer (Authorization header) | Non-empty string starting `Bearer ` | empty header, missing header | `01_api-transport` adds it automatically for authenticated requests; absence triggers a refresh attempt via 401-retry. |
|
||||
| Refresh cookie (response Set-Cookie) | `Secure; HttpOnly; SameSite=Strict` per AC-03 | Missing `HttpOnly` | Test rejects the response (regression — server contract violation). Documented in the suite, asserted by the UI test for defence-in-depth. |
|
||||
| Annotation save body | `{Source, WaypointId, videoTime, mediaId, detections, status}` keys all present (AC-05 / row 23) | missing `Source`, contains `time` instead of `videoTime` | Test FAILS — finding #32 fix regression. |
|
||||
| Waypoint POST body | `{Geopoint:{Lat,Lon,MGRS}, Source, Objective, OrderNum, Height}` shape per `data_parameters.md` (Step 4 fix candidate) | UI's current `{name, latitude, longitude, order}` | Test FAILS once the Step 4 fix lands; pre-fix the test is quarantined (documents the contract drift). |
|
||||
| Enum numeric value on the wire | Member of the spec value set (AC-04 / rows 14-19) | `status: 1` for `Edited` (UI today) instead of `20` (spec) | Test FAILS — exactly the regression that motivated Step 4 AC-04. |
|
||||
| `splitTile` YOLO label | 5 space-separated numeric tokens (AC-39 / row 86) | `"garbage"` (row 87) | Parser surfaces a user-visible error; does NOT silently swallow. Test asserts the error path. |
|
||||
| Numeric form input | Non-empty, parseable, in range (AC-26 / rows 66-67) | empty string, non-numeric, out-of-range | Validation error shown; no PUT fires. |
|
||||
| File upload | ≤ 500 MB (E9 / AC-10 / row 39) | 501 MB | HTTP 413; UI surfaces a user-visible i18n error; no `alert()`. |
|
||||
| i18n key set | `keys(en.json) == keys(ua.json)` (AC-12 / row 45) | UA missing a key present in EN | Static check FAILS. |
|
||||
|
||||
## Open Items For Phase 3 Validation
|
||||
|
||||
- **Enum spec numeric values** (AC-04): **resolved at Phase 3.** Snapshot committed at `_docs/00_problem/input_data/enum_spec_snapshot.json` per `../_docs/00_database_schema.md` (authoritative). `AnnotationStatus`, `MediaStatus`, `Affiliation`, `AnnotationSource` have pinned numerics from the schema. `CombatReadiness` + `MediaType` carry a `verification_pending: true` flag because the schema doesn't pin numerics on those — Step 4 .NET-service inspection lifts the flag (or reorders if the inferred sequential mapping is wrong). UI drift (5 enums) is pinned in the snapshot's `ui_drift_summary` for Step 4 to consume.
|
||||
- **Phase B / target ACs** (AC-11 bundle gate, AC-18 browser-list, AC-24 SSE refresh, AC-25 async-video path, AC-40 tile-zoom UX): the rows are written but the consumer-side behavior does not exist today. Phase 3 will surface these to the user for: (a) downgrade to documentary, (b) quarantine, or (c) accept as gating the day the feature lands.
|
||||
- **Waypoint POST shape** (`data_parameters.md` finding #20): the contract pin is the suite spec, but the UI's current shape is wrong. Tests assert against the contract. Pre-fix the test is quarantined; the Step 4 fix lands together with un-quarantining.
|
||||
- **AC-37 backend ordering**: the class-hotkey contract depends on the `annotations/` service returning classes in `[0..N-1, 20..20+N-1, 40..40+N-1]`. If the seed reveals a different shape, AC-37 row 79 will fail; the fix may need to land server-side or the UI may need a client-side resort. Phase 3 will surface this gap.
|
||||
- **No `Reference File` rows are needed today** — every `Reference File` cell in `results_report.md` is `N/A`. If Phase 2 reveals a need (e.g. for a complex SSE payload sequence), the reference file lands in `_docs/00_problem/input_data/expected_results/` and the row is updated.
|
||||
@@ -0,0 +1,165 @@
|
||||
# Traceability Matrix
|
||||
|
||||
Maps every acceptance criterion and every restriction in `_docs/00_problem/` to the test scenarios that verify it (this directory) and the expected-result row in `_docs/00_problem/input_data/expected_results/results_report.md` that provides the quantifiable observable. Quarantined tests are marked `[Q]` — they assert against a Phase B target feature or a Step 4 fix that has not landed; they activate the day the implementation ships.
|
||||
|
||||
## Acceptance Criteria Coverage
|
||||
|
||||
| AC ID | Acceptance Criterion (short) | Tests | results_report rows | Coverage |
|
||||
|-------|------------------------------|-------|---------------------|----------|
|
||||
| AC-01 | `credentials:'include'` on every authenticated fetch | FT-P-01 [Q for bootstrap], FT-P-02, NFT-PERF-02, NFT-SEC-04, NFT-RES-01, NFT-RES-08 | 01, 02, 03 | Covered |
|
||||
| AC-02 | Bearer never written to client storage | NFT-SEC-01 | 04 | Covered |
|
||||
| AC-03 | Refresh cookie `Secure HttpOnly SameSite=Strict` | NFT-SEC-02, NFT-SEC-03 | 05, 06, 07 | Covered |
|
||||
| AC-04 | Numeric enums match suite spec | FT-P-04, FT-P-05, FT-P-06 | 14, 15, 16, 17, 18, 19 | Covered (`enum_spec_snapshot.json` committed — Phase 3 gate resolved) |
|
||||
| AC-05 | Annotation save endpoint + required body fields | FT-P-07, FT-P-08 | 22, 23 | Covered |
|
||||
| AC-06 | Selected-flight persistence path | FT-P-16, FT-P-17 | 32, 33 | Covered |
|
||||
| AC-07 | Bulk-validate works | FT-P-20, FT-P-21, NFT-PERF-07 | 36, 37 | Covered |
|
||||
| AC-08 | Live-GPS SSE per flight | FT-P-18, FT-P-19, NFT-PERF-04, NFT-PERF-05, NFT-RES-10, NFT-RES-LIM-06, NFT-RES-LIM-07 | 34, 35, 97 | Covered |
|
||||
| AC-09 | Annotation-status SSE during page lifetime | FT-P-09, FT-P-10, NFT-PERF-06, NFT-RES-LIM-05 | 24, 25, 97 | Covered |
|
||||
| AC-10 | Upload size cap 500 MB + UI error path | FT-N-06, NFT-RES-07, NFT-RES-LIM-02 | 38, 39 | Covered |
|
||||
| AC-11 | Initial JS bundle ≤ 2 MB | NFT-PERF-01, NFT-RES-LIM-01 | 40 | Covered (documentary — no CI gate today) |
|
||||
| AC-12 | i18n key parity en ↔ ua | FT-P-22, FT-P-23 | 45, 46 | Covered |
|
||||
| AC-13 | i18n detector + persistence | FT-P-24 [Q], FT-P-25 [Q] | 47, 48 | Covered (quarantined — Step 4 fix) |
|
||||
| AC-14 | Destructive actions require ConfirmDialog + alert() forbidden | FT-P-26, FT-P-27, FT-N-07, NFT-SEC-07, NFT-SEC-08 | 49, 50, 51 | Covered |
|
||||
| AC-15 | ConfirmDialog a11y | FT-P-28, FT-P-29, FT-N-08 | 52, 53, 54 | Covered |
|
||||
| AC-16 | Header flight dropdown a11y | FT-P-30, FT-P-31, FT-N-09 | 55, 56, 57 | Covered |
|
||||
| AC-17 | ProtectedRoute spinner a11y + timeout | FT-P-32, FT-P-33 [Q], NFT-RES-04 [Q] | 58, 59 | Covered (quarantined for timeout) |
|
||||
| AC-18 | Browser support — Chromium + Firefox latest 2 | FT-P-34, NFT-PERF-10 | 60, 98 | Covered (manual smoke, no automated gate today) |
|
||||
| AC-19 | Mobile / desktop breakpoint variants | FT-P-35, FT-P-36 | 61, 62 | Covered |
|
||||
| AC-20 | OpenWeatherMap key not in source | NFT-SEC-09 [Q for source until Step 4] | 63 | Covered (quarantined for source check) |
|
||||
| AC-21 | UserSettings panel-width persistence | FT-P-37 [Q], FT-P-38 [Q], NFT-PERF-08 [Q] | 64, 65 | Covered (quarantined) |
|
||||
| AC-22 | RBAC client-side route gates | FT-N-03 [Q], FT-N-04, FT-N-05 [Q], NFT-SEC-05 [Q], NFT-SEC-06 [Q], NFT-RES-08 | 08, 09, 10 | Covered (quarantined for `/admin` + `/settings` gates) |
|
||||
| AC-23 | Auth refresh transparency | FT-P-02, FT-P-03, NFT-PERF-02, NFT-RES-01 | 11, 12 | Covered |
|
||||
| AC-24 | SSE bearer-rotation reconnect | NFT-PERF-03 [Q], NFT-RES-02 [Q], NFT-RES-10 | 13, 97 | Covered (quarantined — Step 8 hardening) |
|
||||
| AC-25 | Detect endpoint correctness (sync + async) | FT-P-11, FT-P-12 [Q], FT-P-13 [Q] | 26, 27, 28 | Covered (async path quarantined — F7 target) |
|
||||
| AC-26 | Numeric input hygiene | FT-N-11 [Q], FT-N-12 [Q] | 66, 67 | Covered (quarantined — Step 4 fix) |
|
||||
| AC-27 | Save error surfacing in settings | FT-N-13 [Q], FT-N-14 [Q], NFT-PERF-09 [Q], NFT-RES-05 [Q], NFT-RES-06 [Q] | 68, 69 | Covered (quarantined — Step 4 fix) |
|
||||
| AC-28 | Annotation overlay time window `[-50, +150] ms` | FT-P-14, FT-P-15, FT-N-01, FT-N-02 | 29, 30, 31 | Covered |
|
||||
| AC-29 | `mediaType` is typed (no magic literals) | FT-N-15 | 20, 21 | Covered |
|
||||
| AC-30 | Class delete confirmation | FT-P-26, FT-N-07, NFT-SEC-08 | 49 | Covered (overlaps AC-14 row 49) |
|
||||
| AC-31 | `mission-planner/` not in production bundle | NFT-RES-LIM-04 | 41 | Covered |
|
||||
| AC-32 | CI image tag + OCI labels | NFT-RES-LIM-11, NFT-RES-LIM-12, NFT-RES-LIM-13 | 70, 71, 72 | Covered |
|
||||
| AC-33 | Production runtime `nginx:alpine` only | NFT-RES-LIM-03 | 42 | Covered |
|
||||
| AC-34 | nginx routes 9 services with prefix stripping | NFT-RES-LIM-09, NFT-RES-LIM-10 | 43, 44 | Covered |
|
||||
| AC-35 | Manual bbox draw on CanvasEditor | FT-P-39 | 73 | Covered |
|
||||
| AC-36 | 8-handle resize + Ctrl-multi-select + Ctrl-wheel zoom + Ctrl-drag pan | FT-P-40, FT-P-41, FT-P-42, FT-P-43 | 74, 75, 76, 77 | Covered |
|
||||
| AC-37 | Class picker — load + hotkey + click + fallback | FT-P-44, FT-P-45, FT-P-46, FT-P-47 | 78, 79, 80, 81 | Covered (pending backend ordering check — Phase 3 gate) |
|
||||
| AC-38 | PhotoMode switcher | FT-P-48, FT-P-49, FT-P-50 | 82, 83, 84 | Covered |
|
||||
| AC-39 | Tile-splitting endpoint + parser | FT-P-51 [Q], FT-P-52, FT-P-53, FT-N-10 | 85, 86, 87, 88 | Covered (split surface quarantined) |
|
||||
| AC-40 | Tile-zoom auto-zoom + indicator | FT-P-54 [Q], FT-P-55 [Q] | 89, 90 | Covered (quarantined — UX missing today) |
|
||||
| AC-N1 | No collaborative-edit semantics | NFT-SEC-14 | 91 | Covered |
|
||||
| AC-N2 | No in-browser ML | NFT-SEC-10 | 92 | Covered |
|
||||
| AC-N3 | No offline mode | NFT-RES-03, NFT-SEC-12 | 93 | Covered |
|
||||
| AC-N4 | No response-signature library | NFT-SEC-11 | 94 | Covered |
|
||||
| AC-N5 | Dropped legacy features (Sound Detections, Drone Maintenance) | NFT-SEC-13 | 95 | Covered |
|
||||
|
||||
## Restrictions Coverage
|
||||
|
||||
| RID | Restriction (short) | Tests / Mechanism | Coverage |
|
||||
|-----|---------------------|-------------------|----------|
|
||||
| H1 | ARM64-only production image | NFT-RES-LIM-03 (image base check); the build pipeline produces ARM64 only — meta-config | Covered |
|
||||
| H2 | Edge-device deployment target | NFT-PERF-10, NFT-RES-LIM-08 | Covered (documentary) |
|
||||
| H3 | No GPU expectation in UI image | environment.md (no GPU in test rig); NFT-SEC-10 (no ML libs) — together they verify the constraint | Covered (by composition) |
|
||||
| H4 | HTML5 video + canvas + EventSource on Chromium / Firefox latest 2 | FT-P-34 | Covered |
|
||||
| S1 | TypeScript strict mode | STC-S1: static read of `tsconfig.json` for `"strict": true` (planned static check — added by Phase 3 if accepted) | NOT COVERED — Phase 3 to add |
|
||||
| S2 | React 19 | STC-S2: `package.json` dep version pin | NOT COVERED — Phase 3 to add |
|
||||
| S3 | Vite 6 | STC-S3: `package.json` dep version pin | NOT COVERED — Phase 3 to add |
|
||||
| S4 | Bun 1.3.11 | STC-S4: `package.json` `packageManager` field + Dockerfile base image pin | NOT COVERED — Phase 3 to add |
|
||||
| S5 | Static-bundle output only (no Node in prod image) | NFT-RES-LIM-03 | Covered |
|
||||
| S6 | REST + SSE only (no WebSocket / GraphQL / gRPC-Web) | STC-S6: dep scan for `ws`, `socket.io`, `graphql`, `apollo`, `grpc-web` (planned) | NOT COVERED — Phase 3 to add |
|
||||
| S7 | Two React Contexts only (no Redux / Zustand / TanStack Query) | STC-S7: dep scan for `redux`, `zustand`, `@reduxjs/.*`, `@tanstack/.*` | NOT COVERED — Phase 3 to add |
|
||||
| S8 | Tailwind 4 + `az-*` design tokens | STC-S8: dep version pin + presence of token CSS vars | NOT COVERED — Phase 3 to add |
|
||||
| S9 | `leaflet@1.9.4` + `react-leaflet@5` + `leaflet-draw` + `leaflet-polylinedecorator` | STC-S9: `package.json` version pin set | NOT COVERED — Phase 3 to add |
|
||||
| S10 | `chart.js@4` + `react-chartjs-2@4` | STC-S10 | NOT COVERED — Phase 3 to add |
|
||||
| S11 | `@hello-pangea/dnd@18` | STC-S11 | NOT COVERED — Phase 3 to add |
|
||||
| S12 | `i18next` + `react-i18next` with EN + UA bundles only | FT-P-22, FT-P-23 + STC-S12 (no other locale bundle files) | Partially Covered |
|
||||
| S13 | No client-side persistence library | NFT-SEC-01 + STC-S13 (dep scan for `localforage`, `idb`, `dexie`) | Partially Covered |
|
||||
| S14 | No test framework configured today | META — these tests' very existence supersedes this restriction; resolved at Step 5 (Decompose Tests) per `acceptance_criteria.md` AC-14 / S14 note | N/A — meta |
|
||||
| E1 | Air-gap-friendly bundle | NFT-RES-03 (offline boot) + external-dep stubs in environment.md | Partially Covered |
|
||||
| E2 | nginx strips `/api/<service>/` per service | NFT-RES-LIM-09, NFT-RES-LIM-10 | Covered |
|
||||
| E3 | `Secure HttpOnly SameSite=Strict` refresh cookie | NFT-SEC-03 | Covered |
|
||||
| E4 | Vite dev proxy at `/api → http://localhost:8080` | dev-only; not testable in production runtime | NOT COVERED — meta-config (Phase 3 to confirm) |
|
||||
| E5 | `AZAION_REVISION` stamped at build | NFT-RES-LIM-13 | Covered |
|
||||
| E6 | OCI image labels | NFT-RES-LIM-12 | Covered |
|
||||
| E7 | Image registry + tag scheme | NFT-RES-LIM-11 | Covered |
|
||||
| E8 | Branch triggers (`dev` / `stage` / `main`) | STC-E8: parse `.woodpecker/build-arm.yml` triggers (planned) | NOT COVERED — Phase 3 to add |
|
||||
| E9 | `client_max_body_size 500M` | NFT-RES-LIM-02 | Covered |
|
||||
| E10 | OpenWeatherMap direct-from-browser today | NFT-SEC-09 (key check) + environment.md `owm-stub` (E2E isolation) | Covered |
|
||||
| O1 | Bilingual UI mandatory | FT-P-22, FT-P-23 | Covered |
|
||||
| O2 | Bearer never in localStorage / sessionStorage | NFT-SEC-01 | Covered |
|
||||
| O3 | `credentials:'include'` on every authenticated fetch | NFT-SEC-04 | Covered |
|
||||
| O4 | RBAC is server-enforced (UI must NOT trust `AuthUser.role`) | meta-design + FT-N-04 (unauth → /login regardless of any client claim); STC-O4 (no `if (user.role === 'admin')` gating sensitive data, only UI hide/show) | Partially Covered — Phase 3 may add the static gate-pattern lint |
|
||||
| O5 | Refresh cookie attributes | NFT-SEC-03 | Covered |
|
||||
| O6 | No hardcoded credentials | NFT-SEC-09 | Covered |
|
||||
| O7 | Spec is source of truth for numeric enums | FT-P-04, FT-P-05, FT-P-06 | Covered |
|
||||
| O8 | Persist what you type (panel widths) | FT-P-37 [Q], FT-P-38 [Q] | Covered (quarantined) |
|
||||
| O9 | Admin can edit existing detection classes (P12) | NOT COVERED — feature missing today (`acceptance_criteria.md` notes P12 violation; PATCH endpoint to re-introduce in Phase B) | NOT COVERED — Phase B target |
|
||||
| O10 | Destructive actions require ConfirmDialog | NFT-SEC-08, FT-P-26, FT-P-27, FT-N-07 | Covered |
|
||||
| O11 | No SSR / RSC | NFT-RES-LIM-03 (no Node in image) + STC-O11 (no `react-dom/server` import) | Partially Covered |
|
||||
| O12 | `mission-planner/` not compiled by production Vite build | NFT-RES-LIM-04 | Covered |
|
||||
| O13 | Bundle size budget ≤ ~2 MB gzipped initial JS | NFT-PERF-01, NFT-RES-LIM-01 | Covered (target — no CI gate today) |
|
||||
| O14 | No CI test step today | META — resolved at Step 5 (Decompose Tests) | N/A — meta |
|
||||
| O15 | No vuln scan / SBOM / image signing | NOT COVERED — Step 6 / security_approach surface; Phase B addition | NOT COVERED |
|
||||
|
||||
## Coverage Summary
|
||||
|
||||
| Category | Total Items | Covered | Partially Covered | Not Covered | N/A (meta) | Coverage % (Covered+Partial) |
|
||||
|----------|-------------|---------|-------------------|-------------|-----------|--------------------|
|
||||
| Acceptance Criteria | 40 | 40 | 0 | 0 | 0 | 100% (24 fully ungated, 16 with Phase 3 quarantine markers) |
|
||||
| Anti-Criteria | 5 | 5 | 0 | 0 | 0 | 100% |
|
||||
| Restrictions | 41 | 17 | 8 | 13 | 3 | 61% |
|
||||
| **Total** | **86** | **62** | **8** | **13** | **3** | **81%** |
|
||||
|
||||
Acceptance criterion coverage exceeds the 75 % template threshold. Restriction coverage is short of 75 % because most of the un-covered restrictions are dependency-version pins (S1-S11) for which a single static check pass (planned `STC-S*` family) would lift them to Covered without changing the SPA's observable behavior.
|
||||
|
||||
## Uncovered Items Analysis
|
||||
|
||||
| Item | Reason Not Covered | Risk | Mitigation |
|
||||
|------|-------------------|------|-----------|
|
||||
| S1-S11 (TS strict, React/Vite/Bun version pins, Tailwind, Leaflet, Chart.js, DnD) | Dependency-version restrictions need a static `package.json` / `tsconfig.json` parser pass; not authored in this phase | Drift between pinned and installed versions (e.g., transitive resolution); accidental upgrade in a refactor breaking ADRs (ADR-001 …) | Phase 3 to confirm adding the `STC-S*` family; otherwise Step 4 / Step 8 may add them as part of the testability fix |
|
||||
| S12, S13 partials | `STC-S12` (no other locale bundles) and `STC-S13` (no IndexedDB / localForage / Dexie deps) need explicit dep scans | Low — currently aligned per `package.json`; risk only on dep additions | Phase 3 promotion to a single static dep-scan job (run alongside the dep-license lint) |
|
||||
| E4, E8 | Dev-only proxy and pipeline branch triggers are not consumer-observable from a production build | None today; future risk if the proxy diverges from the prod nginx | Document-only; Phase 3 confirms |
|
||||
| O4 partial (RBAC trust pattern) | No lint rule today; the design intent is captured but not asserted in code | UI accidentally gates sensitive data on a client claim | Phase 3 to add an `STC-O4` lint that bans `if (user.role === 'admin') { /* reveal data */ }` patterns; FT-N-04 already locks the unauth path |
|
||||
| O9 (admin can edit classes — P12) | The feature does not exist today (only add + delete); cannot test absence of a regression | Functionality missing relative to spec | Phase B feature cycle will add `PATCH /api/admin/classes/{id}` plus FT-P-XX in the cycle that ships it; AC-37 / AC-30 already enforce the surrounding contract |
|
||||
| O11 partial | NFT-RES-LIM-03 confirms no Node binary in the image; an explicit "no `react-dom/server` import" lint is missing | Could regress to SSR by accident on a refactor; the image base check would still pass | Phase 3 confirms `STC-O11` |
|
||||
| O15 (vuln scan / SBOM / signing) | Pipeline does not emit any of these today | Supply-chain risk | Addressed at Step 6 / `security_approach.md`; outside the test-spec scope |
|
||||
| AC-11, AC-18, AC-24, AC-40, AC-25 async path | Phase B / target features with quarantined tests | Tests do not gate today — risk = the feature ships without the assertion being un-quarantined | Phase 3 chooses: keep quarantined (gates the day the feature ships) OR downgrade to documentary; recommendation: keep quarantined |
|
||||
| AC-04 enum spec numeric values for `MediaStatus` / `Affiliation` / `CombatReadiness` | The exact spec values are not pinned in `enum_spec_snapshot.json` yet | Tests use symbolic comparison and may silently match a wrong UI state | Phase 3 to require population of the snapshot before AC-04 tests gate CI; recommendation: BLOCK Step 4 until the snapshot is committed |
|
||||
| AC-37 backend ordering | The class-hotkey contract requires `[0..N-1, 20..20+N-1, 40..40+N-1]` ordering from the suite; not yet verified | Hotkey test fails at integration; ambiguous responsibility | Phase 3 to surface; fix can land server-side or via a client-side resort, depending on the verification result |
|
||||
|
||||
## Quarantine List (running)
|
||||
|
||||
The following 18 tests assert against a Phase B target or a Step 4 fix and are quarantined until the implementation lands. Phase 3 will decide their disposition.
|
||||
|
||||
| Test | Reason | Activates when |
|
||||
|------|--------|---------------|
|
||||
| FT-P-01 (bootstrap part) | Bootstrap refresh missing `credentials:'include'` per finding | Step 4 fix |
|
||||
| FT-P-12, FT-P-13 | Async video detect (F7) not wired | Phase B feature cycle |
|
||||
| FT-P-24, FT-P-25 | i18n detector + persistence missing | Step 4 fix |
|
||||
| FT-P-33 (timeout) | ProtectedRoute timeout missing | Step 4 fix |
|
||||
| FT-P-37, FT-P-38 | Panel-width writer missing (`useResizablePanel`) | Step 4 fix |
|
||||
| FT-P-51 | Split surface not on dataset page today | Phase B |
|
||||
| FT-P-54, FT-P-55 | Tile-zoom UX missing (finding #24) | Phase B |
|
||||
| FT-N-03, FT-N-05 | `/admin` and `/settings` role-gates missing | Step 4 / Step 8 |
|
||||
| FT-N-11, FT-N-12, FT-N-13, FT-N-14 | Settings form hygiene fixes missing | Step 4 |
|
||||
| NFT-PERF-03 / NFT-RES-02 | SSE refresh-rotation reconnect missing | Step 8 hardening |
|
||||
| NFT-PERF-08 / NFT-PERF-09 | Tied to FT-P-37 / FT-N-13 quarantines | per above |
|
||||
| NFT-SEC-05, NFT-SEC-06 | Tied to FT-N-03, FT-N-05 | per above |
|
||||
| NFT-SEC-09 (source check) | OpenWeatherMap key still in source today | Step 4 fix |
|
||||
| NFT-RES-04 | Tied to FT-P-33 | per above |
|
||||
|
||||
## Phase 3 (Data Validation Gate) — Open Items to Resolve
|
||||
|
||||
### Resolved in Phase 3
|
||||
|
||||
1. ~~**`enum_spec_snapshot.json`** — populate from the suite spec before AC-04 tests gate CI.~~ → **Resolved:** snapshot committed at `_docs/00_problem/input_data/enum_spec_snapshot.json`. `verification_pending: true` markers remain for `CombatReadiness` and `MediaType` (numeric ordering inferred from schema member-listing); Step 4 .NET-service inspection lifts those.
|
||||
2. ~~**NFT-RES-09** — no `results_report.md` row binding.~~ → **Resolved:** row 96 added (tainted-canvas fallback observable).
|
||||
3. ~~**NFT-RES-10** — no `results_report.md` row binding.~~ → **Resolved:** row 97 added (SSE server-disconnect observable; ≤ 10 s indicator-or-reconnect; reconnect attempts ≤ 1 in window).
|
||||
4. ~~**NFT-PERF-10** — FCP baseline has no `results_report.md` row.~~ → **Resolved:** row 98 added (`FCP ≤ 3 000 ms` on warm-cache navigation to `/flights`, headless Chromium, 2 vCPU / 4 GB edge profile).
|
||||
|
||||
### Still open (carry forward to Step 4 / runner)
|
||||
|
||||
5. **AC-37 backend ordering** — verify the `annotations/` service response shape and either confirm matches or schedule a fix on the appropriate side.
|
||||
6. **STC family** — confirm adding the `STC-S*` / `STC-O4` / `STC-O11` static-check IDs to lift the restriction coverage above 75 %.
|
||||
7. **Quarantine disposition** — accept the quarantine list above; decide whether quarantined tests gate CI today (recommended: no, but they are picked up automatically the day the feature lands).
|
||||
8. **AC-04 UI enum drift in `src/types/index.ts`** — tests will FAIL until the Step 4 fix lands per `acceptance_criteria.md`; quarantine until Step 4 OR run them and use the failure as the gate to schedule Step 4. The drift list is pinned in `enum_spec_snapshot.json` → `ui_drift_summary` (5 enums).
|
||||
9. **Parent-suite doc fixes (leftover)** — `../_docs/01_annotations.md` line 208 and `../_docs/09_dataset_explorer.md` line 165 show stale `affiliation: 2 // Hostile` examples; should be 20 per `00_database_schema.md`. Record as a leftover in `_docs/_process_leftovers/` when raised against the parent suite.
|
||||
Reference in New Issue
Block a user