Initial commit

docs/02_components/01_flight_api/01.03_feature_user_interaction.md

@@ -0,0 +1,76 @@
+# Feature: User Interaction
+
+## Description
+REST endpoints for user-triggered operations: submitting GPS fixes for blocked flights and converting detected object pixel coordinates to GPS. These endpoints support the human-in-the-loop workflow when automated localization fails.
+
+## Component APIs Implemented
+- `submit_user_fix(flight_id: str, fix_data: UserFixRequest) -> UserFixResponse`
+- `convert_object_to_gps(flight_id: str, frame_id: int, pixel: Tuple[float, float]) -> ObjectGPSResponse`
+- `get_frame_context(flight_id: str, frame_id: int) -> FrameContextResponse`
+
+## REST Endpoints
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/flights/{flightId}/user-fix` | Submit user-provided GPS anchor |
+| POST | `/flights/{flightId}/frames/{frameId}/object-to-gps` | Convert pixel to GPS |
+| GET | `/flights/{flightId}/frames/{frameId}/context` | Get context images for manual fix |
+
+## External Tools and Services
+- **FastAPI**: Web framework for REST endpoints
+- **Pydantic**: Request/response validation
+
+## Internal Methods
+| Method | Purpose |
+|--------|---------|
+| `_validate_user_fix_request(fix_data)` | Validate pixel and GPS coordinates |
+| `_validate_flight_blocked(flight_id)` | Verify flight is in blocked state |
+| `_validate_frame_processed(flight_id, frame_id)` | Verify frame has pose in Factor Graph |
+| `_validate_pixel_coordinates(pixel, resolution)` | Validate pixel within image bounds |
+| `_build_user_fix_response(result)` | Build response with processing status |
+| `_build_object_gps_response(result)` | Build GPS response with accuracy |
+| `_build_frame_context_response(result)` | Build context payload with image URLs |
+
+## Unit Tests
+1. **submit_user_fix validation**
+   - Valid request for blocked flight → returns 200, processing_resumed=true
+   - Flight not blocked → returns 409
+   - Invalid GPS coordinates → returns 400
+   - Non-existent flight_id → returns 404
+
+2. **submit_user_fix pixel validation**
+   - Pixel within image bounds → accepted
+   - Negative pixel coordinates → returns 400
+   - Pixel outside image bounds → returns 400
+
+3. **convert_object_to_gps validation**
+   - Valid processed frame → returns GPS with accuracy
+   - Frame not yet processed → returns 409
+   - Non-existent frame_id → returns 404
+   - Invalid pixel coordinates → returns 400
+
+4. **get_frame_context validation**
+   - Valid blocked frame → returns 200 with UAV and satellite image URLs
+   - Frame not found → returns 404
+   - Context unavailable → returns 409
+
+4. **convert_object_to_gps accuracy**
+   - High confidence frame → low accuracy_meters
+   - Low confidence frame → high accuracy_meters
+
+## Integration Tests
+1. **User fix unblocks processing**
+   - Process until blocked → Submit user fix → Verify processing resumes
+   - Fetch frame context before submission to ensure payload is populated
+   - Verify SSE `processing_resumed` event sent
+
+2. **Object-to-GPS workflow**
+   - Process flight → Call object-to-gps for multiple pixels
+   - Verify GPS coordinates are spatially consistent
+
+3. **User fix with invalid anchor**
+   - Submit fix with GPS far outside geofence
+   - Verify appropriate error handling
+
+4. **Concurrent object-to-gps calls**
+   - Multiple clients request conversion simultaneously
+   - All receive correct responses

docs/02_components/01_flight_api/01__spec_light_api.md

@@ -0,0 +1,708 @@
+# Flight API
+
+## Interface Definition
+
+**Interface Name**: `IFlightAPI`
+
+### Interface Methods
+
+```python
+class IFlightAPI(ABC):
+    @abstractmethod
+    def create_flight(self, flight_data: FlightCreateRequest) -> FlightResponse:
+        pass
+    
+    @abstractmethod
+    def get_flight(self, flight_id: str) -> FlightDetailResponse:
+        pass
+    
+    @abstractmethod
+    def delete_flight(self, flight_id: str) -> DeleteResponse:
+        pass
+    
+    @abstractmethod
+    def update_waypoint(self, flight_id: str, waypoint_id: str, waypoint: Waypoint) -> UpdateResponse:
+        pass
+    
+    @abstractmethod
+    def batch_update_waypoints(self, flight_id: str, waypoints: List[Waypoint]) -> BatchUpdateResponse:
+        pass
+    
+    @abstractmethod
+    def upload_image_batch(self, flight_id: str, batch: ImageBatch) -> BatchResponse:
+        pass
+    
+    @abstractmethod
+    def submit_user_fix(self, flight_id: str, fix_data: UserFixRequest) -> UserFixResponse:
+        pass
+    
+    @abstractmethod
+    def get_flight_status(self, flight_id: str) -> FlightStatusResponse:
+        pass
+    
+    @abstractmethod
+    def create_sse_stream(self, flight_id: str) -> SSEStream:
+        pass
+    
+    @abstractmethod
+    def convert_object_to_gps(self, flight_id: str, frame_id: int, pixel: Tuple[float, float]) -> ObjectGPSResponse:
+        pass
+
+    @abstractmethod
+    def get_frame_context(self, flight_id: str, frame_id: int) -> FrameContextResponse:
+        pass
+```
+
+## Component Description
+
+### Responsibilities
+- Expose REST API endpoints for complete flight lifecycle management
+- Handle flight CRUD operations (create, read, update, delete)
+- Manage waypoints and geofences within flights
+- Handle satellite data prefetching on flight creation
+- Accept batch image uploads (10-50 images per request)
+- Accept user-provided GPS fixes for blocked flights
+- Provide real-time status updates
+- Stream results via Server-Sent Events (SSE)
+
+### Scope
+- FastAPI-based REST endpoints
+- Request/response validation
+- Coordinate with Flight Processor for all operations
+- Multipart form data handling for image uploads
+- SSE connection management
+- Authentication and rate limiting
+
+---
+
+## Flight Management Endpoints
+
+### `create_flight(flight_data: FlightCreateRequest) -> FlightResponse`
+
+**REST Endpoint**: `POST /flights`
+
+**Description**: Creates a new flight with initial waypoints, geofences, camera parameters, and triggers satellite data prefetching.
+
+**Called By**:
+- Client applications (Flight UI, Mission Planner UI)
+
+**Input**:
+```python
+FlightCreateRequest:
+    name: str
+    description: str
+    start_gps: GPSPoint
+    rough_waypoints: List[GPSPoint]
+    geofences: Geofences
+    camera_params: CameraParameters
+    altitude: float
+```
+
+**Output**:
+```python
+FlightResponse:
+    flight_id: str
+    status: str  # "prefetching", "ready", "error"
+    message: Optional[str]
+    created_at: datetime
+```
+
+**Processing Flow**:
+1. Validate request data
+2. Call F02 Flight Processor → create_flight()
+3. Flight Processor triggers satellite prefetch
+4. Return flight_id immediately (prefetch is async)
+
+**Error Conditions**:
+- `400 Bad Request`: Invalid input data (missing required fields, invalid GPS coordinates)
+- `409 Conflict`: Flight with same ID already exists
+- `500 Internal Server Error`: Database or internal error
+
+**Test Cases**:
+1. **Valid flight creation**: Provide valid flight data → returns 201 with flight_id
+2. **Missing required field**: Omit name → returns 400 with error message
+3. **Invalid GPS coordinates**: Provide lat > 90 → returns 400
+4. **Concurrent flight creation**: Multiple flights → all succeed
+
+---
+
+### `get_flight(flight_id: str) -> FlightDetailResponse`
+
+**REST Endpoint**: `GET /flights/{flightId}`
+
+**Description**: Retrieves complete flight information including all waypoints, geofences, and processing status.
+
+**Called By**:
+- Client applications
+
+**Input**:
+```python
+flight_id: str
+```
+
+**Output**:
+```python
+FlightDetailResponse:
+    flight_id: str
+    name: str
+    description: str
+    start_gps: GPSPoint
+    waypoints: List[Waypoint]
+    geofences: Geofences
+    camera_params: CameraParameters
+    altitude: float
+    status: str
+    frames_processed: int
+    frames_total: int
+    created_at: datetime
+    updated_at: datetime
+```
+
+**Error Conditions**:
+- `404 Not Found`: Flight ID does not exist
+- `500 Internal Server Error`: Database error
+
+**Test Cases**:
+1. **Existing flight**: Valid flightId → returns 200 with complete flight data
+2. **Non-existent flight**: Invalid flightId → returns 404
+3. **Flight with many waypoints**: Flight with 2000+ waypoints → returns 200 with all data
+
+---
+
+### `delete_flight(flight_id: str) -> DeleteResponse`
+
+**REST Endpoint**: `DELETE /flights/{flightId}`
+
+**Description**: Deletes a flight and all associated waypoints, images, and processing data.
+
+**Called By**:
+- Client applications
+
+**Input**:
+```python
+flight_id: str
+```
+
+**Output**:
+```python
+DeleteResponse:
+    deleted: bool
+    flight_id: str
+```
+
+**Error Conditions**:
+- `404 Not Found`: Flight does not exist
+- `409 Conflict`: Flight is currently being processed
+- `500 Internal Server Error`: Database error
+
+**Test Cases**:
+1. **Delete existing flight**: Valid flightId → returns 200
+2. **Delete non-existent flight**: Invalid flightId → returns 404
+3. **Delete processing flight**: Active processing → returns 409
+
+---
+
+### `update_waypoint(flight_id: str, waypoint_id: str, waypoint: Waypoint) -> UpdateResponse`
+
+**REST Endpoint**: `PUT /flights/{flightId}/waypoints/{waypointId}`
+
+**Description**: Updates a specific waypoint within a flight. Used for per-frame GPS refinement.
+
+**Called By**:
+- Internal (F13 Result Manager for per-frame updates)
+- Client applications (manual corrections)
+
+**Input**:
+```python
+flight_id: str
+waypoint_id: str
+waypoint: Waypoint:
+    lat: float
+    lon: float
+    altitude: Optional[float]
+    confidence: float
+    timestamp: datetime
+    refined: bool
+```
+
+**Output**:
+```python
+UpdateResponse:
+    updated: bool
+    waypoint_id: str
+```
+
+**Error Conditions**:
+- `404 Not Found`: Flight or waypoint not found
+- `400 Bad Request`: Invalid waypoint data
+- `500 Internal Server Error`: Database error
+
+**Test Cases**:
+1. **Update existing waypoint**: Valid data → returns 200
+2. **Refinement update**: Refined coordinates → updates successfully
+3. **Invalid coordinates**: lat > 90 → returns 400
+4. **Non-existent waypoint**: Invalid waypoint_id → returns 404
+
+---
+
+### `batch_update_waypoints(flight_id: str, waypoints: List[Waypoint]) -> BatchUpdateResponse`
+
+**REST Endpoint**: `PUT /flights/{flightId}/waypoints/batch`
+
+**Description**: Updates multiple waypoints in a single request. Used for trajectory refinements.
+
+**Called By**:
+- Internal (F13 Result Manager for asynchronous refinement updates)
+
+**Input**:
+```python
+flight_id: str
+waypoints: List[Waypoint]
+```
+
+**Output**:
+```python
+BatchUpdateResponse:
+    success: bool
+    updated_count: int
+    failed_ids: List[str]
+```
+
+**Error Conditions**:
+- `404 Not Found`: Flight not found
+- `400 Bad Request`: Invalid waypoint data
+- `500 Internal Server Error`: Database error
+
+**Test Cases**:
+1. **Batch update 100 waypoints**: All succeed
+2. **Partial failure**: 5 waypoints fail → returns failed_ids
+3. **Empty batch**: Returns success=True, updated_count=0
+4. **Large batch**: 500 waypoints → succeeds
+
+---
+
+## Image Processing Endpoints
+
+### `upload_image_batch(flight_id: str, batch: ImageBatch) -> BatchResponse`
+
+**REST Endpoint**: `POST /flights/{flightId}/images/batch`
+
+**Description**: Uploads a batch of 10-50 UAV images for processing.
+
+**Called By**:
+- Client applications
+
+**Input**:
+```python
+flight_id: str
+ImageBatch: multipart/form-data
+    images: List[UploadFile]
+    metadata: BatchMetadata
+        start_sequence: int
+        end_sequence: int
+```
+
+**Output**:
+```python
+BatchResponse:
+    accepted: bool
+    sequences: List[int]
+    next_expected: int
+    message: Optional[str]
+```
+
+**Processing Flow**:
+1. Validate flight_id exists
+2. Validate batch size (10-50 images)
+3. Validate sequence numbers (strict sequential)
+4. Call F02 Flight Processor → queue_images(flight_id, batch)
+5. F02 delegates to F05 Image Input Pipeline
+6. Return immediately (processing is async)
+
+**Error Conditions**:
+- `400 Bad Request`: Invalid batch size, out-of-sequence images
+- `404 Not Found`: flight_id doesn't exist
+- `413 Payload Too Large`: Batch exceeds size limit
+- `429 Too Many Requests`: Rate limit exceeded
+
+**Test Cases**:
+1. **Valid batch upload**: 20 images → returns 202 Accepted
+2. **Out-of-sequence batch**: Sequence gap detected → returns 400
+3. **Too many images**: 60 images → returns 400
+4. **Large images**: 50 × 8MB images → successfully uploads
+
+---
+
+### `submit_user_fix(flight_id: str, fix_data: UserFixRequest) -> UserFixResponse`
+
+**REST Endpoint**: `POST /flights/{flightId}/user-fix`
+
+**Description**: Submits user-provided GPS anchor point to unblock failed localization.
+
+**Called By**:
+- Client applications (when user responds to `user_input_needed` event)
+
+**Input**:
+```python
+UserFixRequest:
+    frame_id: int
+    uav_pixel: Tuple[float, float]
+    satellite_gps: GPSPoint
+```
+
+**Output**:
+```python
+UserFixResponse:
+    accepted: bool
+    processing_resumed: bool
+    message: Optional[str]
+```
+
+**Processing Flow**:
+1. Validate flight_id exists and is blocked
+2. Call F02 Flight Processor → handle_user_fix(flight_id, fix_data)
+3. F02 delegates to F11 Failure Recovery Coordinator
+4. Coordinator applies anchor to Factor Graph
+5. Resume processing pipeline
+
+**Error Conditions**:
+- `400 Bad Request`: Invalid fix data
+- `404 Not Found`: flight_id or frame_id not found
+- `409 Conflict`: Flight not in blocked state
+
+**Test Cases**:
+1. **Valid user fix**: Blocked flight → returns 200, processing resumes
+2. **Fix for non-blocked flight**: Returns 409
+3. **Invalid GPS coordinates**: Returns 400
+
+---
+
+### `convert_object_to_gps(flight_id: str, frame_id: int, pixel: Tuple[float, float]) -> ObjectGPSResponse`
+
+**REST Endpoint**: `POST /flights/{flightId}/frames/{frameId}/object-to-gps`
+
+**Description**: Converts object pixel coordinates to GPS. Used by external object detection systems (e.g., Azaion.Inference) to get GPS coordinates for detected objects.
+
+**Called By**:
+- External object detection systems (Azaion.Inference)
+- Any system needing pixel-to-GPS conversion for a specific frame
+
+**Input**:
+```python
+ObjectToGPSRequest:
+    pixel_x: float  # X coordinate in image
+    pixel_y: float  # Y coordinate in image
+```
+
+**Output**:
+```python
+ObjectGPSResponse:
+    gps: GPSPoint
+    accuracy_meters: float  # Estimated accuracy
+    frame_id: int
+    pixel: Tuple[float, float]
+```
+
+**Processing Flow**:
+1. Validate flight_id and frame_id exist
+2. Validate frame has been processed (has pose in Factor Graph)
+3. Call F02 Flight Processor → convert_object_to_gps(flight_id, frame_id, pixel)
+4. F02 delegates to F13.image_object_to_gps(flight_id, frame_id, pixel)
+5. Return GPS with accuracy estimate
+
+**Error Conditions**:
+- `400 Bad Request`: Invalid pixel coordinates
+- `404 Not Found`: flight_id or frame_id not found
+- `409 Conflict`: Frame not yet processed (no pose available)
+
+**Test Cases**:
+1. **Valid conversion**: Object at (1024, 768) → returns GPS
+2. **Unprocessed frame**: Frame not in Factor Graph → returns 409
+3. **Invalid pixel**: Negative coordinates → returns 400
+
+---
+
+### `get_flight_status(flight_id: str) -> FlightStatusResponse`
+
+**REST Endpoint**: `GET /flights/{flightId}/status`
+
+**Description**: Retrieves current processing status of a flight.
+
+**Called By**:
+- Client applications (polling for status)
+
+**Input**:
+```python
+flight_id: str
+```
+
+**Output**:
+```python
+FlightStatusResponse:
+    status: str  # "prefetching", "ready", "processing", "blocked", "completed", "failed"
+    frames_processed: int
+    frames_total: int
+    current_frame: Optional[int]
+    current_heading: Optional[float]
+    blocked: bool
+    search_grid_size: Optional[int]
+    message: Optional[str]
+    created_at: datetime
+    updated_at: datetime
+```
+
+**Error Conditions**:
+- `404 Not Found`: flight_id doesn't exist
+
+**Test Cases**:
+1. **Processing flight**: Returns current progress
+2. **Blocked flight**: Returns blocked=true with search_grid_size
+3. **Completed flight**: Returns status="completed" with final counts
+
+---
+
+### `create_sse_stream(flight_id: str) -> SSEStream`
+
+**REST Endpoint**: `GET /flights/{flightId}/stream`
+
+**Description**: Opens Server-Sent Events connection for real-time result streaming.
+
+**Called By**:
+- Client applications
+
+**Input**:
+```python
+flight_id: str
+```
+
+**Output**:
+```python
+SSE Stream with events:
+    - frame_processed
+    - frame_refined
+    - search_expanded
+    - user_input_needed
+    - processing_blocked
+    - flight_completed
+```
+
+**Processing Flow**:
+1. Validate flight_id exists
+2. Call F02 Flight Processor → create_client_stream(flight_id, client_id)
+3. F02 delegates to F15 SSE Event Streamer → create_stream()
+4. Return SSE stream to client
+
+**Event Format**:
+```json
+{
+  "event": "frame_processed",
+  "data": {
+    "frame_id": 237,
+    "gps": {"lat": 48.123, "lon": 37.456},
+    "altitude": 800.0,
+    "confidence": 0.95,
+    "heading": 87.3,
+    "timestamp": "2025-11-24T10:30:00Z"
+  }
+}
+```
+
+**Error Conditions**:
+- `404 Not Found`: flight_id doesn't exist
+- Connection closed on client disconnect
+
+**Test Cases**:
+1. **Connect to stream**: Opens SSE connection successfully
+2. **Receive frame events**: Process 100 frames → receive 100 events
+3. **Receive user_input_needed**: Blocked frame → event sent
+4. **Client reconnect**: Replay missed events from last_event_id
+
+---
+
+## Integration Tests
+
+### Test 1: Complete Flight Lifecycle
+1. POST /flights with valid data
+2. GET /flights/{flightId} → verify data
+3. GET /flights/{flightId}/stream (open SSE)
+4. POST /flights/{flightId}/images/batch × 40
+5. Receive frame_processed events via SSE
+6. Receive flight_completed event
+7. GET /flights/{flightId} → verify waypoints updated
+8. DELETE /flights/{flightId}
+
+### Test 2: User Fix Flow
+1. Create flight and process images
+2. Receive user_input_needed event
+3. POST /flights/{flightId}/user-fix
+4. Receive processing_resumed event
+5. Continue receiving frame_processed events
+
+### Test 3: Concurrent Flights
+1. Create 10 flights concurrently
+2. Upload batches to all flights in parallel
+3. Stream results from all flights simultaneously
+4. Verify no cross-contamination
+
+### Test 4: Waypoint Updates
+1. Create flight
+2. Simulate per-frame updates via PUT /flights/{flightId}/waypoints/{waypointId} × 100
+3. GET flight and verify all waypoints updated
+4. Verify refined=true flag set
+
+---
+
+## Non-Functional Requirements
+
+### Performance
+- **create_flight**: < 500ms response (prefetch is async)
+- **get_flight**: < 200ms for flights with < 2000 waypoints
+- **update_waypoint**: < 100ms (critical for real-time updates)
+- **upload_image_batch**: < 2 seconds for 50 × 2MB images
+- **submit_user_fix**: < 200ms response
+- **get_flight_status**: < 100ms
+- **SSE latency**: < 500ms from event generation to client receipt
+
+### Scalability
+- Support 100 concurrent flight processing sessions
+- Handle 1000+ concurrent SSE connections
+- Handle flights with up to 3000 waypoints
+- Support 10,000 requests per minute
+
+### Reliability
+- Request timeout: 30 seconds for batch uploads
+- SSE keepalive: Ping every 30 seconds
+- Automatic SSE reconnection with event replay
+- Graceful handling of client disconnects
+
+### Security
+- API key authentication
+- Rate limiting: 100 requests/minute per client
+- Max upload size: 500MB per batch
+- CORS configuration for web clients
+- Input validation on all endpoints
+- SQL injection prevention
+
+---
+
+## Dependencies
+
+### Internal Components
+- **F02 Flight Processor**: For ALL operations (flight CRUD, image batching, user fixes, SSE streams, object-to-GPS conversion). F01 is a thin REST layer that delegates all business logic to F02.
+
+**Note**: F01 does NOT directly call F05, F11, F13, or F15. All operations are routed through F02 to maintain a single coordinator pattern.
+
+### External Dependencies
+- **FastAPI**: Web framework
+- **Uvicorn**: ASGI server
+- **Pydantic**: Validation
+- **python-multipart**: Multipart form handling
+
+---
+
+## Data Models
+
+### GPSPoint
+```python
+class GPSPoint(BaseModel):
+    lat: float  # Latitude -90 to 90
+    lon: float  # Longitude -180 to 180
+```
+
+### CameraParameters
+```python
+class CameraParameters(BaseModel):
+    focal_length: float  # mm
+    sensor_width: float  # mm
+    sensor_height: float  # mm
+    resolution_width: int  # pixels
+    resolution_height: int  # pixels
+    distortion_coefficients: Optional[List[float]] = None
+```
+
+### Polygon
+```python
+class Polygon(BaseModel):
+    north_west: GPSPoint
+    south_east: GPSPoint
+```
+
+### Geofences
+```python
+class Geofences(BaseModel):
+    polygons: List[Polygon]
+```
+
+### FlightCreateRequest
+```python
+class FlightCreateRequest(BaseModel):
+    name: str
+    description: str
+    start_gps: GPSPoint
+    rough_waypoints: List[GPSPoint]
+    geofences: Geofences
+    camera_params: CameraParameters
+    altitude: float
+```
+
+### Waypoint
+```python
+class Waypoint(BaseModel):
+    id: str
+    lat: float
+    lon: float
+    altitude: Optional[float] = None
+    confidence: float
+    timestamp: datetime
+    refined: bool = False
+```
+
+### FlightDetailResponse
+```python
+class FlightDetailResponse(BaseModel):
+    flight_id: str
+    name: str
+    description: str
+    start_gps: GPSPoint
+    waypoints: List[Waypoint]
+    geofences: Geofences
+    camera_params: CameraParameters
+    altitude: float
+    status: str
+    frames_processed: int
+    frames_total: int
+    created_at: datetime
+    updated_at: datetime
+```
+
+### FlightStatusResponse
+```python
+class FlightStatusResponse(BaseModel):
+    status: str
+    frames_processed: int
+    frames_total: int
+    current_frame: Optional[int]
+    current_heading: Optional[float]
+    blocked: bool
+    search_grid_size: Optional[int]
+    message: Optional[str]
+    created_at: datetime
+    updated_at: datetime
+```
+
+### BatchMetadata
+```python
+class BatchMetadata(BaseModel):
+    start_sequence: int
+    end_sequence: int
+    batch_number: int
+```
+
+### BatchUpdateResponse
+```python
+class BatchUpdateResponse(BaseModel):
+    success: bool
+    updated_count: int
+    failed_ids: List[str]
+    errors: Optional[Dict[str, str]]
+```