component assesment and fixes done

docs/02_components/02_flight_processor/flight_lifecycle_manager_spec.md

@@ -0,0 +1,146 @@
+# Flight Lifecycle Manager
+
+## Interface Definition
+
+**Interface Name**: `IFlightLifecycleManager`
+
+### Interface Methods
+
+```python
+class IFlightLifecycleManager(ABC):
+    # Flight Lifecycle
+    @abstractmethod
+    def create_flight(self, flight_data: FlightData) -> str:
+        pass
+    
+    @abstractmethod
+    def get_flight(self, flight_id: str) -> Optional[Flight]:
+        pass
+    
+    @abstractmethod
+    def get_flight_state(self, flight_id: str) -> Optional[FlightState]:
+        pass
+    
+    @abstractmethod
+    def delete_flight(self, flight_id: str) -> bool:
+        pass
+    
+    @abstractmethod
+    def update_flight_status(self, flight_id: str, status: FlightStatusUpdate) -> bool:
+        pass
+    
+    # Waypoint Management
+    @abstractmethod
+    def update_waypoint(self, flight_id: str, waypoint_id: str, waypoint: Waypoint) -> bool:
+        pass
+    
+    @abstractmethod
+    def batch_update_waypoints(self, flight_id: str, waypoints: List[Waypoint]) -> BatchUpdateResult:
+        pass
+    
+    @abstractmethod
+    def get_flight_metadata(self, flight_id: str) -> Optional[FlightMetadata]:
+        pass
+    
+    # Validation
+    @abstractmethod
+    def validate_waypoint(self, waypoint: Waypoint) -> ValidationResult:
+        pass
+    
+    @abstractmethod
+    def validate_geofence(self, geofence: Geofences) -> ValidationResult:
+        pass
+    
+    @abstractmethod
+    def validate_flight_continuity(self, waypoints: List[Waypoint]) -> ValidationResult:
+        pass
+    
+    # API Delegation Methods (called by F01)
+    @abstractmethod
+    def queue_images(self, flight_id: str, batch: ImageBatch) -> BatchQueueResult:
+        """Delegates to F05 Image Input Pipeline and triggers F02.2 Processing Engine."""
+        pass
+    
+    @abstractmethod
+    def handle_user_fix(self, flight_id: str, fix_data: UserFixRequest) -> UserFixResult:
+        """Delegates to F02.2 Processing Engine to apply fix."""
+        pass
+    
+    @abstractmethod
+    def create_client_stream(self, flight_id: str, client_id: str) -> StreamConnection:
+        """Delegates to F15 SSE Event Streamer."""
+        pass
+    
+    @abstractmethod
+    def convert_object_to_gps(self, flight_id: str, frame_id: int, pixel: Tuple[float, float]) -> GPSPoint:
+        """Delegates to F13 Coordinate Transformer."""
+        pass
+    
+    # System Initialization
+    @abstractmethod
+    def initialize_system(self) -> bool:
+        pass
+```
+
+## Component Description
+
+### Responsibilities
+- **Component ID**: F02.1
+- **Flight Lifecycle**: Manage flight creation, persistence, and deletion.
+- **System Entry Point**: Main interface for the REST API (F01).
+- **Resource Management**: Initializes system components and manages `F02.2 Flight Processing Engine` instances.
+- **Data Validation**: Validates inputs before processing.
+- **Satellite Prefetching**: Triggers F04 prefetching on flight creation.
+
+### Scope
+- CRUD operations for Flights and Waypoints.
+- Coordination of system startup.
+- Hand-off of active processing tasks to F02.2.
+- Does **NOT** contain the processing loop or recovery logic.
+
+## API Methods
+
+### `create_flight(flight_data: FlightData) -> str`
+**Description**: Creates a new flight, validates data, sets ENU origin, and triggers satellite prefetching.
+**Called By**: F01 Flight API
+**Processing Flow**:
+1. Generate flight_id.
+2. Validate geofences and waypoints.
+3. Call F13.set_enu_origin(flight_id, start_gps).
+4. Trigger F04.prefetch_route_corridor().
+5. Save to F03 Flight Database.
+6. Return flight_id.
+
+### `queue_images(flight_id: str, batch: ImageBatch) -> BatchQueueResult`
+**Description**: Queues images and ensures a Processing Engine is active for this flight.
+**Processing Flow**:
+1. Delegate to F05.queue_batch().
+2. Retrieve or create instance of `F02.2 Flight Processing Engine` for this flight.
+3. Trigger `engine.start_processing()` (async).
+4. Return result.
+
+### `handle_user_fix(flight_id: str, fix_data: UserFixRequest) -> UserFixResult`
+**Description**: Forwards user fix to the active processing engine.
+**Processing Flow**:
+1. Get active engine for flight_id.
+2. Call `engine.apply_user_fix(fix_data)`.
+3. Return result.
+
+### `initialize_system() -> bool`
+**Description**: startup routine.
+**Processing Flow**:
+1. Load config (F17).
+2. Initialize models (F16).
+3. Initialize DB (F03).
+4. Initialize Cache (F04).
+5. Load Indexes (F08).
+
+## Dependencies
+- **F02.2 Flight Processing Engine**: Managed child component.
+- **F03 Flight Database**: Persistence.
+- **F04 Satellite Data Manager**: Prefetching.
+- **F05 Image Input Pipeline**: Image queuing.
+- **F13 Coordinate Transformer**: ENU origin setting.
+- **F15 SSE Event Streamer**: Stream creation.
+- **F17 Configuration Manager**: Config loading.
+

docs/02_components/02_flight_processor/flight_processing_engine_spec.md

@@ -0,0 +1,108 @@
+# Flight Processing Engine
+
+## Interface Definition
+
+**Interface Name**: `IFlightProcessingEngine`
+
+### Interface Methods
+
+```python
+class IFlightProcessingEngine(ABC):
+    @abstractmethod
+    def start_processing(self, flight_id: str) -> None:
+        """Starts the main processing loop in a background thread/task."""
+        pass
+    
+    @abstractmethod
+    def stop_processing(self, flight_id: str) -> None:
+        pass
+    
+    @abstractmethod
+    def process_frame(self, flight_id: str, frame_id: int) -> FrameResult:
+        pass
+    
+    @abstractmethod
+    def apply_user_fix(self, flight_id: str, fix_data: UserFixRequest) -> UserFixResult:
+        pass
+    
+    @abstractmethod
+    def handle_tracking_loss(self, flight_id: str, frame_id: int) -> RecoveryStatus:
+        pass
+    
+    # Chunk Lifecycle (Delegates to F12 but orchestrated here)
+    @abstractmethod
+    def get_active_chunk(self, flight_id: str) -> Optional[ChunkHandle]:
+        pass
+    
+    @abstractmethod
+    def create_new_chunk(self, flight_id: str, frame_id: int) -> ChunkHandle:
+        pass
+```
+
+## Component Description
+
+### Responsibilities
+- **Component ID**: F02.2
+- **Processing Orchestration**: Runs the main loop: Image -> VO -> Graph -> Result.
+- **State Machine**: Manages flight status (Processing, Blocked, Recovering, Completed).
+- **Recovery Coordination**: Calls F11 methods and acts on return values.
+- **Chunk Management**: Calls F12 to manage chunk lifecycle based on tracking status.
+- **Background Tasks**: Manages background chunk matching tasks.
+
+### Scope
+- Per-flight processing logic.
+- Interaction with Visual Pipeline (F06, F07, F09).
+- Interaction with State Estimation (F10).
+- Interaction with Recovery (F11).
+- Result Publishing (F14, F15).
+
+## Processing Flow
+
+### `run_processing_loop(flight_id: str)`
+1.  **Loop**: While `F05.get_next_image()` returns image:
+2.  **Chunk Check**:
+    *   `active_chunk = F12.get_active_chunk()`
+    *   If `detect_chunk_boundary()`: `active_chunk = F12.create_chunk()`.
+3.  **Visual Odometry**:
+    *   Call `F06.requires_rotation_sweep()`.
+    *   Call `F07.compute_relative_pose()`.
+4.  **Tracking Check**:
+    *   If tracking good:
+        *   `F12.add_frame_to_chunk()`.
+        *   `F09.align_to_satellite()` (optional drift correction).
+        *   `F10.add_relative_factor()`.
+        *   `F10.optimize_chunk()`.
+        *   `F14.update_frame_result()`.
+    *   If tracking lost:
+        *   **Proactive Chunking**: `F11.create_chunk_on_tracking_loss()`.
+        *   **Recovery**: Call `handle_tracking_loss()`.
+
+### `handle_tracking_loss(flight_id, frame_id)`
+1.  Call `F11.start_search()`.
+2.  Loop progressive search (1..25 tiles):
+    *   `result = F11.try_current_grid()`.
+    *   If found: `F11.mark_found()`, break.
+    *   If not found: `F11.expand_search_radius()`.
+3.  If still not found:
+    *   `req = F11.create_user_input_request()`.
+    *   `F15.send_user_input_request(req)`.
+    *   Set status to **BLOCKED**.
+    *   Wait for `apply_user_fix`.
+
+### `apply_user_fix(fix_data)`
+1.  Call `F11.apply_user_anchor(fix_data)`.
+2.  If success:
+    *   Set status to **PROCESSING**.
+    *   Resume loop.
+
+## Dependencies
+- **F05 Image Input Pipeline**: Image source.
+- **F06 Image Rotation Manager**: Pre-processing.
+- **F07 Sequential Visual Odometry**: Motion estimation.
+- **F09 Metric Refinement**: Satellite alignment.
+- **F10 Factor Graph Optimizer**: State estimation.
+- **F11 Failure Recovery Coordinator**: Recovery logic.
+- **F12 Route Chunk Manager**: Chunk state.
+- **F14 Result Manager**: Saving results.
+- **F15 SSE Event Streamer**: Real-time updates.
+