# Architecture Overview

## System Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                         SIMULATION LAYER                         │
│  ┌──────────────────┐  ┌──────────────────┐  ┌───────────────┐ │
│  │   Gazebo World   │  │  ArduPilot SITL  │  │    MAVROS     │ │
│  │  (Physics, Viz)  │  │   (Autopilot)    │  │  (ROS Bridge) │ │
│  └────────┬─────────┘  └────────┬─────────┘  └───────┬───────┘ │
└───────────┼─────────────────────┼─────────────────────┼─────────┘
            │                     │                     │
            ▼                     ▼                     ▼
┌─────────────────────────────────────────────────────────────────┐
│                         SENSOR LAYER                             │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌──────────┐  │
│  │  Forward   │  │  Downward  │  │    IMU     │  │  Range-  │  │
│  │  Camera    │  │  Camera    │  │            │  │  finder  │  │
│  └─────┬──────┘  └─────┬──────┘  └─────┬──────┘  └────┬─────┘  │
└────────┼───────────────┼───────────────┼──────────────┼────────┘
         │               │               │              │
         ▼               ▼               ▼              ▼
┌─────────────────────────────────────────────────────────────────┐
│                       PERCEPTION LAYER                           │
│  ┌─────────────────────┐  ┌────────────────┐  ┌──────────────┐  │
│  │   Visual Odometry   │  │  Optical Flow  │  │  Landmark    │  │
│  │  (ORB/SIFT/SURF)    │  │ (Lucas-Kanade) │  │  Detection   │  │
│  └──────────┬──────────┘  └───────┬────────┘  └──────┬───────┘  │
└─────────────┼─────────────────────┼──────────────────┼──────────┘
              │                     │                  │
              ▼                     ▼                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                      LOCALIZATION LAYER                          │
│                    ┌──────────────────────┐                      │
│                    │   Position Estimator │                      │
│                    │   (EKF Sensor Fusion)│                      │
│                    └──────────┬───────────┘                      │
└───────────────────────────────┼─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                       NAVIGATION LAYER                           │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
│  │  Local Planner  │  │    Obstacle     │  │    Waypoint     │  │
│  │                 │  │   Avoidance     │  │    Follower     │  │
│  └────────┬────────┘  └────────┬────────┘  └────────┬────────┘  │
└───────────┼────────────────────┼────────────────────┼───────────┘
            │                    │                    │
            ▼                    ▼                    ▼
┌─────────────────────────────────────────────────────────────────┐
│                        CONTROL LAYER                             │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
│  │  UAV Controller │  │  UGV Controller │  │ Mission Planner │  │
│  │                 │  │                 │  │                 │  │
│  └────────┬────────┘  └────────┬────────┘  └────────┬────────┘  │
└───────────┼────────────────────┼────────────────────┼───────────┘
            │                    │                    │
            ▼                    ▼                    ▼
┌─────────────────────────────────────────────────────────────────┐
│                        SAFETY LAYER                              │
│  ┌─────────────────────────┐  ┌─────────────────────────────┐   │
│  │   Geofence Monitor      │  │   Failsafe Handler          │   │
│  │   (GPS-based only)      │  │   (Vision loss, battery)    │   │
│  └─────────────────────────┘  └─────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
```

## Module Descriptions

### Vision Module (`src/vision/`)
- **camera_processor.py**: Image preprocessing, undistortion
- **visual_odometry.py**: Feature-based pose estimation
- **optical_flow.py**: Velocity from image flow
- **object_detector.py**: Landmark/obstacle detection
- **visual_servoing.py**: Vision-based control

### Localization Module (`src/localization/`)
- **position_estimator.py**: Sensor fusion for position
- **ekf_fusion.py**: Extended Kalman Filter implementation
- **landmark_tracker.py**: Track known visual features

### Navigation Module (`src/navigation/`)
- **local_planner.py**: Path planning in local frame
- **obstacle_avoidance.py**: Reactive obstacle avoidance
- **waypoint_follower.py**: Sequential waypoint navigation

### Control Module (`src/control/`)
- **uav_controller.py**: Quadcopter flight control
- **ugv_controller.py**: Ground vehicle control
- **mission_planner.py**: Multi-vehicle coordination

### Safety Module (`src/safety/`)
- **geofence_monitor.py**: GPS-based boundary checking
- **failsafe_handler.py**: Emergency procedures

## Data Flow

```
Camera Image → Feature Detection → Feature Matching → 
Essential Matrix → Relative Pose → EKF Update → 
Local Position → Navigation Controller → 
Velocity Commands → MAVROS → ArduPilot
```

## ROS 2 Topics

### Sensor Topics
- `/uav/camera/forward/image_raw`
- `/uav/camera/downward/image_raw`
- `/uav/imu/data`
- `/uav/rangefinder/range`

### Perception Topics
- `/uav/visual_odometry/pose`
- `/uav/optical_flow/velocity`

### Control Topics
- `/uav/mavros/setpoint_position/local`
- `/uav/mavros/setpoint_velocity/cmd_vel`
- `/ugv/cmd_vel`

### Safety Topics
- `/geofence/status`
- `/failsafe/active`