System Architecture & Core Services
====================================

The WORKVO mobile client is built on **Flutter 3.x** combined with native Android/iOS background service engines, communicating with a containerized Django REST Framework backend powered by high-concurrency SQLite (Write-Ahead Logging mode).

.. contents:: Table of Contents
   :local:
   :depth: 2

Client Architecture Overview
----------------------------
The application follows a reactive, testable Clean Architecture powered by **Riverpod 2.x** and **GoRouter 14.x**:

* **Presentation Layer**: Flutter widgets utilizing adaptive layout containers, safe insets (SDK 35 Edge-to-Edge compliance), and custom visual design system.
* **State Management**: Asynchronous state providers (`AsyncNotifier`, `FutureProvider`) caching offline data and optimistic UI updates.
* **Network & Data Layer**: `Dio 5.x` client with interceptors for token refresh, hardware UUID injection, and query parameter authentication.
* **Storage Layer**: `FlutterSecureStorage` for encrypted JWT tokens and `SharedPreferences` for user session preferences.

Background GPS Telemetry & High-Concurrency Pipeline
----------------------------------------------------
Field sales specialists require continuous tracking without draining device batteries or causing database lockups on the server.

1. **Client-Side Batching**:
   - Location fixes are gathered locally every 15 seconds using fused GPS and network providers.
   - Points are buffered in a local FIFO queue and dispatched in batches of 10-30 points via `POST /api/v1/locations/batch/`.
   - Automatic retry with exponential backoff on intermittent network failure.

2. **Server-Side WAL SQLite Architecture**:
   - The production server uses **SQLite WAL mode** (`PRAGMA journal_mode=WAL; PRAGMA synchronous=NORMAL; PRAGMA busy_timeout=60000;`).
   - Batches are inserted using atomic bulk transactions (`bulk_create`), eliminating N+1 table locks and allowing simultaneous read operations from web dashboards.

OTA CodePush Engine (Shorebird)
-------------------------------
WORKVO embeds the **Shorebird Flutter Engine**, allowing mission-critical bug fixes, UI enhancements, and security patches to be pushed instantly to devices worldwide:

* Boot check on app launch queries Shorebird servers for published patches.
* Background patch download without interrupting the active user session.
* Seamless patch activation on the next application launch.

FCM Push Notification Architecture
----------------------------------
Google Firebase Cloud Messaging (FCM) is configured via `FCMService`:

* **Topic Subscriptions**: `all_employees`, `sales_reps`, `managers_<company_id>`.
* **High-Priority Triggers**: Shift override notices, leave approval/rejection alerts, payslip issuance notifications.
* **Foreground Handling**: Heads-up banner display with direct in-app navigation routes.