# Motorcycle Digital Dashboard - Project Summary

This document serves as a comprehensive summary of all features, architecture, and implementations completed for the Flutter Motorcycle Digital Dashboard application.

## 🏗️ Architecture & Core Stack
- **Framework**: Flutter (Dart) - Android first.
- **State Management**: **Riverpod** (`flutter_riverpod`) used for dependency injection and reactive UI state (e.g., streaming live sensor data).
- **Local Database**: **Drift** (SQLite) used for robust, relational, and type-safe persistence of ride histories.
- **Routing**: **GoRouter** utilized with `StatefulShellRoute` to provide a persistent `BottomNavigationBar` across multiple screens.

---

## 🚀 Features & Implementations

### 1. Telemetry & Sensor Integration
The application interfaces directly with the Android device's hardware to provide real-time telemetry:
- **LocationService**: Uses `geolocator` to stream precise GPS data (5Hz update interval). It applies aggressive filtering to ignore sudden jumps in speed or poor accuracy readings, providing smooth `speed` (MPH) and `heading` data.
- **SensorFusionService**: Uses `sensors_plus` to listen to the device's Accelerometer and Gyroscope. It combines the data using a **Complementary Filter** (Alpha = 0.96) to calculate highly accurate **Bank/Lean Angles** and Pitch, effectively canceling out engine vibration and short-term bumps. Also calculates lateral and longitudinal **G-Forces**.
- **CompassService**: Uses the magnetometer to act as a fallback/secondary heading provider.
- **Mount Calibration**: A mathematical offset system allows the phone to be mounted at any angle on the motorcycle. The rider can "Zero" the sensors to set the current physical orientation as 0° Lean/Pitch.

### 2. Ride State Machine & Automation
- **RideStateMachine**: A Riverpod `StateNotifier` that automatically transitions between `Idle`, `Ready`, and `Riding` states based on GPS speed.
- **Automatic Recording**: Starts tracking a "Ride Session" automatically. It continually calculates and stores the rider's maximums (Top Speed, Max Left/Right Lean, Max G-Force) into memory.

### 3. Performance Metrics
- **PerformanceTimerService**: Automatically detects hard acceleration from 0 MPH. Starts a high-resolution timer and stops precisely when the GPS speed crosses 60 MPH and 100 MPH, logging the 0-60 and 0-100 times.

### 4. Data Persistence (Drift)
- **Rides Table**: Stores completed ride sessions (Start/End time, Top Speed, Max Lean Angles, Max Accel/Braking Gs).
- **PerformanceRuns Table**: Stores 0-60 and 0-100 times linked via foreign key to the specific Ride session.

### 5. User Interface (Material 3)
Designed with extremely high-contrast dark mode for at-a-glance readability while riding.
- **Dashboard Screen**: Adapts dynamically to Portrait and Landscape mounting. Shows a gigantic Speedometer, current Heading, Lean Angle gauge, and live G-Force metrics.
- **Map Screen**: Integrates `google_maps_flutter` for full-screen navigation/tracking. Follows the rider's GPS location. Supports toggling between Normal and Satellite views. *(Note: Requires a valid Google Maps API Key in AndroidManifest.xml)*.
- **History Screen**: A list view populated directly from the Drift database, showing cards for all past rides and their telemetry maximums.
- **Settings Screen**: Provides a "Calibrate Mount Angle" button to zero the sensors, and a "Clear Ride History" button to wipe the local database.

### 6. Police Alert Abstraction
- Created a `PoliceAlertService` interface. Since Google doesn't provide a native speed-trap API endpoint, this is abstracted out so third-party APIs (like Waze/RadarBot) can be injected in the future. A mock implementation is currently provided.

---

## 🛠️ Next Steps / Maintenance
1. **Google Maps API Key**: Replace the `YOUR_API_KEY_HERE` placeholder in `android/app/src/main/AndroidManifest.xml` with a real key from the Google Cloud Console.
2. **iOS Support**: If ported to iOS in the future, the `Info.plist` will need the corresponding Location, Motion, and Background execution permissions added.