gps-denied-desktop/_docs/02_components/structure_plan.md

Initial Structure for gps-denied

Technology Stack

• Python: 3.10+ (GTSAM compatibility)
• Web Framework: FastAPI (async)
• Database: PostgreSQL + SQLAlchemy ORM
• Validation: Pydantic v2
• ML Runtime: TensorRT (primary), ONNX Runtime (fallback) - NO PyTorch needed for inference
• Graph Optimization: GTSAM
• Similarity Search: Faiss

Project Structure

gps-denied/
├── main.py                        # FastAPI app entry point
├── pyproject.toml
├── .gitignore
├── .env.example
├── README.md
│
├── models/                        # Pydantic DTOs (1 file per model)
│   ├── __init__.py                # Re-exports all models
│   ├── core/                      # Core shared models
│   │   ├── __init__.py
│   │   ├── gps_point.py
│   │   ├── camera_parameters.py
│   │   ├── pose.py
│   │   ├── polygon.py
│   │   └── validation_result.py
│   ├── flight/                    # Flight domain models
│   │   ├── __init__.py
│   │   ├── flight.py
│   │   ├── flight_state.py
│   │   ├── waypoint.py
│   │   ├── geofences.py
│   │   └── heading_record.py
│   ├── processing/                # Visual processing models
│   │   ├── __init__.py
│   │   ├── relative_pose.py
│   │   ├── motion.py
│   │   ├── matches.py
│   │   ├── alignment_result.py
│   │   └── rotation_result.py
│   ├── chunks/                    # Chunk-related models
│   │   ├── __init__.py
│   │   ├── chunk_handle.py
│   │   ├── chunk_bounds.py
│   │   └── sim3_transform.py
│   ├── satellite/                 # Satellite tile models
│   │   ├── __init__.py
│   │   ├── tile_coords.py
│   │   ├── tile_bounds.py
│   │   └── tile_candidate.py
│   ├── recovery/                  # Recovery/search models
│   │   ├── __init__.py
│   │   ├── search_session.py
│   │   ├── confidence_assessment.py
│   │   ├── user_anchor.py
│   │   └── user_input_request.py
│   ├── results/                   # Result models
│   │   ├── __init__.py
│   │   ├── frame_result.py
│   │   ├── flight_results.py
│   │   ├── refined_frame_result.py
│   │   └── optimization_result.py
│   ├── images/                    # Image-related models
│   │   ├── __init__.py
│   │   ├── image_data.py
│   │   ├── image_metadata.py
│   │   ├── image_batch.py
│   │   └── processing_status.py
│   ├── config/                    # Configuration models
│   │   ├── __init__.py
│   │   ├── system_config.py
│   │   ├── flight_config.py
│   │   ├── database_config.py
│   │   ├── model_config.py
│   │   ├── rotation_config.py
│   │   └── recovery_config.py
│   └── api/                       # API request/response models
│       ├── __init__.py
│       ├── flight_requests.py
│       ├── flight_responses.py
│       ├── batch_requests.py
│       └── user_fix_requests.py
│
├── components/                    # Interface (base.py) + implementation together
│   ├── __init__.py
│   ├── flight_api/
│   │   ├── __init__.py
│   │   ├── base.py                # ABC interface
│   │   └── flight_api.py          # Implementation
│   ├── flight_lifecycle_manager/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   └── flight_lifecycle_manager.py
│   ├── flight_processing_engine/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   └── flight_processing_engine.py
│   ├── flight_database/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   └── flight_database.py
│   ├── satellite_data_manager/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   └── satellite_data_manager.py
│   ├── image_input_pipeline/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   └── image_input_pipeline.py
│   ├── image_rotation_manager/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   └── image_rotation_manager.py
│   ├── sequential_visual_odometry/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   └── sequential_visual_odometry.py
│   ├── global_place_recognition/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   └── global_place_recognition.py
│   ├── metric_refinement/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   └── metric_refinement.py
│   ├── factor_graph_optimizer/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   └── factor_graph_optimizer.py
│   ├── failure_recovery_coordinator/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   └── failure_recovery_coordinator.py
│   ├── route_chunk_manager/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   └── route_chunk_manager.py
│   ├── coordinate_transformer/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   └── coordinate_transformer.py
│   ├── result_manager/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   └── result_manager.py
│   ├── sse_event_streamer/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   └── sse_event_streamer.py
│   ├── model_manager/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   └── model_manager.py
│   └── configuration_manager/
│       ├── __init__.py
│       ├── base.py
│       └── configuration_manager.py
│
├── helpers/                       # Single file per helper
│   ├── __init__.py
│   ├── camera_model.py
│   ├── gsd_calculator.py
│   ├── robust_kernels.py
│   ├── faiss_index_manager.py
│   ├── performance_monitor.py
│   ├── web_mercator_utils.py
│   ├── image_rotation_utils.py
│   └── batch_validator.py
│
├── db/                            # Database layer
│   ├── __init__.py
│   ├── connection.py
│   ├── models.py                  # SQLAlchemy ORM models
│   └── migrations/
│
├── api/                           # FastAPI routes
│   ├── __init__.py
│   ├── routes/
│   │   ├── __init__.py
│   │   ├── flights.py
│   │   ├── images.py
│   │   └── stream.py
│   └── dependencies.py
│
└── _docs/                         # Documentation

Dependencies (pyproject.toml)

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "azaion-gps-denied-desktop"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "fastapi>=0.109.0",
    "uvicorn[standard]>=0.27.0",
    "pydantic>=2.5.0",
    "sqlalchemy[asyncio]>=2.0.0",
    "asyncpg>=0.29.0",
    "alembic>=1.13.0",
    "numpy>=1.26.0",
    "opencv-python>=4.9.0",
    "sse-starlette>=2.0.0",
    "python-multipart>=0.0.6",
    "httpx>=0.26.0",
    "pyyaml>=6.0",
    "gtsam>=4.2",
]

[project.optional-dependencies]
ml = [
    "tensorrt>=10.0.0",
    "onnxruntime-gpu>=1.17.0",
    "faiss-gpu>=1.7.4",
]
dev = [
    "pytest>=7.4.0",
    "pytest-asyncio>=0.21.0",
    "pytest-cov>=4.1.0",
]

[tool.hatch.build.targets.wheel]
packages = ["models", "components", "helpers", "db", "api"]

Note: PyTorch removed - TensorRT and ONNX Runtime handle inference without it.

Implementation Phases

Phase 1: Project Setup ✓

• Create package structure with __init__.py files
• Create pyproject.toml, .gitignore, README.md, .env.example
• Setup uv for dependency management

Phase 2: Core DTOs ✓

• models/core/ - GPSPoint, CameraParameters, Pose, Polygon, ValidationResult
• models/flight/ - Flight, FlightState, Waypoint, Geofences, HeadingRecord
• models/processing/ - RelativePose, AlignmentResult, Matches, Motion, RotationResult
• models/chunks/ - ChunkHandle, ChunkBounds, Sim3Transform
• All remaining model subdirectories (satellite, recovery, results, images, config, api)

Phase 3: Components with Interfaces ✓

• Each component folder contains:
  • base.py - ABC interface
  • {component_name}.py - Implementation stub with NotImplementedError
• All 18 components implemented

Phase 4: Helpers ✓

• Single file helpers with class stubs
• All 8 helpers implemented

Phase 5: Database Schema ✓

• SQLAlchemy ORM models (Flight, Waypoint, FrameResult, Chunk)
• Async connection management with asyncpg
• Alembic migrations folder created

Phase 6: API Routes ✓

• FastAPI routes for flights, images, SSE streaming
• Dependency injection setup

Completed Tasks

• Create package structure, pyproject.toml, .gitignore
• Create all Pydantic DTOs (models/ directory)
• Create components with base.py (ABC) + stub implementations
• Create helper files with empty implementations
• Create SQLAlchemy models and Alembic setup
• Create API routes and dependencies