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).

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.