docs: define distributed Mission Core topology

2026-07-24 19:40:59 +03:00
parent b790f29d59
commit 359f0d1d39
5 changed files with 285 additions and 5 deletions
@@ -62,6 +62,11 @@ reports easy to misuse.
    Micro XRCE-DDS Agent's UDP wildcard bind is acceptable only inside that
    boundary; no S0 listener may be reachable from the worker LAN or Windows
    host network.
+17. Product packaging, simulation-worker placement, the future onboard Edge
+    Agent, local-first field evidence and offline synchronization follow
+    [ADR 0016](0016-distributed-product-edge-and-worker-topology.md). Native
+    Gazebo GUI is worker-local diagnostics; the operator product remains the
+    browser Control Station over canonical state.

 ## Consequences

@@ -0,0 +1,172 @@
+# ADR 0016: Distributed web product, edge runtime and worker topology
+
+## Status
+
+Accepted for architecture on 2026-07-24. It defines placement and packaging,
+not field actuator acceptance. The current Windows/WSL2 simulation worker is a
+laboratory deployment of this topology; the future onboard Edge Agent and its
+physical command authority remain separate gates.
+
+## Context
+
+Mission Core has a React Control Station, a Python control plane, native
+simulation providers and future onboard components. Treating all of them as one
+application creates two misleading alternatives:
+
+1. embed Gazebo, PX4, ROS 2 and Nav2 inside the browser; or
+2. make Mission Core a Windows/macOS/Linux desktop executable.
+
+Neither matches the system.
+
+Gazebo Harmonic has a native Qt GUI, PX4 SITL and ROS 2 are Linux processes, and
+Nav2 is a runtime graph. A browser cannot own those processes or preserve their
+state when its tab closes. Conversely, a field vehicle must keep bounded
+autonomy, safety behavior and durable local evidence when the operator browser,
+WAN or control centre is unavailable.
+
+The operator still needs one coherent product: plan a mission, inspect a live
+or historical vehicle, run a simulation, compare outcomes and review evidence
+from a browser on macOS, Windows, Linux or a tablet.
+
+## Decision
+
+### Product form
+
+1. The primary Mission Core operator product remains the React Control Station
+   served as static web assets by a Mission Core Gateway/API. It is not a
+   platform-specific desktop executable.
+2. An optional PWA, kiosk shell or thin Tauri/Electron wrapper may package the
+   same web assets for offline distribution. Such a wrapper is not a second
+   product, does not own authority and is not required for the core topology.
+3. Native provider GUIs are diagnostic tools. Gazebo GUI, QGroundControl and
+   similar tools do not become product navigation or a source-of-record.
+
+### Runtime roles
+
+4. Mission Core Control Plane owns users, missions, scenarios, policy,
+   qualification-run identity, authority admission, orchestration, catalogues,
+   comparison and reports.
+5. Simulation Worker is a separately registered Linux execution target. It runs
+   Simulation Orchestrator worker components plus Gazebo, PX4 SITL, ROS 2 and
+   Nav2. Normal product operation is headless. A native Gazebo GUI may attach
+   locally for laboratory diagnosis without becoming the control plane.
+6. Vehicle Edge Agent is a future headless Linux service on the onboard
+   computer or a vehicle-adjacent edge computer. It owns device adapters,
+   bounded local mission state, health, canonical telemetry, local evidence,
+   store-and-forward synchronization and the server-side physical authority
+   boundary accepted for that vehicle.
+7. The flight/rover controller remains a separate PX4 hardware boundary. A
+   browser never talks to PX4 directly.
+8. Observation/perception workers may run onboard, on a nearby edge computer or
+   in a control-centre worker according to latency and bandwidth budgets. Their
+   placement does not change canonical contracts or authority ownership.
+
+### Browser presentation
+
+9. The browser receives bounded canonical state, events, metrics, maps,
+   trajectories, perception layers and optional media previews. It renders
+   interactive product views through browser-native components such as Rerun
+   Web Viewer, WebGL/canvas and ordinary React controls.
+10. A Polygon run view shows the canonical rover pose, route, planned/factual
+    trajectory, footprint, safety state and derived scene. It does not require
+    remote pixels from Gazebo GUI.
+11. Full native Gazebo rendering may be exposed only as an explicitly
+    diagnostic remote-desktop/WebRTC capability. It is optional, isolated from
+    command authority and never the only representation of run state.
+
+### Connectivity and evidence
+
+12. Field safety and bounded mission execution cannot depend on a browser tab,
+    a WAN connection or continuous connectivity to a central Mission Core
+    instance.
+13. The Edge Agent persists raw/source evidence and the canonical event/state
+    journal locally before optional upload. High-volume sensor data remains on
+    vehicle storage until retention and connectivity policy permits transfer.
+14. Connected mode sends bounded live telemetry, health, decisions and previews
+    outward. Disconnected mode continues the locally admitted policy, applies
+    the accepted loss/failsafe behavior and queues evidence for later sync.
+15. Reconnection performs idempotent, digest-bound store-and-forward
+    synchronization. The central archive never rewrites the vehicle's original
+    run identity or presents a partial upload as complete.
+16. A field kit may host the Gateway/API and React assets locally on an operator
+    laptop or edge hub. The same deployment can later synchronize with a
+    control-centre instance; no Internet connection is required to render the
+    UI.
+
+### Authority path
+
+17. The authority path is always:
+
+    ```text
+    Browser intent
+      -> Mission Core API/policy
+      -> Orchestrator or Vehicle Edge Agent
+      -> allowlisted provider/device adapter
+      -> PX4 boundary
+    ```
+
+18. Losing the browser affects presentation only. Losing upstream connectivity
+    invokes the locally accepted watchdog/failsafe policy; it does not grant a
+    new command source.
+
+## Supported deployment topologies
+
+### Laboratory simulation
+
+```text
+Operator browser
+  -> Mission Core Gateway/API
+  -> Simulation Orchestrator
+  -> registered Linux/WSL2 GPU worker
+  -> Gazebo + PX4 SITL + ROS 2 + Nav2
+  -> local source evidence + canonical/derived streams
+```
+
+The current `MissionCore-Sim` WSL2 distribution on the D drive is this
+topology's first qualified worker. Its native Gazebo window is local diagnostics;
+the product view remains browser-native.
+
+### Connected field vehicle
+
+```text
+Operator browser/control centre
+  -> Mission Core Gateway/API
+  <-> Vehicle Edge Agent on onboard Linux
+  -> PX4 hardware boundary
+  -> sensors and actuators
+```
+
+Bounded telemetry and previews can be live. Raw/high-volume evidence is written
+locally first and uploaded according to policy.
+
+### Disconnected field vehicle and later review
+
+```text
+Approved local mission + Edge Agent + PX4
+  -> local execution/failsafe
+  -> local append-only evidence
+  -> later digest-bound synchronization
+  -> browser history/replay/report
+```
+
+The historical/replay product is therefore not a fallback or a separate
+application. It is the review side of the same distributed system.
+
+## Consequences
+
+- Operators use one browser product across simulation, field monitoring,
+  planning, archive and comparison.
+- Native Linux dependencies do not force a Windows-only or macOS-only Mission
+  Core executable.
+- Gazebo is not installed on field vehicles unless a specific lab/HIL profile
+  requires it.
+- The product needs explicit Gateway, worker-registration, Edge Agent,
+  store-and-forward and capability-discovery contracts.
+- Live 3D is a canonical-state presentation problem, not a remote-Gazebo-window
+  dependency.
+- A thin desktop wrapper remains possible for distribution or kiosk use, but it
+  cannot widen authority or hide missing offline server components.
+- Field hardware, storage budgets, network-loss policy, physical e-stop,
+  operator takeover and real actuator authority still require separate
+  acceptance.
+