gps-denied-onboard/_docs/02_document/module-layout.md

# 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/`
- **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**: BASALT VIO Adapter, Satellite Service, Anchor Verification, Tile Manager, FDR And Observability

### Component: BASALT VIO Adapter

- **Epic**: AZ-213
- **Directory**: `src/basalt_vio_adapter/`
- **Native Directory**: `src/native/basalt_bridge/`
- **Technologies**: Python adapter, C++ native bridge, BASALT, Eigen/Sophus or BASALT math stack, OpenCV 4.x, shared time-sync contracts
- **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

### 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**: 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

### Component: Satellite Service

- **Epic**: AZ-214
- **Directory**: `src/satellite_service/`
- **Native Directory**: `src/native/tensor_rt/`
- **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/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
- **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/`
- **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/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

### 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**: BASALT 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, BASALT 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 | 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.

## Out-of-Product E2E Test Suite

The 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/**`, `tests/e2e/**`, `e2e/replay/**`, and `e2e/reports/**`, and it exercises the runtime only through public file, MAVLink, cache, status, and FDR interfaces.

- **Technologies**: Python, pytest-style runner, Docker/compose, pymavlink/log parser, ArduPilot Plane SITL, QGC observer/log parser, CSV/Markdown reports

## 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, except explicitly assigned native directories.
- Paths follow the project `src/` layout already confirmed by `AZ-219_initial_structure`.