update readme

palm_oil_mobile/README.md

@@ -1,70 +1,88 @@
 # Palm Oil Ripeness AI - Mobile App
 
-This Flutter application ports the AI-driven palm oil ripeness detection system to mobile devices. It allows for gallery-based analysis with local history storage and health alerts.
+A professional, high-performance Flutter application designed for palm oil plantation managers and harvesters. This app provides real-time and static AI-driven ripeness detection, enabling data-driven harvesting decisions directly in the field.
+
+---
+
+## 📱 Executive Summary
+The **Palm Oil Ripeness AI** mobile app is a field-ready tool that automates the assessment of Fresh Fruit Bunches (FFB). By leveraging on-device Deep Learning (TFLite), the app eliminates the need for internet connectivity in remote plantations, providing instant grading and health alerts to optimize yield and minimize loss from premature harvest.
+
+---
 
 ## 🛠 Features
-- **AI Inference**: On-device TFLite processing for ripeness classification.
-- **Gallery Analysis**: Pick photos directly from the device gallery.
-- **History Vault**: Local storage of detection results using SQFlite.
-- **Health Alerts**: Immediate UI feedback for abnormal bunches.
+
+### 1. **Live Inference (Point-and-Scan)**
+- **Real-time Detection:** Utilizes an atomic idle-lock mechanism to process camera streams at high speed.
+- **Momentum Lock:** A robust hysteresis system that "locks" onto fruit bunches to prevent camera stutter and ensure reliable capture.
+- **Auto-Capture:** Automatically triggers a high-resolution snapshot once a stable detection is confirmed.
+
+### 2. **Snap & Analyze (Manager's Manual Mode)**
+- **High-Res Accuracy:** Manual shutter mode using `ResolutionPreset.high` for maximum detail.
+- **Direct JPEG Decoding:** Skips YUV conversion for the most accurate industrial-grade inference.
+- **Auto-Reset Workflow:** Seamlessly clears previous results after acknowledgment to allow rapid sequential captures.
+
+### 3. **Analyze Gallery**
+- Allows managers to analyze previously captured photos from the device's storage.
+- Includes a scanning animation and detailed bounding box overlays.
+
+### 4. **History Vault & Result Persistence**
+- **SQLite Storage:** Every analysis is stored locally with metadata (ripeness class, confidence, coordinates).
+- **Image Archiving:** Automatically copies and persists captured images to the `ApplicationDocumentsDirectory`.
+
+### 5. **Industrial Alerts & Summaries**
+- **Health Alert:** 🔴 Red warnings for "Abnormal" or "Empty_Bunch" detections.
+- **Yield Warning:** 🟠 Orange alerts for "Unripe" or "Underripe" fruit, highlighting "Potential Yield Loss".
+
+---
 
 ## 🚀 Setup & Installation
 
 ### Prerequisites
-- [Flutter SDK](https://docs.flutter.dev/get-started/install) installed and added to your PATH.
-- Android Studio or VS Code with Flutter extension.
-- A physical Android device connected via USB with "Developer Options" and "USB Debugging" enabled.
+- [Flutter SDK](https://docs.flutter.dev/get-started/install) (latest stable).
+- Android Studio / VS Code with Flutter & Dart extensions.
+- A physical Android/iOS device (Camera required; Emulators NOT recommended).
 
 ### 1. Initialize Project
-Navigate to the mobile project directory and fetch dependencies:
 ```bash
+# Navigate to the mobile project directory
 cd palm_oil_mobile
+
+# Fetch dependencies
 flutter pub get
 ```
 
 ### 2. Run the App
-To test the app with full AI performance, run it in **Release Mode**:
+To achieve real-time performance, it is **highly recommended** to run in **Release Mode**:
 ```bash
 flutter run --release
 ```
 
-## 🧪 Testing Instructions
-
-1.  **Launch the App**: Open the app on your device.
-2.  **Select Gallery Analysis**: Tap on the **Analyze Gallery** card.
-3.  **Pick a Photo**: Grant gallery permissions and select a photo of a palm oil bunch.
-4.  **Observe Results**:
-    *   The app will display "Initializing AI..." while processing.
-    *   The detected grade and confidence score will appear.
-    *   🔴 **Health Alert**: If "Empty_Bunch" or "Abnormal" is detected, a red warning box will show.
-5.  **Check History**: Navigate back to the Home screen and select **History Vault** to see your past detections.
-6.  **Re-examine**: Tap on any history card to view the detailed summary.
+---
 
-## 🏗 Project Structure (Flutter Beginner's Guide)
+## 🏗 Project Architecture
 
-As you're new to Flutter, here’s a map of where the important logic lives. All your custom code is inside the `lib/` folder:
+### 📁 `lib/screens/` (UI Layer)
+- **`home_screen.dart`**: Central navigation hub with card-based dashboard.
+- **`live_analysis_screen.dart`**: Advanced camera stream handler with momentum locking logic.
+- **`static_capture_screen.dart`**: Dedicated manual capture workflow with industrial summaries.
+- **`analysis_screen.dart`**: Gallery-based interface with scanning overlays.
+- **`history_screen.dart`**: Secure vault for reviewing past palm records.
 
-### 1. `lib/main.dart`
-The **entry point** of the application. This is where the app theme is defined and the first screen (`HomeScreen`) is launched.
+### 📁 `lib/services/` (Logic Layer)
+- **`tflite_service.dart`**: A persistent Isolate-based service that handles all AI inference (static and stream-based) without blocking the UI thread.
+- **`database_helper.dart`**: Manages the local SQLite database for perpetual history.
 
-### 2. `lib/models/`
-*   **`palm_record.dart`**: Defines the "blueprint" for a detection result. If you want to store more data (like GPS coordinates or weather), you'd add fields here.
+### 📁 `lib/models/` (Data Layer)
+- **`palm_record.dart`**: Schema definition for detection history and bounding box coordinates.
 
-### 3. `lib/services/`
-This folder contains "behind-the-scenes" logic:
-*   **`yolo_service.dart`**: Wraps the AI model. This is where the TFLite model is initialized and where image inference happens.
-*   **`database_helper.dart`**: Manages the local SQLite database (`palm_oil_history.db`). Change this if you need to update the database schema.
+---
 
-### 4. `lib/screens/`
-This is where the **UI** lives:
-*   **`home_screen.dart`**: The main dashboard.
-*   **`analysis_screen.dart`**: The UI for image selection, showing the loading spinner, and displaying the AI results.
-*   **`history_screen.dart`**: The list view for previous records and the detail modal.
+## 📦 Assets
+- `assets/best.tflite`: The YOLO-based ripeness detection model.
+- `assets/labels.txt`: Class definitions (Ripe, Unripe, Underripe, Overripe, Abnormal, Empty_Bunch).
 
-### 5. `assets/`
-Located at the root of the project. This contains your non-code files:
-*   `models/best.tflite`: The trained brain of the app.
-*   `labels/labels.txt`: The names of the classes the model can recognize.
+---
 
-## ⚙️ Configuration
-*   **`pubspec.yaml`**: The project's manifest. This is where you add new dependencies (like camera or GPS plugins) and register new assets.
+## ⚠️ Requirements & Permissions
+- **Camera:** Required for Live and Static analysis.
+- **Storage:** Required to save/load photos and database records.