Architecture Overview

The Veg Sahayyak SDK is engineered around a clean, decoupled, and framework-agnostic architecture. This ensures high-accuracy telematics processing in background environments without imposing dependency injection frameworks (like Hilt or Koin) onto host applications.

---

🏛️ Modular Design

The SDK is strictly modularized into 5 components to enforce separation of concerns and enable flexible, lightweight B2B integration:

📱

Host Android Application

Commercial Fleet / Logistics / Navigation App

Imports BOM & Consumes SDK

Bill of Materials

Gradle Platform

speed-bom

com.vegsahayyak:speed-bom

Aligns all SDK module versions to prevent runtime ABI mismatches across your dependency tree.

• ✓ Centralized semantic version catalog
• ✓ Guarantees binary compatibility between core and UI
• ✓ Simplifies app gradle dependency blocks

implementation(platform("com.vegsahayyak:speed-bom:2.2.0"))

Headless Engine

Zero UI Coupling

speed-core

com.vegsahayyak:speed-core

Pure Kotlin telematics engine, GPS FusedLocation provider, EMA smoothing, and persistent Foreground Service.

• ✓ High-accuracy FusedLocationProviderClient integration
• ✓ Dual Schmitt Trigger hysteresis (+1 / -3 km/h)
• ✓ ScreenStateWatcher battery-saving GPS throttling
• ✓ StateFlow<SpeedData> reactive state stream

SpeedAssistant.with(context, "YOUR_JWT_LICENSE").setDrivingProfile(DrivingProfile.CarHighway).start()

Compose UI

Jetpack Compose & XML Interop

speed-ui

com.vegsahayyak:speed-ui

OLED-optimized, 60fps hardware-accelerated speedometer dial with dark mode, high contrast, and accessibility.

• ✓ Custom Android Canvas drawing with hardware acceleration
• ✓ Pre-built Dark Gray (OLED) and High Contrast sunlight modes
• ✓ TalkBack & Screen-reader accessibility tokens

SpeedGauge(speed = 78f, warningSpeed = 80f, minSpeedLimit = 40f)

Floating PiP

SYSTEM_ALERT_WINDOW

speed-overlay

com.vegsahayyak:speed-overlay

Lightweight floating Picture-in-Picture window for persistent speed display over third-party navigation apps.

• ✓ Draws over Google Maps and Waze
• ✓ Configurable dimensions and colors
• ✓ Bypasses Activity lifecycles

PipWidget(speed = currentSpeed, unitLabel = "km/h")

Zero-Touch

Activity Recognition

speed-autostart

com.vegsahayyak:speed-autostart

Seamless background trip detection via Google Play Activity Recognition (IN_VEHICLE transitions).

• ✓ Zero continuous GPS polling when parked
• ✓ Preserves battery via hardware sensor hub
• ✓ Bypasses OEM background killers

AutoStartManager.enable(context, onSuccess = { ... })

speed-bom→Manages version alignment for all modules (v2.2.0)

speed-core→100% headless, zero UI or DI dependencies

speed-ui→Jetpack Compose UI, depends on speed-core

speed-overlay→Floating PiP window, depends on speed-core

speed-autostart→Zero-touch Activity Recognition background trip detection

Module Responsibilities

Module	Namespace	Role
speed-core	com.vegsahayyak.speedcore	Headless Engine: Location tracking, TelematicsEngine signal processing, Foreground Service, SpeedColorScheme, persistent preferences, and repository contracts. Crucially, this module is entirely headless and contains zero Jetpack Compose or UI dependencies.
speed-ui	com.vegsahayyak.speedui	Jetpack Compose UI: Production-ready, animated SpeedGauge canvas component, HudDisplay night windshield projection, and SpeedUiColorScheme. All UI rendering is fully delegated here.
speed-overlay	com.vegsahayyak.speedoverlay	Floating PiP Overlay: Lightweight floating Picture-in-Picture window for persistent speed display over third-party navigation apps.
speed-autostart	com.vegsahayyak.speedautostart	Zero-Touch Autostart: Seamless background trip detection via Google Play Activity Recognition (IN_VEHICLE transitions).
speed-bom	com.vegsahayyak.speedbom	Bill of Materials: Aligns module versioning (v2.2.0) so clients never encounter runtime ABI mismatches.

---

🛡️ Native Security & Binary Hardening (libveg_vault.so)

In v2.2.0, critical signal processing algorithms and licensing verification are encapsulated within a compiled Native C++ Library (libveg_vault.so). This provides defense-in-depth protection for commercial enterprise integrations:

• Anti-Tamper & Anti-Reversing: Core telematics logic is protected against Dalvik/ART bytecode decompilation, dynamic hooking, and runtime memory tampering.
• Offline Cryptographic Integrity: High-assurance license validation runs locally on-device, verifying cryptographic signatures without exposing raw mathematical constants or logic to the Java/Kotlin runtime layer.
• Minimal Binary Footprint: Fully stripped to less than 300KB per ABI, preserving the SDK's lightweight footprint with zero impact on host application APK size.

---

🔑 Commercial Enterprise Licensing

The SDK operates exclusively on an offline-first Commercial Enterprise License model, eliminating runtime third-party authentication servers or tracking dependencies:

1. Self-Contained Claims: Your commercial license key is a signed JSON Web Token (JWT) that encodes authorized module entitlements (such as :speed-ui, :speed-overlay, :speed-autostart) and expiration bounds.
2. 100% Offline Execution: All license verification runs locally on-device within the native vault. Fleets and logistics vehicles operate uninterrupted in remote, tunnel, or off-grid environments without periodic server ping requirements.

---

📐 Signal Processing & Telematics Engine

GPS hardware sensors on mobile devices frequently produce velocity noise spikes, multipath signal reflections, and intermittent signal drift (especially in urban canyons or under bridges). The TelematicsEngine in speed-core applies a multi-stage mathematical pipeline before emitting speed updates.

Live TelematicsEngine Mathematics Pipeline

EMA Factor (α): [REDACTED]

[Proprietary Mathematical Model]Trigger: > Upper Limit | Dismiss: < Lower Hysteresis Bound

Timestamp	Raw GPS (Jitter)	EMA Smoothed	Hysteresis State

1. Accuracy Confidence Gating

Raw GPS fixes with an estimated horizontal accuracy greater than our proprietary internal threshold (or missing speed precision) are discarded:

🎯 Gating Rule

Accept GPS Fix IF: horizontalAccuracy <= CONFIDENCE_THRESHOLD (2σ confidence)

When a reading is rejected, the engine emits SpeedData.LowAccuracy, preventing erratic spikes while preserving the last valid smoothed speed.

---

2. Exponential Moving Average (EMA)

To eliminate abrupt needle shaking while retaining immediate responsiveness to actual vehicle acceleration, the engine applies an Exponential Moving Average using proprietary coefficients gated inside libveg_vault.so.

📐 Mathematical Smoothing Formula

SmoothedVelocity[t] = α · RawVelocity[t] + (1 - α) · SmoothedVelocity[t - 1]

• S_t: Smoothed speed at timestamp t (in meters/second).
• Y_t: Raw velocity reading from the GPS provider.
• S_{t-1}: Previous smoothed speed state.
• α: Calibrated weighting coefficient (executed securely inside libveg_vault.so).

---

3. Dual Schmitt Trigger Hysteresis (Max & Min Limits)

A major problem with standard telematics alerting is alarm flutter (e.g. at 80.1 km/h the alarm fires, at 79.9 km/h it shuts off, causing rapid flickering and annoying audio chatter).

The SDK's TelematicsEngine implements a Dual Schmitt Trigger Hysteresis state machine covering both Maximum Speed Limits and Minimum Speed Corridors. These dynamic limits are no longer set manually; they are now automatically fed by the selected DrivingProfile (e.g. CarHighway, EScooter):

⚡ Dual Schmitt Trigger State Machine

Interactive state visualizer: test threshold transitions and hysteresis dampening bands.

✅In Safe Speed Corridor

Current Vehicle Speed:65 km/h

0 (Parked)Min: 40 km/hMax: 80 km/h120 km/h

🅿️

Standby / Parked

Speed ≤ MinLimit (Startup Guard)

↓

Speed > Safe Bound → Arms System

🟢

In Safe Speed Corridor

Normal cruising between 40 km/h — 80 km/h

Trigger: Speed > Upper LimitDismiss: Speed < Lower Hysteresis Bound

🚨

Over-Speed Alert

isOverLimit = true (Red Tones)

Trigger: Speed < Lower LimitDismiss: Speed > Upper Hysteresis Bound

⚠️

Under-Speed Alert

isUnderLimit = true (Amber Tones)

✅

In Safe Speed Corridor

Speed is within the safe driving window. Both alerts are inactive.

isOverLimit: false isUnderLimit: false

A. Maximum Speed Ceiling Hysteresis

• Trigger Threshold: Warning activates when speed exceeds the upper bound limit.
• Dismissal Threshold: Warning deactivates when speed drops below the required hysteresis baseline.
• Result: Sets isOverLimit = true in SpeedData.SpeedChanged.

B. Minimum Speed Corridor Hysteresis

• Startup Safety Guard (hasReachedSafeSpeed): Prevents false under-speed alarms when the vehicle is stationary or starting from a parking stop until it first accelerates past a safe baseline.
• Trigger Threshold: Warning activates when driving speed drops below the corridor floor.
• Dismissal Threshold: Warning deactivates once speed recovers safely into the corridor.
• Result: Sets isUnderLimit = true in SpeedData.SpeedChanged.

---

🔋 Foreground Service & Battery Optimization

Continuous GPS monitoring can drain mobile battery rapidly. The SDK provides advanced power-conservation strategies:

🔋 ScreenStateWatcher & Power Optimization Sequence

Intelligent GPS hardware throttling and display lifecycle management

1

👤

Driver / UserTurns Screen Off

→

ACTION_SCREEN_OFFSystem broadcast dispatched

2

👁️

ScreenStateWatcherBroadcastReceiver

→

isScreenOn = falseNotifies SpeedometerService

3

⚙️

SpeedometerServiceForeground Service

→

🌿 updateWhileScreenOff == false

removeLocationUpdates()

GPS hardware is placed into ultra-low-power sleep. Reduces background battery consumption by up to 68%.

Power Consumption:🌿 ~0.8% battery / hr (Ultra-Low)

Status Bar Update:Cached Vector Numeric Drawable

1. AutoStartManager (:speed-autostart): This is the new recommended strategy for battery optimization. By utilizing Google Play Services IN_VEHICLE transitions, it detects when a trip starts or stops using the low-power sensor hub, bypassing OEM background killers without relying on continuous GPS polling.
2. ScreenStateWatcher: Dynamically observes display state. If the host application configures updateWhileScreenOff = false, the GPS hardware is immediately turned off when the screen sleeps, reducing power consumption by up to 68%.
3. Dynamic Status Bar Icons: Speed is rendered directly into the system status bar as a vector numeric drawable, allowing drivers to monitor speed without keeping the screen active.

---

👉 Next Step: Explore the Core Integration Guide to initialize the SDK and collect live telematics streams.