mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-06-21 08:21:13 +00:00
Update autodev state documentation to reflect progress in the Decompose phase, changing the current step from 5 to 6. Revise sub-step details to indicate a shift to phase 2, focusing on module layout for the Satellite Service and Tile Manager, and awaiting confirmation before product task decomposition. Additionally, enhance problem documentation to clarify the original still-image sample limitations and introduce the Derkachi representative fixture for improved data validation. Update references to the Tile Manager and Satellite Service throughout the documentation for consistency.
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -0,0 +1,245 @@
|
||||
# Module Layout
|
||||
|
||||
**Language**: mixed (Python orchestration + C++ native vision bridges)
|
||||
**Layout Convention**: src-layout
|
||||
**Root**: `src/`
|
||||
**Last Updated**: 2026-05-03
|
||||
|
||||
## Layout Rules
|
||||
|
||||
1. Each product component owns one top-level directory under `src/`.
|
||||
2. Shared contracts and cross-cutting helpers live under `src/shared/`.
|
||||
3. Native hot-path or third-party bridge code lives under `src/native/` and is owned by the component that wraps it.
|
||||
4. Public API surface per component is limited to `__init__.py`, `types.py`, and `interfaces.py` unless a component entry lists another public file.
|
||||
5. Tests live under `tests/` by test type and component; implementation tasks must not place tests inside the component tree unless a later test task explicitly changes this layout.
|
||||
|
||||
## Per-Component Mapping
|
||||
|
||||
### Component: Camera Ingest And Calibration
|
||||
|
||||
- **Epic**: AZ-209
|
||||
- **Directory**: `src/camera_ingest_calibration/`
|
||||
- **Public API**:
|
||||
- `src/camera_ingest_calibration/__init__.py`
|
||||
- `src/camera_ingest_calibration/types.py`
|
||||
- `src/camera_ingest_calibration/interfaces.py`
|
||||
- **Internal (do NOT import from other components)**:
|
||||
- `src/camera_ingest_calibration/internal/*`
|
||||
- `src/camera_ingest_calibration/_*.py`
|
||||
- **Owns (exclusive write during implementation)**: `src/camera_ingest_calibration/**`
|
||||
- **Imports from**: shared/contracts, shared/geo_geometry, shared/time_sync, shared/config, shared/errors, shared/telemetry
|
||||
- **Consumed by**: BASALT VIO Adapter, Satellite Service, Anchor Verification, Tile Manager, FDR And Observability, Validation Harness
|
||||
|
||||
### Component: BASALT VIO Adapter
|
||||
|
||||
- **Epic**: AZ-213
|
||||
- **Directory**: `src/basalt_vio_adapter/`
|
||||
- **Native Directory**: `src/native/basalt_bridge/`
|
||||
- **Public API**:
|
||||
- `src/basalt_vio_adapter/__init__.py`
|
||||
- `src/basalt_vio_adapter/types.py`
|
||||
- `src/basalt_vio_adapter/interfaces.py`
|
||||
- **Internal (do NOT import from other components)**:
|
||||
- `src/basalt_vio_adapter/internal/*`
|
||||
- `src/basalt_vio_adapter/_*.py`
|
||||
- `src/native/basalt_bridge/**`
|
||||
- **Owns (exclusive write during implementation)**:
|
||||
- `src/basalt_vio_adapter/**`
|
||||
- `src/native/basalt_bridge/**`
|
||||
- **Imports from**: Camera Ingest And Calibration, MAVLink And GCS Integration, shared/contracts, shared/geo_geometry, shared/time_sync, shared/config, shared/errors, shared/telemetry
|
||||
- **Consumed by**: Safety And Anchor Wrapper, FDR And Observability, Validation Harness
|
||||
|
||||
### Component: Safety And Anchor Wrapper
|
||||
|
||||
- **Epic**: AZ-216
|
||||
- **Directory**: `src/safety_anchor_wrapper/`
|
||||
- **Public API**:
|
||||
- `src/safety_anchor_wrapper/__init__.py`
|
||||
- `src/safety_anchor_wrapper/types.py`
|
||||
- `src/safety_anchor_wrapper/interfaces.py`
|
||||
- **Internal (do NOT import from other components)**:
|
||||
- `src/safety_anchor_wrapper/internal/*`
|
||||
- `src/safety_anchor_wrapper/_*.py`
|
||||
- **Owns (exclusive write during implementation)**: `src/safety_anchor_wrapper/**`
|
||||
- **Imports from**: BASALT VIO Adapter, Anchor Verification, MAVLink And GCS Integration, Camera Ingest And Calibration, shared/contracts, shared/geo_geometry, shared/time_sync, shared/config, shared/errors, shared/telemetry
|
||||
- **Consumed by**: MAVLink And GCS Integration, Tile Manager, FDR And Observability, Validation Harness
|
||||
|
||||
### Component: Satellite Service
|
||||
|
||||
- **Epic**: AZ-214
|
||||
- **Directory**: `src/satellite_service/`
|
||||
- **Native Directory**: `src/native/tensor_rt/`
|
||||
- **Public API**:
|
||||
- `src/satellite_service/__init__.py`
|
||||
- `src/satellite_service/types.py`
|
||||
- `src/satellite_service/interfaces.py`
|
||||
- **Internal (do NOT import from other components)**:
|
||||
- `src/satellite_service/internal/*`
|
||||
- `src/satellite_service/_*.py`
|
||||
- `src/native/tensor_rt/**`
|
||||
- **Owns (exclusive write during implementation)**:
|
||||
- `src/satellite_service/**`
|
||||
- `src/native/tensor_rt/**`
|
||||
- **Imports from**: Camera Ingest And Calibration, Tile Manager, Safety And Anchor Wrapper, shared/contracts, shared/geo_geometry, shared/time_sync, shared/config, shared/errors, shared/telemetry
|
||||
- **Consumed by**: Anchor Verification, FDR And Observability, Validation Harness
|
||||
- **Network invariant**: external Satellite Service sync is allowed only pre-flight or post-flight; no mid-flight satellite-provider or suite-service calls.
|
||||
|
||||
### Component: Anchor Verification
|
||||
|
||||
- **Epic**: AZ-215
|
||||
- **Directory**: `src/anchor_verification/`
|
||||
- **Native Directory**: `src/native/feature_matching/`
|
||||
- **Public API**:
|
||||
- `src/anchor_verification/__init__.py`
|
||||
- `src/anchor_verification/types.py`
|
||||
- `src/anchor_verification/interfaces.py`
|
||||
- **Internal (do NOT import from other components)**:
|
||||
- `src/anchor_verification/internal/*`
|
||||
- `src/anchor_verification/_*.py`
|
||||
- `src/native/feature_matching/**`
|
||||
- **Owns (exclusive write during implementation)**:
|
||||
- `src/anchor_verification/**`
|
||||
- `src/native/feature_matching/**`
|
||||
- **Imports from**: Satellite Service, Camera Ingest And Calibration, Tile Manager, shared/contracts, shared/geo_geometry, shared/time_sync, shared/config, shared/errors, shared/telemetry
|
||||
- **Consumed by**: Safety And Anchor Wrapper, FDR And Observability, Validation Harness
|
||||
|
||||
### Component: Tile Manager
|
||||
|
||||
- **Epic**: AZ-211
|
||||
- **Directory**: `src/tile_manager/`
|
||||
- **Public API**:
|
||||
- `src/tile_manager/__init__.py`
|
||||
- `src/tile_manager/types.py`
|
||||
- `src/tile_manager/interfaces.py`
|
||||
- **Internal (do NOT import from other components)**:
|
||||
- `src/tile_manager/internal/*`
|
||||
- `src/tile_manager/_*.py`
|
||||
- **Owns (exclusive write during implementation)**:
|
||||
- `src/tile_manager/**`
|
||||
- `migrations/postgresql/cache_*.sql`
|
||||
- `migrations/seed/cache_*`
|
||||
- **Imports from**: Camera Ingest And Calibration, Safety And Anchor Wrapper, shared/contracts, shared/geo_geometry, shared/time_sync, shared/config, shared/errors, shared/telemetry
|
||||
- **Consumed by**: Satellite Service, Anchor Verification, FDR And Observability, Validation Harness
|
||||
|
||||
### Component: MAVLink And GCS Integration
|
||||
|
||||
- **Epic**: AZ-210
|
||||
- **Directory**: `src/mavlink_gcs_integration/`
|
||||
- **Public API**:
|
||||
- `src/mavlink_gcs_integration/__init__.py`
|
||||
- `src/mavlink_gcs_integration/types.py`
|
||||
- `src/mavlink_gcs_integration/interfaces.py`
|
||||
- **Internal (do NOT import from other components)**:
|
||||
- `src/mavlink_gcs_integration/internal/*`
|
||||
- `src/mavlink_gcs_integration/_*.py`
|
||||
- **Owns (exclusive write during implementation)**: `src/mavlink_gcs_integration/**`
|
||||
- **Imports from**: Safety And Anchor Wrapper, shared/contracts, shared/time_sync, shared/config, shared/errors, shared/telemetry
|
||||
- **Consumed by**: BASALT VIO Adapter, Safety And Anchor Wrapper, FDR And Observability, Validation Harness
|
||||
|
||||
### Component: FDR And Observability
|
||||
|
||||
- **Epic**: AZ-212
|
||||
- **Directory**: `src/fdr_observability/`
|
||||
- **Public API**:
|
||||
- `src/fdr_observability/__init__.py`
|
||||
- `src/fdr_observability/types.py`
|
||||
- `src/fdr_observability/interfaces.py`
|
||||
- **Internal (do NOT import from other components)**:
|
||||
- `src/fdr_observability/internal/*`
|
||||
- `src/fdr_observability/_*.py`
|
||||
- **Owns (exclusive write during implementation)**:
|
||||
- `src/fdr_observability/**`
|
||||
- `migrations/postgresql/fdr_*.sql`
|
||||
- `migrations/seed/fdr_*`
|
||||
- **Imports from**: shared/contracts, shared/time_sync, shared/config, shared/errors, shared/telemetry
|
||||
- **Consumed by**: all runtime components, Validation Harness
|
||||
|
||||
### Component: Validation Harness
|
||||
|
||||
- **Epic**: AZ-217
|
||||
- **Directory**: `src/validation_harness/`
|
||||
- **Public API**:
|
||||
- `src/validation_harness/__init__.py`
|
||||
- `src/validation_harness/types.py`
|
||||
- `src/validation_harness/interfaces.py`
|
||||
- **Internal (do NOT import from other components)**:
|
||||
- `src/validation_harness/internal/*`
|
||||
- `src/validation_harness/_*.py`
|
||||
- **Owns (exclusive write during implementation)**:
|
||||
- `src/validation_harness/**`
|
||||
- `e2e/replay/**`
|
||||
- `e2e/reports/**`
|
||||
- **Imports from**: public runtime interfaces only, shared/contracts, shared/geo_geometry, shared/time_sync, shared/config, shared/errors, shared/telemetry
|
||||
- **Consumed by**: CI/CD pipeline and release evidence review
|
||||
|
||||
## Shared / Cross-Cutting
|
||||
|
||||
### shared/contracts
|
||||
|
||||
- **Epic**: AZ-206
|
||||
- **Directory**: `src/shared/contracts/`
|
||||
- **Purpose**: Shared DTOs, protocol shapes, schemas, and public contract exports.
|
||||
- **Owned by**: initial structure and shared-contract tasks under AZ-206.
|
||||
- **Consumed by**: all components.
|
||||
|
||||
### shared/geo_geometry
|
||||
|
||||
- **Epic**: AZ-207
|
||||
- **Directory**: `src/shared/geo_geometry/`
|
||||
- **Purpose**: WGS84/local conversions, GSD, camera footprint projection, homography/covariance unit conversion, and distance calculations.
|
||||
- **Owned by**: shared geometry task under AZ-207.
|
||||
- **Consumed by**: Camera Ingest And Calibration, Safety And Anchor Wrapper, Anchor Verification, Tile Manager, Validation Harness.
|
||||
|
||||
### shared/time_sync
|
||||
|
||||
- **Epic**: AZ-207
|
||||
- **Directory**: `src/shared/time_sync/`
|
||||
- **Purpose**: Monotonic timestamp checks, frame-to-IMU alignment, clock-domain metadata, replay ordering, and gap/jitter metrics.
|
||||
- **Owned by**: time-sync task under AZ-207.
|
||||
- **Consumed by**: Camera Ingest And Calibration, BASALT VIO Adapter, MAVLink And GCS Integration, FDR And Observability, Validation Harness.
|
||||
|
||||
### shared/config
|
||||
|
||||
- **Epic**: AZ-208
|
||||
- **Directory**: `src/shared/config/`
|
||||
- **Purpose**: Runtime profile loading, environment validation, typed settings, and startup readiness inputs.
|
||||
- **Owned by**: runtime configuration task under AZ-208.
|
||||
- **Consumed by**: all runtime components and Validation Harness.
|
||||
|
||||
### shared/errors
|
||||
|
||||
- **Epic**: AZ-208
|
||||
- **Directory**: `src/shared/errors/`
|
||||
- **Purpose**: Error categories, result envelopes, fail-fast helpers, and non-silent exception contracts.
|
||||
- **Owned by**: runtime error contract task under AZ-208.
|
||||
- **Consumed by**: all components.
|
||||
|
||||
### shared/telemetry
|
||||
|
||||
- **Epic**: AZ-208
|
||||
- **Directory**: `src/shared/telemetry/`
|
||||
- **Purpose**: Structured logging, metrics labels, health event shapes, and FDR-safe event metadata helpers.
|
||||
- **Owned by**: observability/config contract task under AZ-208.
|
||||
- **Consumed by**: all components.
|
||||
|
||||
## Allowed Dependencies (layering)
|
||||
|
||||
Read top-to-bottom; an upper layer may import from a lower layer but never the reverse.
|
||||
|
||||
| Layer | Components | May import from |
|
||||
|-------|------------|-----------------|
|
||||
| 5. Validation / Evidence | Validation Harness | 1, 2, 3, 4 public interfaces |
|
||||
| 4. Runtime Output / Coordination | Safety And Anchor Wrapper, MAVLink And GCS Integration, FDR And Observability | 1, 2, 3 public interfaces |
|
||||
| 3. Perception / Satellite Anchor | BASALT VIO Adapter, Satellite Service, Anchor Verification | 1, 2 public interfaces |
|
||||
| 2. Data Ingest / Persistence | Camera Ingest And Calibration, Tile Manager | 1 |
|
||||
| 1. Shared / Foundation | shared/contracts, shared/geo_geometry, shared/time_sync, shared/config, shared/errors, shared/telemetry | none |
|
||||
|
||||
Violations of this table are Architecture findings in code-review Phase 7 and are High severity.
|
||||
|
||||
## Self-Verification
|
||||
|
||||
- Every component under `_docs/02_document/components/` has a mapping entry.
|
||||
- Cross-cutting epics AZ-206, AZ-207, and AZ-208 have shared ownership entries.
|
||||
- Layering covers all components and keeps shared code at the bottom.
|
||||
- Component-owned paths do not overlap, except explicitly assigned native directories.
|
||||
- Paths follow the project `src/` layout already confirmed by `AZ-219_initial_structure`.
|
||||
Reference in New Issue
Block a user