gps-denied-onboard/.planning/codebase/STRUCTURE.md

Codebase Structure

Analysis Date: 2026-04-01

Directory Layout

gps-denied-onboard/
├── src/
│   └── gps_denied/             # Main package
│       ├── __init__.py         # Package version
│       ├── __main__.py         # Entry point (uvicorn runner)
│       ├── app.py              # FastAPI app factory + lifespan
│       ├── config.py           # Pydantic-settings configuration classes
│       ├── api/
│       │   ├── __init__.py
│       │   ├── deps.py         # FastAPI dependency providers (singletons)
│       │   └── routers/
│       │       ├── __init__.py
│       │       └── flights.py  # All /flights/* endpoints
│       ├── core/
│       │   ├── processor.py    # FlightProcessor — main orchestrator
│       │   ├── pipeline.py     # ImageInputPipeline — image ingestion/queuing
│       │   ├── vo.py           # SequentialVisualOdometry (SuperPoint+LightGlue)
│       │   ├── satellite.py    # SatelliteDataManager (tile fetch/cache)
│       │   ├── gpr.py          # GlobalPlaceRecognition (AnyLoc/DINOv2)
│       │   ├── metric.py       # MetricRefinement (LiteSAM homography alignment)
│       │   ├── graph.py        # FactorGraphOptimizer (GTSAM/mock pose graph)
│       │   ├── chunk_manager.py # RouteChunkManager (disconnected segments)
│       │   ├── recovery.py     # FailureRecoveryCoordinator (tracking loss handling)
│       │   ├── rotation.py     # ImageRotationManager (360° sweep, heading tracking)
│       │   ├── coordinates.py  # CoordinateTransformer (ENU↔GPS, pixel→GPS)
│       │   ├── models.py       # ModelManager + MockInferenceEngine
│       │   ├── results.py      # ResultManager (DB + SSE publish)
│       │   └── sse.py          # SSEEventStreamer (per-flight async queues)
│       ├── db/
│       │   ├── __init__.py
│       │   ├── engine.py       # Async SQLAlchemy engine + session factory
│       │   ├── models.py       # ORM table definitions (8 tables)
│       │   └── repository.py   # FlightRepository DAO (all SQL operations)
│       ├── schemas/
│       │   ├── __init__.py     # GPSPoint, CameraParameters, Polygon, Geofences
│       │   ├── flight.py       # Flight CRUD request/response schemas
│       │   ├── image.py        # ImageBatch, ImageData, ProcessedBatch schemas
│       │   ├── vo.py           # Features, Matches, Motion, RelativePose
│       │   ├── gpr.py          # TileCandidate, DatabaseMatch
│       │   ├── metric.py       # AlignmentResult, ChunkAlignmentResult, Sim3Transform
│       │   ├── satellite.py    # TileCoords, TileBounds
│       │   ├── graph.py        # Pose, OptimizationResult, FactorGraphConfig
│       │   ├── chunk.py        # ChunkHandle, ChunkStatus enum
│       │   ├── rotation.py     # RotationResult, HeadingHistory
│       │   ├── model.py        # InferenceEngine base schema
│       │   └── events.py       # SSEMessage, SSEEventType, FrameProcessedEvent, etc.
│       └── utils/
│           └── mercator.py     # Slippy map tile math (lat/lon↔tile x/y/bounds)
├── _docs/
│   ├── _autopilot_state.md     # GSD planning state tracker
│   ├── 01_solution/
│   │   └── solution.md         # Master architecture document (finalized draft 06)
│   └── 02_document/
│       └── tests/              # Test scenario specifications (43 scenarios)
├── .planning/
│   └── codebase/               # GSD mapping documents (this directory)
├── .venv/                      # Python virtual environment (committed or local)
├── pyproject.toml              # Project metadata and dependencies
└── flight_data.db              # SQLite DB (runtime artifact, not committed)

Directory Purposes

src/gps_denied/:

• Purpose: Top-level Python package; everything importable from here
• Key files: app.py (create_app factory), config.py (all settings), __main__.py (entrypoint)

src/gps_denied/api/:

• Purpose: HTTP API surface only — routing, request/response handling, dependency injection
• Contains: One router (flights.py) with 9 endpoints, deps.py with 3 singleton providers
• Key files: routers/flights.py (all endpoints), deps.py (ProcessorDep, SessionDep, RepoDep)

src/gps_denied/core/:

• Purpose: All processing logic — state machines, algorithms, pipeline components
• Module count: 14 files
• Key files: processor.py (orchestrator), models.py (inference abstraction), graph.py (pose graph)
• Note: Each component has a matching I* ABC interface defined in the same file

src/gps_denied/db/:

• Purpose: Database access only — no business logic
• Contains: Engine setup, ORM models, one repository class
• Key files: models.py (8 ORM tables), repository.py (all DB operations)

src/gps_denied/schemas/:

• Purpose: Pydantic data contracts; shared across API, core, and DB layers
• Contains: 12 schema files covering every domain concept
• Key files: __init__.py (GPSPoint, CameraParameters — imported everywhere), flight.py (largest — all REST schemas)

src/gps_denied/utils/:

• Purpose: Pure utility functions with no side effects
• Contains: mercator.py — Mercator projection math for tile coordinate conversion
• Used by: satellite.py exclusively

_docs/:

• Purpose: Architecture documentation and planning artifacts — not source code
• Key files: 01_solution/solution.md (the authoritative design doc), _autopilot_state.md (GSD planning tracker)

Key File Locations

Entry Points:

• src/gps_denied/__main__.py: Invoked by python -m gps_denied; starts uvicorn
• src/gps_denied/app.py: create_app() factory; app module-level instance used by uvicorn

Configuration:

• src/gps_denied/config.py: All settings via pydantic-settings; reads from .env and env vars
  • DB_URL → SQLAlchemy connection string (default: SQLite)
  • TILES_ZOOM_LEVEL, TILES_CACHE_DIR, TILES_API_KEY → satellite tile provider
  • MODEL_WEIGHTS_DIR, MODEL_SUPERPOINT_PATH, etc. → model file paths
  • RECOVERY_*, ROTATION_* → algorithm thresholds

Core Orchestration:

• src/gps_denied/core/processor.py: FlightProcessor — only class that calls other pipeline components

Dependency Wiring:

• src/gps_denied/api/deps.py: Single location where singletons (FlightProcessor, SSEEventStreamer) are created and wired; ProcessorDep type alias used in all routers

Database Schema:

• src/gps_denied/db/models.py: All 8 ORM tables with cascade deletes; ground truth for DB schema

Pydantic Contracts:

• src/gps_denied/schemas/__init__.py: GPSPoint and CameraParameters — imported by nearly every module

Naming Conventions

Files:

• snake_case.py throughout
• Core components named after their function: vo.py, gpr.py, metric.py, graph.py
• Interfaces co-located with implementation in the same file (ISequentialVisualOdometry and SequentialVisualOdometry both in vo.py)

Classes:

• Implementation classes: PascalCase noun phrases (FlightProcessor, RouteChunkManager)
• Interfaces: I prefix + implementation name (IRouteChunkManager)
• ORM models: suffixed with Row (FlightRow, WaypointRow)
• Pydantic models: suffixed with Request/Response for API schemas; bare names for internal data

Functions:

• snake_case
• Async functions throughout API and DB layers; sync in core (except process_frame which is async)

Constants/Enums:

• TrackingState: str, Enum with lowercase values ("normal", "lost", "recovery")
• SSEEventType: str, Enum with snake_case values
• ChunkStatus: str, Enum

Where to Add New Code

New API endpoint:

• Add route function to src/gps_denied/api/routers/flights.py
• Add request/response Pydantic models to src/gps_denied/schemas/flight.py
• Add business logic method to src/gps_denied/core/processor.py
• If new router prefix needed: create src/gps_denied/api/routers/{name}.py and register in app.py

New pipeline component:

• Create src/gps_denied/core/{component_name}.py
• Define I{ComponentName}(ABC) interface and {ComponentName} implementation in same file
• Add schemas to src/gps_denied/schemas/{component_name}.py
• Add component instantiation to app.py lifespan block
• Inject via FlightProcessor.attach_components() and call from process_frame()

New database table:

• Add {Name}Row(Base) to src/gps_denied/db/models.py
• Add CRUD methods to src/gps_denied/db/repository.py
• Add foreign key + relationship to FlightRow if flight-scoped

New configuration setting:

• Add field to the appropriate BaseSettings subclass in src/gps_denied/config.py
• Use ENV_PREFIX__FIELD_NAME env var pattern

New schema type:

• Add to src/gps_denied/schemas/{relevant_file}.py or create new file
• If broadly shared (like GPSPoint), add to src/gps_denied/schemas/__init__.py

Utility functions:

• Add to src/gps_denied/utils/mercator.py if geospatial math
• Create src/gps_denied/utils/{name}.py for other pure utilities

Special Directories

.venv/:

• Purpose: Python virtual environment
• Generated: Yes (via python -m venv or uv)
• Committed: Present in tree (check .gitignore)

_docs/:

• Purpose: Architecture docs, test specs, GSD planning artifacts
• Generated: No (hand-authored)
• Committed: Yes

.planning/:

• Purpose: GSD (Get Stuff Done) planning system — phase plans, codebase maps
• Generated: By GSD commands
• Committed: Yes (used by CI/planning tools)

.image_storage/ (runtime):

• Purpose: Disk storage for uploaded UAV images per flight
• Created by: ImageInputPipeline.store_images()
• Path: Relative to process CWD; configurable via ImageInputPipeline(storage_dir=...)

.satellite_cache/ (runtime):

• Purpose: diskcache directory for satellite tiles
• Created by: SatelliteDataManager.__init__()
• Size limit: 10GB default

Module Dependency Graph (simplified)

api/routers/flights.py
    → api/deps.py
        → core/processor.py
            → core/pipeline.py       (image ingestion)
            → core/results.py        (DB + SSE publish)
            → core/sse.py            (event streaming)
            → [via attach_components]
                → core/vo.py         → core/models.py
                → core/gpr.py        → core/models.py
                → core/metric.py     → core/models.py
                → core/graph.py      (optional: gtsam)
                → core/chunk_manager.py → core/graph.py
                → core/recovery.py   → core/chunk_manager.py
                                     → core/gpr.py
                                     → core/metric.py
                → core/rotation.py
        → db/repository.py
            → db/models.py
        → core/sse.py
    → db/engine.py

core/satellite.py     (standalone — not wired into processor yet)
core/coordinates.py   (standalone — not wired into processor yet)
utils/mercator.py     → only used by core/satellite.py
schemas/*             → imported by all layers (no internal imports)
config.py             → imported by db/engine.py, and anywhere settings needed

Notably standalone (not connected to processor):

• src/gps_denied/core/satellite.py: SatelliteDataManager — instantiated nowhere in app.py or processor.py; satellite tiles fetched inline with mock in processor.py
• src/gps_denied/core/coordinates.py: CoordinateTransformer — not instantiated in the pipeline; convert_object_to_gps in processor returns a hardcoded stub (GPSPoint(lat=48.0, lon=37.0))

---

Structure analysis: 2026-04-01