ui/_docs/02_document/diagrams/components.md

# 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 &amp; Context<br/>Header · HelpModal · ConfirmDialog<br/>DetectionClasses · FlightContext]

  Login[04 — Login]
  Flights[05 — Flights &amp; Mission Planning<br/>incl. GPS-Denied sub-page<br/>+ Test Mode &#40;tlog+video→SITL→onboard&#41;]
  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).