# 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)

```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

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