Update autodev state, architecture documentation, and glossary terms

Transitioned the autodev state to phase 21, reflecting the completion of Step 5 and the drafting of Step 6 epics. Revised the architecture documentation to clarify the roles of the Tile Manager and its components, ensuring accurate representation of the system's operational flow. Updated glossary entries for Flight State and Operator to incorporate recent changes and enhance clarity on component interactions and responsibilities.
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-10 00:21:34 +03:00
parent 723f574b14
commit 64542d32fc
52 changed files with 8789 additions and 88 deletions
@@ -0,0 +1,221 @@
<mxfile host="app.diagrams.net" modified="2026-05-09T00:00:00.000Z" agent="autodev/plan-step3" version="22.0.0">
<diagram id="components" name="Components">
<mxGraphModel dx="1700" dy="1100" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1700" pageHeight="1200" math="0" shadow="0">
<root>
<mxCell id="0" />
<mxCell id="1" parent="0" />
<!-- Group: External systems -->
<mxCell id="ext_satprov" value="[[ satellite-provider ]]&#10;(parent suite, .NET 8 REST)" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;dashed=1;align=center;" vertex="1" parent="1">
<mxGeometry x="40" y="40" width="220" height="60" as="geometry" />
</mxCell>
<mxCell id="ext_navcam" value="[[ Nav camera ]]&#10;(adti20, 3 Hz, 5472x3648)" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;dashed=1;align=center;" vertex="1" parent="1">
<mxGeometry x="280" y="40" width="220" height="60" as="geometry" />
</mxCell>
<mxCell id="ext_opws" value="[[ Operator workstation ]]" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;dashed=1;align=center;" vertex="1" parent="1">
<mxGeometry x="520" y="40" width="220" height="60" as="geometry" />
</mxCell>
<mxCell id="ext_ap" value="[[ ArduPilot Plane FC ]]&#10;(MAVLink 2.0 signed)" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;dashed=1;align=center;" vertex="1" parent="1">
<mxGeometry x="1440" y="40" width="220" height="60" as="geometry" />
</mxCell>
<mxCell id="ext_inav" value="[[ iNav FC ]]&#10;(MSP2, unsigned)" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;dashed=1;align=center;" vertex="1" parent="1">
<mxGeometry x="1440" y="120" width="220" height="60" as="geometry" />
</mxCell>
<mxCell id="ext_qgc" value="[[ QGroundControl GCS ]]&#10;(MAVLink 2.0, 1-2 Hz)" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;dashed=1;align=center;" vertex="1" parent="1">
<mxGeometry x="1440" y="200" width="220" height="60" as="geometry" />
</mxCell>
<!-- Pre-flight / operator components (orange) -->
<mxCell id="c12" value="C12 Operator Tooling&#10;(workstation; CLI)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;align=center;" vertex="1" parent="1">
<mxGeometry x="520" y="160" width="220" height="60" as="geometry" />
</mxCell>
<mxCell id="c10" value="C10 Cache Provisioner&#10;(companion, offline)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;align=center;" vertex="1" parent="1">
<mxGeometry x="280" y="160" width="220" height="60" as="geometry" />
</mxCell>
<!-- Per-frame onboard pipeline (blue) -->
<mxCell id="c1" value="C1 VIO&#10;(VioStrategy)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;align=center;" vertex="1" parent="1">
<mxGeometry x="280" y="320" width="160" height="60" as="geometry" />
</mxCell>
<mxCell id="c2" value="C2 VPR&#10;(VprStrategy)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;align=center;" vertex="1" parent="1">
<mxGeometry x="460" y="320" width="160" height="60" as="geometry" />
</mxCell>
<mxCell id="c25" value="C2.5 Re-rank&#10;(inlier-count)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;align=center;" vertex="1" parent="1">
<mxGeometry x="640" y="320" width="160" height="60" as="geometry" />
</mxCell>
<mxCell id="c3" value="C3 Matcher&#10;(DISK+LightGlue)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;align=center;" vertex="1" parent="1">
<mxGeometry x="820" y="320" width="160" height="60" as="geometry" />
</mxCell>
<mxCell id="c35" value="C3.5 AdHoP&#10;(conditional)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;align=center;" vertex="1" parent="1">
<mxGeometry x="1000" y="320" width="160" height="60" as="geometry" />
</mxCell>
<mxCell id="c4" value="C4 Pose&#10;(OpenCV+GTSAM)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;align=center;" vertex="1" parent="1">
<mxGeometry x="1180" y="320" width="160" height="60" as="geometry" />
</mxCell>
<mxCell id="c5" value="C5 State Estimator&#10;(GTSAM iSAM2)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;align=center;" vertex="1" parent="1">
<mxGeometry x="1180" y="440" width="180" height="60" as="geometry" />
</mxCell>
<mxCell id="c8" value="C8 FC Adapter&#10;(pymavlink + YAMSPy)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;align=center;" vertex="1" parent="1">
<mxGeometry x="1440" y="440" width="220" height="60" as="geometry" />
</mxCell>
<!-- Cross-cutting infra (green) -->
<mxCell id="c6" value="C6 Tile Cache + Spatial Index&#10;(Postgres + filesystem + FAISS HNSW)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;align=center;" vertex="1" parent="1">
<mxGeometry x="500" y="540" width="320" height="80" as="geometry" />
</mxCell>
<mxCell id="c7" value="C7 Inference Runtime&#10;(TensorRT 10.3 / ONNX-RT / PyTorch)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;align=center;" vertex="1" parent="1">
<mxGeometry x="40" y="320" width="220" height="120" as="geometry" />
</mxCell>
<mxCell id="c13" value="C13 Flight Data Recorder (FDR)&#10;(per-flight ≤64 GB; AC-NEW-3)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;align=center;" vertex="1" parent="1">
<mxGeometry x="500" y="700" width="320" height="80" as="geometry" />
</mxCell>
<!-- Operator-side enclave (orange) — C11 Tile Manager: separate binary, not loaded airborne -->
<mxCell id="enclave_postland" value="Operator-side enclave (C11 Tile Manager — separate binary; ADR-004 process-level isolation; airborne image excludes this code path; both TileDownloader and TileUploader run only here)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=none;strokeColor=#d79b00;dashed=1;verticalAlign=top;align=left;fontStyle=2;" vertex="1" parent="1">
<mxGeometry x="900" y="700" width="540" height="160" as="geometry" />
</mxCell>
<mxCell id="c11" value="C11 Tile Manager&#10;(TileDownloader + TileUploader)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;align=center;" vertex="1" parent="1">
<mxGeometry x="940" y="740" width="220" height="60" as="geometry" />
</mxCell>
<!-- mock-suite-sat-service is an e2e-test fixture, not a component (ADR-007 reversed 2026-05-09). Not shown on the architecture diagram. -->
<!-- Edges: per-frame pipeline -->
<mxCell id="e_navcam_c1" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1" source="ext_navcam" target="c1">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_navcam_c2" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1" source="ext_navcam" target="c2">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c2_c25" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1" source="c2" target="c25">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c25_c3" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1" source="c25" target="c3">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c3_c35" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1" source="c3" target="c35">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c35_c4" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1" source="c35" target="c4">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c4_c5" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1" source="c4" target="c5">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c1_c5" style="endArrow=classic;html=1;rounded=0;exitX=1;exitY=0.5;" edge="1" parent="1" source="c1" target="c5">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c5_c8" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1" source="c5" target="c8">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c8_ap" style="endArrow=classic;html=1;rounded=0;startArrow=classic;" edge="1" parent="1" source="c8" target="ext_ap">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c8_inav" style="endArrow=classic;html=1;rounded=0;startArrow=classic;" edge="1" parent="1" source="c8" target="ext_inav">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c8_qgc" style="endArrow=classic;html=1;rounded=0;startArrow=classic;" edge="1" parent="1" source="c8" target="ext_qgc">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<!-- Edges: storage + inference -->
<mxCell id="e_c2_c6" style="endArrow=classic;html=1;rounded=0;dashed=1;" edge="1" parent="1" source="c2" target="c6">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c25_c6" style="endArrow=classic;html=1;rounded=0;dashed=1;" edge="1" parent="1" source="c25" target="c6">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c3_c6" style="endArrow=classic;html=1;rounded=0;dashed=1;" edge="1" parent="1" source="c3" target="c6">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c5_c6" value="orthorect F4" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1" source="c5" target="c6">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c7_c1" style="endArrow=classic;html=1;rounded=0;dashed=1;" edge="1" parent="1" source="c7" target="c1">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c7_c2" style="endArrow=classic;html=1;rounded=0;dashed=1;" edge="1" parent="1" source="c7" target="c2">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c7_c25" style="endArrow=classic;html=1;rounded=0;dashed=1;" edge="1" parent="1" source="c7" target="c25">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c7_c3" style="endArrow=classic;html=1;rounded=0;dashed=1;" edge="1" parent="1" source="c7" target="c3">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c7_c35" style="endArrow=classic;html=1;rounded=0;dashed=1;" edge="1" parent="1" source="c7" target="c35">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c7_c4" value="ThermalState" style="endArrow=classic;html=1;rounded=0;dashed=1;" edge="1" parent="1" source="c7" target="c4">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<!-- Edges: pre-flight provisioning F1 -->
<mxCell id="e_opws_c12" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1" source="ext_opws" target="c12">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c12_c11_dl" value="F1 phase 1:&#10;download_tiles_for_area" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1" source="c12" target="c11">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c11_satprov_get" value="GET /api/satellite/tiles&#10;(TLS + service API key)" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1" source="c11" target="ext_satprov">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c11_c6_write" value="write tiles&#10;(source=googlemaps)" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1" source="c11" target="c6">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c12_c10" value="F1 phase 2:&#10;build_cache_artifacts" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1" source="c12" target="c10">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c10_c6" value="read tiles + write FAISS index, manifest" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1" source="c10" target="c6">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c10_c7" value="engine compile" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1" source="c10" target="c7">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<!-- Edges: post-landing F10 (operator-side enclave; same C11 component, TileUploader interface) -->
<mxCell id="e_c11_c6" value="read pending tiles" style="endArrow=classic;html=1;rounded=0;startArrow=classic;" edge="1" parent="1" source="c11" target="c6">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c11_satprov" value="POST /ingest&#10;(D-PROJ-2 planned)" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1" source="c11" target="ext_satprov">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<!-- Edges: FDR cross-cutting (every component logs to C13) -->
<mxCell id="e_c1_c13" style="endArrow=classic;html=1;rounded=0;dashed=1;strokeColor=#82b366;" edge="1" parent="1" source="c1" target="c13">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c5_c13" style="endArrow=classic;html=1;rounded=0;dashed=1;strokeColor=#82b366;" edge="1" parent="1" source="c5" target="c13">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c8_c13" style="endArrow=classic;html=1;rounded=0;dashed=1;strokeColor=#82b366;" edge="1" parent="1" source="c8" target="c13">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c6_c13" style="endArrow=classic;html=1;rounded=0;dashed=1;strokeColor=#82b366;" edge="1" parent="1" source="c6" target="c13">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c7_c13" style="endArrow=classic;html=1;rounded=0;dashed=1;strokeColor=#82b366;" edge="1" parent="1" source="c7" target="c13">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<!-- FC IMU/attitude inbound to C8 -> C1 + C5 -->
<mxCell id="e_ap_c8_in" style="endArrow=classic;html=1;rounded=0;dashed=1;" edge="1" parent="1" source="ext_ap" target="c8">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_inav_c8_in" style="endArrow=classic;html=1;rounded=0;dashed=1;" edge="1" parent="1" source="ext_inav" target="c8">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c8_c1" value="ImuWindow" style="endArrow=classic;html=1;rounded=0;dashed=1;" edge="1" parent="1" source="c8" target="c1">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_c8_c5_in" style="endArrow=classic;html=1;rounded=0;dashed=1;" edge="1" parent="1" source="c8" target="c5">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<!-- Legend -->
<mxCell id="legend" value="Legend&#10;-- solid arrow: data flow / call&#10;-- dashed arrow: dependency / read or telemetry&#10;-- green dashed: FDR write side-effect (every component)&#10;Color coding:&#10;-- blue: per-frame onboard runtime&#10;-- green: cross-cutting infra (storage / inference / FDR)&#10;-- orange: operator-side / pre-flight / post-landing&#10;-- yellow: external systems&#10;Note: mock-suite-sat-service is an e2e-test fixture, not a component (ADR-007 reversed)" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#f8f8f8;strokeColor=#999999;align=left;verticalAlign=top;" vertex="1" parent="1">
<mxGeometry x="40" y="900" width="540" height="180" as="geometry" />
</mxCell>
</root>
</mxGraphModel>
</diagram>
</mxfile>
@@ -0,0 +1,34 @@
# System Flow Diagrams — Index
The canonical Mermaid sequence diagrams + flowcharts for every system flow live in the single source of truth `_docs/02_document/system-flows.md`. This index file exists so the `diagrams/` directory has a discoverable per-flow entry point matching the artifact-management convention; **do not duplicate Mermaid bodies here** — keep them in `system-flows.md` so they cannot drift.
## Per-flow links
| Flow | Description | Section in `system-flows.md` |
|------|-------------|------------------------------|
| F1 | Pre-flight cache provisioning | `## Flow F1: Pre-flight cache provisioning` |
| F2 | Takeoff load (cold-start TTFF, AC-NEW-1) | `## Flow F2: Takeoff load` |
| F3 | Steady-state per-frame estimation (the F3 hot path) | `## Flow F3: Steady-state per-frame estimation` |
| F4 | Mid-flight tile generation + local cache write | `## Flow F4: Mid-flight tile generation + local cache write` |
| F5 | Visual blackout + spoofed-GPS failsafe (AC-NEW-8) | `## Flow F5: Visual blackout + spoofed-GPS failsafe` |
| F6 | Sharp-turn / disconnected-segment re-localization | `## Flow F6: Sharp-turn / disconnected-segment re-localization` |
| F7 | Spoofing-promotion via EKF source-set switch (AC-NEW-2) | `## Flow F7: Spoofing-promotion via EKF source-set switch` |
| F8 | Companion reboot recovery | `## Flow F8: Companion reboot recovery` |
| F9 | GCS telemetry stream (AC-6.1) | `## Flow F9: GCS telemetry stream` |
| F10 | Post-landing tile upload (D-PROJ-2 contract) | `## Flow F10: Post-landing tile upload` |
Each section in `system-flows.md` contains: description, preconditions, Mermaid sequence diagram, Mermaid flowchart, data-flow table, error scenarios, and performance expectations.
## Component-level diagram
The component-level diagram (showing component boundaries and inter-component edges) is `_docs/02_document/diagrams/components.drawio`. It is the visual companion to the per-component specs under `_docs/02_document/components/`.
## Conventions reminder
Per `.cursor/skills/plan/templates/system-flows.md` § Mermaid Diagram Conventions:
- Component-named participants (e.g. `participant C5 as C5 StateEstimator`).
- camelCase node IDs.
- `{Question?}` decisions, `([label])` start/end, `[[label]]` for external systems.
- No inline styling.
If a new flow Fn is added, insert it in `system-flows.md` AND add a row above. Do NOT create separate flow files unless the project later decides to split `system-flows.md` per flow (in which case this index becomes the table of contents and the Mermaid bodies move).