azaion/gps-denied-onboard
1
0
Fork 0
mirror of https://github.com/azaion/gps-denied-onboard.git synced 2026-06-21 13:41:14 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
3d2c22d8ba69cc0766e20c1123cf58fd22d2e9e1
gps-denied-onboard/_docs/02_document/module-layout.md
T
Oleksandr Bezdieniezhnykh cab7b5d020 [AZ-233] Update Docker Compose and enhance test documentation 
- Modified the Docker Compose configuration to include an input root for replay tests and added an environment variable for enabling SITL.
- Enhanced documentation for various testing processes, including the addition of a Runtime Completeness Decomposition Gate and clarifications on internal module testing requirements.
- Updated the implementation completeness report to reflect the current state and added new test cases for performance and resilience scenarios.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-06 05:03:48 +03:00

248 lines
12 KiB
Markdown
Raw Blame History

# 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 inside the owning component folder under `native/`.
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/`
- **Technologies**: Python, OpenCV 4.x, camera SDK/V4L2/GigE adapter boundary, calibration files, shared geometry/time helpers
- **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**: VIO Adapter, Satellite Service, Anchor Verification, Tile Manager, FDR And Observability
### Component: VIO Adapter
- **Epic**: AZ-213
- **Directory**: `src/vio_adapter/`
- **Native Directory**: `src/vio_adapter/native/`
- **Technologies**: Python adapter, C++ native bridge, BASALT as current backend, Eigen/Sophus or backend-native math stack, OpenCV 4.x, shared time-sync contracts
- **Public API**:
- `src/vio_adapter/__init__.py`
- `src/vio_adapter/types.py`
- `src/vio_adapter/interfaces.py`
- **Internal (do NOT import from other components)**:
- `src/vio_adapter/internal/*`
- `src/vio_adapter/_*.py`
- `src/vio_adapter/native/**`
- **Owns (exclusive write during implementation)**:
- `src/vio_adapter/**`
- **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
### Component: Safety And Anchor Wrapper
- **Epic**: AZ-216
- **Directory**: `src/safety_anchor_wrapper/`
- **Technologies**: Python state machine, OpenCV geometry helpers, covariance/gating logic, shared DTO contracts, MAVLink output DTOs
- **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**: 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
### Component: Satellite Service
- **Epic**: AZ-214
- **Directory**: `src/satellite_service/`
- **Native Directory**: `src/satellite_service/native/`
- **Technologies**: Python service adapter, DINOv2-VLAD descriptors, ONNX/TensorRT candidate path, CPU FAISS, offline package sync client
- **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/satellite_service/native/**`
- **Owns (exclusive write during implementation)**:
- `src/satellite_service/**`
- **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
- **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/anchor_verification/native/`
- **Technologies**: Python validation pipeline, ALIKED/DISK + LightGlue, OpenCV RANSAC/USAC, SIFT/ORB baseline, native feature-matching bridge
- **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/anchor_verification/native/**`
- **Owns (exclusive write during implementation)**:
- `src/anchor_verification/**`
- **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
### Component: Tile Manager
- **Epic**: AZ-211
- **Directory**: `src/tile_manager/`
- **Technologies**: Python repository/policy layer, PostgreSQL/PostGIS, GDAL/rasterio COG handling, signed JSON sidecars, OpenCV/GDAL orthorectification, hash/signature validation
- **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
### Component: MAVLink And GCS Integration
- **Epic**: AZ-210
- **Directory**: `src/mavlink_gcs_integration/`
- **Technologies**: Python, MAVSDK telemetry subscriptions, pymavlink `GPS_INPUT` emission, MAVLink/QGC status messages
- **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**: VIO Adapter, Safety And Anchor Wrapper, FDR And Observability
### Component: FDR And Observability
- **Epic**: AZ-212
- **Directory**: `src/fdr_observability/`
- **Technologies**: Python append/export layer, PostgreSQL event index, CBOR segment payloads, optional Parquet export, structured logging/health events
- **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
## Shared / Cross-Cutting
### shared/contracts
- **Epic**: AZ-206
- **Directory**: `src/shared/contracts/`
- **Technologies**: Python typed DTOs, schema/contract definitions, Markdown API-contract documents
- **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/`
- **Technologies**: Python geometry utilities, OpenCV 4.x, WGS84/local-frame math, homography/covariance conversions
- **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.
### shared/time_sync
- **Epic**: AZ-207
- **Directory**: `src/shared/time_sync/`
- **Technologies**: Python timestamp utilities, monotonic-clock validation, MAVLink/camera timestamp normalization, replay ordering checks
- **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, VIO Adapter, MAVLink And GCS Integration, FDR And Observability.
### shared/config
- **Epic**: AZ-208
- **Directory**: `src/shared/config/`
- **Technologies**: Python configuration loader, environment variables, `.env.example`, startup readiness validation
- **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.
### shared/errors
- **Epic**: AZ-208
- **Directory**: `src/shared/errors/`
- **Technologies**: Python exception/result envelope types, shared error categories, fail-fast helpers
- **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/`
- **Technologies**: Python structured logging, metrics labels, health event DTOs, FDR-safe telemetry metadata
- **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 |
|-------|------------|-----------------|
| 4. Runtime Output / Coordination | Safety And Anchor Wrapper, MAVLink And GCS Integration, FDR And Observability | 1, 2, 3 public interfaces |
| 3. Perception / Satellite Anchor | 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.
## Out-of-Product Blackbox / E2E Test Suite
The blackbox/e2e replay/SITL/Jetson validation suite is not a product component and must not receive Step 6 product implementation tasks. It owns test-support artifacts under `tests/blackbox/**`, `e2e/replay/**`, `e2e/fixtures/**`, `e2e/mocks/**`, `docker-compose.test.yml`, and `deployment/docker/Dockerfile.replay`, and it exercises the runtime only through public file, MAVLink, cache, status, and FDR interfaces.
- **Technologies**: Python, pytest-style runner, Docker/compose, deterministic fixture stubs, ArduPilot Plane SITL/QGC observer placeholders, CSV/Markdown reports
- **Entry points**:
- Local: `python3 -m pytest`
- Replay: `python -m e2e.replay.run_replay --output-dir <dir> --input-root <fixture-root>`
- Compose: `docker compose -f docker-compose.test.yml run --build --rm replay-consumer`
## Self-Verification
- Every runtime 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; native bridge paths live inside the component that owns them.
- Paths follow the project `src/` layout already confirmed by `AZ-219_initial_structure`.
Reference in New Issue View Git Blame Copy Permalink