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/`
- **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`.