[Website] Update docs website and README to reflect all project features and BLE Zero-read protocol

Author: CreatorJohn

README.md

@@ -1,101 +1,127 @@
 # Off Chat: A Decentralized Digital Concierge
 ### Bachelor Thesis Project | CTU FEE, Prague
 
-**Off Chat** is an offline-first, peer-to-peer communication platform built with Flutter. It utilizes Bluetooth Low Energy (BLE) to enable device discovery, relative location tracking (Radar), and secure messaging without any reliance on internet or cellular connectivity.
+**Off Chat** is an offline-first, peer-to-peer decentralized communication platform built with Flutter. It utilizes Bluetooth Low Energy (BLE) to enable instant device discovery, relative location tracking (Radar), and secure messaging without any reliance on internet, cellular connectivity, or central infrastructure.
 
-This project was developed as part of a Bachelor Thesis at the **Czech Technical University in Prague (CTU), Faculty of Electrical Engineering (FEE)**.
+This project was developed as part of a Bachelor Thesis in Open Informatics at the **Czech Technical University in Prague (CTU), Faculty of Electrical Engineering (FEE)**.
 
 ---
 
 ## 🌟 Key Features
 
-- **The Nodes (Discovery):** Real-time scanning of nearby active devices. Displays user profiles (avatar, alias) and proximity metadata.
-- **The Radar (Location):** A custom-painted visualization showing the relative bearing and distance of peers using a combination of GPS coordinates and device compass data.
-- **Off-Grid Messaging:** Reliable text and media exchange (images up to 512x512) over BLE GATT characteristics.
-- **Identity Protocol:** Secure local profile management with automated image compression and background synchronization.
-- **Aurelian Noir Aesthetic:** A premium "Digital Concierge" design system featuring deep black surfaces, gold primary accents, and fluid geometry.
+### 📡 Zero-read Identification Protocol
+- **Instant Discovery:** Avoids the high overhead of establishing GATT connections for simple identification. Nearby active devices are discovered and verified immediately upon capturing a single advertisement packet.
+- **Cache-Hit Proximity:** If a peer's `stableId` is already cached locally and their `versionTag` hasn't changed, they are instantly visualized on the radar without any active radio transmission.
+
+### 🗺️ Custom-Painted Location Radar
+- **Relative Proximity Canvas:** A gorgeous, custom-painted radar visualization showing the relative bearing and distance of peers in real-time.
+- **Sensor Fusion:** Merges high-precision GPS coordinates from the `geolocator` package with active compass data from `flutter_compass` to correctly rotate and render neighboring nodes relative to the user's orientation.
+
+### ⚡ Dual-role Mesh Topography (Store & Forward)
+- **Central + Peripheral:** Each device runs simultaneous BLE Central (scanning/connecting) and BLE Peripheral (advertising/serving) roles using coordinated asynchronous timers.
+- **Background Persistence:** Utilizes a dedicated foreground service isolate on Android to ensure continuous mesh operations and location updates, even when the OS is under heavy memory pressure.
+
+### 🛣️ Intelligent Mesh Routing Engines
+- **Directed Beam Routing (Geographic LAR):** When geographic locations are available, the app calculates a weighted *Forwarding Score* based on angular deviation (bearing via sférická trigonometrie) and RSSI signal strength. Messages are selectively routed towards the destination, reducing radio traffic by up to 65%.
+- **Starburst Routing (Flooding):** Used as a fallback when geographic data is unavailable. Floods the network with a strict 10-hop Time-To-Live (TTL) limit and duplicate message deduplication via local cache.
+- **Breadcrumb ACK Tracking:** ACKs travel back along the reversed paths of the messages, updating delivery states deterministically.
+
+### 🛡️ End-to-End Cryptography (Security Level 4)
+- **Key Exchange:** Secure, local key exchange using **X25519 Diffie-Hellman** curves during first-contact synchronization.
+- **Symmetric Encryption:** All subsequent message payloads are encrypted end-to-end using **ChaCha20-Poly1305 AEAD** to ensure confidentiality, integrity, and authenticity.
+
+### 📦 Chunked Transfer Engine
+- **Dynamic MTU Adaptation:** An abstract chunking protocol that dynamically resizes data chunks (from standard 23 bytes up to 512 bytes) based on MTU values negotiated during connection.
+- **Profile Synchronization:** Seamlessly streams and reconstructs larger data files, such as custom profile pictures, over BLE GATT characteristics.
+
+### 🎨 Aurelian Noir Aesthetics
+- **Digital Concierge Style:** Premium dark UI designed to feel prestigious and elegant.
+- **Visual Palette:** Deep obsidian black background surfaces (`#131313`) with subtle textures, radiant gold accents (`#F2CA50`), fluid glassmorphic cards, custom typography (Plus Jakarta Sans/Outfit), and smooth bento-grid layouts.
 
 ---
 
 ## 🏗 Architecture
 
-The project follows a **Feature-First Architecture**, ensuring high cohesion and low coupling between modules. Each feature is self-contained with its own Presentation, Domain, and Data layers.
+The project follows a rigorous **Domain-Driven Design (DDD) Feature-First Architecture**, keeping features modular, highly cohesive, and loosely coupled.
 
 ```text
 lib/src/
 ├── features/
-│   ├── onboarding/   # Multi-step security & setup protocol
-│   ├── discovery/    # BLE Scanning & Peer management
-│   ├── location/     # Radar math, Compass, & UI Canvas
-│   ├── profile/      # Local identity & Settings
-│   └── chat/         # Messaging logic & Media chunking
+│   ├── onboarding/   # Multi-step onboarding, profile setup & key generation
+│   ├── discovery/    # BLE Discovery engine, scan loop, and Sync Queue
+│   ├── location/     # Radar math, Compass sensors, & CustomPaint Canvas
+│   ├── profile/      # Local identity, settings & System Health Bento Grid
+│   └── chat/         # Messaging handler, encryption, & ChunkedTransferManager
 ├── core/
-│   ├── routing/      # Reactive GoRouter with Onboarding protection
-│   ├── theme/        # Centralized Aurelian Noir ThemeData
-│   ├── database/     # Isar local persistence layer
-│   └── notifications/# Local background alerts
+│   ├── routing/      # Reactive GoRouter with state guards
+│   ├── theme/        # Centralized Aurelian Noir ThemeData & app tokens
+│   ├── database/     # Isar local database collections (FoundDevice, Message, RelayTask)
+│   └── notifications/# Background local notification service
 └── app.dart          # Root Material application
 ```
 
 ---
 
-## 🛰 The Off-Chat Protocol
+## 🛰 The Off-Chat BLE Protocol
+
+To overcome BLE advertisement limits (31 bytes) and iOS background constraints, Off Chat splits data transmission between the primary packet and the scan response.
 
-To overcome standard BLE advertisement limits (31 bytes) and iOS background restrictions, this project implements a **Hybrid Discovery Strategy**:
+### 1. Primary Advertisement Packet (Main Packet — Exactly 5 Bytes)
+Packs critical identity data tightly at the byte-level:
+- **Bytes 0-3:** `Stable Device ID` (32-bit big-endian unsigned integer).
+- **Byte 4:** Combined byte consisting of:
+  - **Bits 7-2 (6 bits):** `Version Tag` (First 6 bits of the Profile Hash) to detect profile changes instantly.
+  - **Bit 1 (1 bit):** Platform Flag (`1` for iOS, `0` for Android).
+  - **Bit 0 (1 bit):** Online Status Flag (`1` if acting as an Internet Bridge, `0` if offline).
 
-### 1. The 13-Byte Payload
-We pack essential metadata into a byte-level structure to fit within Manufacturer Data:
-- **Byte 0:** Flags (Platform: Android/iOS, Visibility: Enabled/Disabled).
-- **Bytes 1-4:** Profile Hash (Deterministic CRC32 of username/avatar).
-- **Bytes 5-8:** Latitude (Float32).
-- **Bytes 9-12:** Longitude (Float32).
+### 2. Scan Response Packet (12 Bytes)
+Dispatched only when requested by active scanners to conserve battery:
+- **Bytes 0-2 (24 bits):** `Latitude` compressed to a 24-bit fixed-point integer.
+- **Bytes 3-5 (24 bits):** `Longitude` compressed to a 24-bit fixed-point integer.
+- **Bytes 6-11 (6 bytes):** `Full Profile Hash` for cryptographically verifying user identity.
 
-### 2. Hybrid Strategy
-- **Primary Advertisement:** Broadcasts only the Service UUID and essential flags to minimize packet size and maximize discovery reliability (especially for iOS background).
-- **Scan Response:** The 13-byte custom metadata is moved to the Scan Response packet.
-- **Local Name:** Disabled to free up primary advertisement bandwidth.
-- **Background (iOS):** When Scan Response data is stripped by the OS, the app initiates a **silent GATT connection** to read the "Identity Characteristic," fetching the 13-byte payload before disconnecting.
+### 3. iOS Background Fallback
+iOS strips Manufacturer Data from advertisement packets when in the background. Off Chat handles this gracefully:
+- When a background node is detected without manufacturer data, the Central node initiates a **silent GATT connection** to read the designated `identityCharUuid` characteristic.
+- It extracts the same 5-byte and 12-byte metadata blocks and disconnects immediately, preserving battery.
 
-### 3. Intelligent Motion (Flight Mode)
-To ensure stability in high-speed environments (airplanes, fast trains), the protocol implements **Adaptive Throttling**:
-- **Normal Mode (< 72 km/h):** Updates location and restarts advertising every **10 meters**.
-- **High-Speed Mode (≥ 72 km/h):** Switches to a stable **2-minute timer**, ignoring distance changes. This prevents rapid Bluetooth stack resets and allows peers a reliable window to connect.
-- **Heartbeat:** Forced update every **5 minutes** even if the device is stationary.
+### 4. Throttled Heartbeat (Energy Conservation)
+Continuous scanning and advertising is resource-heavy. Off Chat utilizes **Adaptive Throttling**:
+- **Stationary State:** If the user is sitting still, the advertiser sleeps and restarts advertising only every **300 seconds** (Heartbeat) to maintain connection tables.
+- **Motion State:** When a change of **111 meters** or movement from physical sensors is detected, advertising rates instantly spike to maximum frequency to facilitate rapid handshake loops.
 
 ---
 
 ## 🛠 Tech Stack & Dependencies
 
 - **Framework:** Flutter (Dart)
-- **State Management:** Riverpod (Generator & Annotation)
-- **Navigation:** GoRouter
-- **Database:** Isar (NoSQL)
-- **Communication:** `flutter_blue_plus` (Client) & `ble_peripheral` (Server)
-- **Permissions:** `permission_handler` (Runtime Android 12+ BLE/Location support)
-- **Logging:** `logging` (Structured output for debugging)
-- **Sensors:** `geolocator` (GPS) & `flutter_compass`
-- **Design:** Google Fonts (Plus Jakarta Sans)
+- **State Management:** Riverpod (Generator, Annotations, and AsyncNotifiers)
+- **Database:** Isar (High-performance, asynchronous NoSQL database)
+- **BLE Communication:** `flutter_blue_plus` (Central scanner) & `ble_peripheral` (Peripheral server)
+- **Security:** `cryptography` (X25519 for key exchange, ChaCha20-Poly1305 for AEAD encryption)
+- **Sensors:** `geolocator` (GPS coordinates) & `flutter_compass` (Compass heading)
+- **Aesthetics:** Google Fonts (Outfit & Plus Jakarta Sans)
 
 ---
 
 ## 🚀 Getting Started
 
 ### Prerequisites
-- Flutter SDK (Latest Stable)
-- Two physical devices **OR** Android Emulators with **Netsim** enabled.
-- Android 12+ (API 31) for full BLE Advertising/Scanning support.
+- Flutter SDK (version 3.11.1 or newer stable)
+- Two physical Android/iOS devices (ideal for BLE testing) **OR** Android Emulators with **Netsim** configured.
+- Android 12+ (API 31) for required Nearby Devices runtime permissions.
 
 ### Installation
-1. Clone the repository.
-2. Install dependencies:
+1. Clone this repository.
+2. Fetch Dart packages:
    ```bash
    flutter pub get
    ```
-3. Run code generation (required for Riverpod and Isar):
+3. Generate required database schemas and Riverpod annotations:
    ```bash
    dart run build_runner build --delete-conflicting-outputs
    ```
-4. Deploy to a device:
+4. Run the application:
    ```bash
    flutter run
    ```
@@ -104,27 +130,20 @@ To ensure stability in high-speed environments (airplanes, fast trains), the pro
 
 ## 🧪 Testing & Verification
 
-### Developer Terminal (In-App)
-A hidden debug console is available for real-time monitoring of BLE status and system logs:
-1.  Navigate to the **Discovery (Home)** screen.
-2.  **Triple-tap** the "OFFCHAT" logo in the header.
-3.  The terminal displays the last 200 logs with color-coded severity levels.
-
-### Multi-Emulator Testing (Netsim)
-You can test BLE discovery and GATT sync locally using **Netsim** (Android Network Simulator):
-1. Launch two Android emulators (API 31+).
-2. Ensure Netsim is enabled in emulator settings.
-3. Open the Netsim GUI: `http://localhost:7681/gui` to manage device proximity and signal strength.
-
-### Continuous Integration
-A GitHub Action is configured to build release artifacts on every push to `master`.
-- **APK:** `off-chat-release.apk`
-- **App Bundle:** `off-chat-release.aab`
-Builds are pushed automatically to the `android` branch for deployment.
-
-### Automated Checks
-The project strictly follows Dart style guidelines (lowerCamelCase constants, no `print` in production).
-Verify code quality and run tests:
+### 💻 Developer Console (In-App Terminal)
+A hidden debug console is built directly into the UI for real-time mesh monitoring:
+1. Navigate to the **Discovery (Home)** screen.
+2. **Triple-tap** the `OFFCHAT` logo in the top AppBar.
+3. A developer terminal overlay opens, showing the last 200 console logs with color-coded severity levels (Severe, Info, Warning).
+
+### 🌐 Proximity Simulation (Netsim)
+Test mesh routing and discovery on a single machine:
+1. Launch two Android Emulators (API 31+).
+2. Open the **Netsim GUI** in your browser: `http://localhost:7681/gui`
+3. Drag the virtual devices closer or further apart to simulate RSSI changes, range limits, and connection handshakes.
+
+### 🧹 Quality Checks & Verification
+The project maintains absolute style guidelines. Check for linting issues and run tests:
 ```bash
 flutter analyze
 flutter test