[AZ-219] [AZ-228] Generalize VIO component layout

Keep VIO package and native bridge paths backend-neutral so BASALT remains an implementation choice rather than a component boundary.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-03 12:20:41 +03:00
parent 79997e39ac
commit 72a9df6b57
34 changed files with 123 additions and 114 deletions
@@ -16,10 +16,13 @@ project-root/
├── src/
│ ├── __init__.py
│ ├── camera_ingest_calibration/
│ ├── basalt_vio_adapter/
│ ├── vio_adapter/
│ │ └── native/
│ ├── safety_anchor_wrapper/
│ ├── satellite_service/
│ │ └── native/
│ ├── anchor_verification/
│ │ └── native/
│ ├── tile_manager/
│ ├── mavlink_gcs_integration/
│ ├── fdr_observability/
@@ -30,10 +33,6 @@ project-root/
│ │ ├── config/
│ │ ├── errors/
│ │ └── telemetry/
│ └── native/
│ ├── basalt_bridge/
│ ├── feature_matching/
│ └── tensor_rt/
├── migrations/
│ ├── postgresql/
│ └── seed/
@@ -74,7 +73,7 @@ project-root/
### Layout Rationale
The runtime is organized directly under `src/` because this repository already represents the GPS-denied onboard system. Component directories live at the source root, with native bridges isolated under `src/native/` for BASALT, feature matching, and TensorRT-sensitive paths. Shared contracts, geometry, time-sync, configuration, error envelopes, and telemetry DTOs are centralized so component tasks consume a single public interface instead of duplicating cross-cutting logic.
The runtime is organized directly under `src/` because this repository already represents the GPS-denied onboard system. Component directories live at the source root, and native bridges stay inside the component folder that owns the backend or hot path. Shared contracts, geometry, time-sync, configuration, error envelopes, and telemetry DTOs are centralized so component tasks consume a single public interface instead of duplicating cross-cutting logic.
The scaffold separates runtime source, migrations, tests, deployment assets, configuration, and mutable data. Production runs on Jetson hardware, while Docker/compose is used for replay, SITL, and deterministic CI environments.
@@ -98,8 +97,8 @@ The scaffold separates runtime source, migrations, tests, deployment assets, con
| Component | Interface | Methods | Exposed To |
|-----------|-----------|---------|------------|
| Camera ingest/calibration | `FrameProvider` | `next_frame`, `detect_occlusion`, `classify_quality` | BASALT VIO, Satellite Service, anchor verification, Tile Manager |
| BASALT VIO adapter | `VioAdapter` | `initialize`, `process`, `health` | Safety wrapper, e2e tests |
| Camera ingest/calibration | `FrameProvider` | `next_frame`, `detect_occlusion`, `classify_quality` | VIO Adapter, Satellite Service, anchor verification, Tile Manager |
| VIO adapter | `VioAdapter` | `initialize`, `process`, `health` | Safety wrapper, e2e tests |
| Safety/anchor wrapper | `LocalizationStateMachine` | `update_vio`, `consider_anchor`, `degrade`, `propagate_imu_only`, `tile_write_eligibility` | MAVLink/GCS, Tile Manager, FDR, e2e tests |
| Satellite Service | `SatelliteService` | `import_mission_cache`, `load_index`, `retrieve`, `upload_generated_tiles` | Safety wrapper, anchor verification, Tile Manager |
| Anchor verification | `AnchorVerifier` | `verify`, `benchmark_matcher` | Safety wrapper, FDR |
@@ -174,7 +173,7 @@ tests/
├── unit/
│ ├── shared/
│ ├── camera_ingest_calibration/
│ ├── basalt_vio_adapter/
│ ├── vio_adapter/
│ ├── safety_anchor_wrapper/
│ ├── satellite_service/
│ ├── anchor_verification/
@@ -245,7 +244,7 @@ Each deployable service exposes `/health/live`, `/health/ready`, and `/metrics`
| 5 | MAVLink/GCS integration | Supplies FC telemetry DTOs and validates `GPS_INPUT` output contract early |
| 6 | Tile Manager | Owns PostGIS cache manifest, sidecars, COG access, freshness gates, and generated-tile orthorectification |
| 7 | FDR/observability | Provides audit path for all components and validation reports |
| 8 | BASALT VIO adapter | Depends on frame and telemetry contracts, blocks wrapper integration |
| 8 | VIO adapter | Depends on frame and telemetry contracts, blocks wrapper integration |
| 9 | Satellite Service | Depends on tile schema and frame DTOs, feeds anchor verification, and handles pre-flight/post-flight package sync |
| 10 | Anchor verification | Depends on retrieval candidates and cache tile access |
| 11 | Safety/anchor wrapper | Consumes VIO, anchor, camera degradation, MAVLink, and FDR contracts |