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.