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 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 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; native bridge paths live inside the component that owns them.
• Paths follow the project src/ layout already confirmed by AZ-219_initial_structure.