Architecture & Code Standards

These guidelines define the structural rules and engineering standards for the Veg Sahayyak SDK codebase. AI agents and developers must adhere to these standards to maintain a clean, testable, and scalable modular architecture.

---

1. Modular Architecture Boundaries

The repository is organized into distinct Gradle modules with strict boundaries:

• :speed-core (Headless Telematics Engine)
  • Responsibility: Mathematical signal processing (TelematicsEngine), Fused Location polling (SpeedWatcher), SpeedColorScheme, and foreground service lifecycle (SpeedometerService).
  • Rules: CRITICAL: Jetpack Compose dependencies (e.g., androidx.compose.ui) must never leak into :speed-core. Minimal third-party footprint (only Google Play Services Location and Coroutines). Does not force DI frameworks on consuming clients.
• :speed-ui (Jetpack Compose Visual Layer)
  • Responsibility: Hardware-accelerated canvas speedometer (SpeedGauge), HUD digital display (HudDisplay), windshield reflection modifiers (Modifier.hudMirror), accessibility semantics, and automotive themes (SpeedUiColorScheme).
  • Rules: Depends on :speed-core and Jetpack Compose. No direct Android framework storage or location polling.
• :speed-overlay (Floating PiP Overlay Widget)
  • Responsibility: Lightweight floating Picture-in-Picture window (PipWidget) for persistent speed display over third-party navigation apps.
  • Rules: Optional plugin module. Decoupled from core logic.
• :speed-autostart (Zero-Touch Autostart Plugin)
  • Responsibility: Background trip detection (AutoStartManager) via Google Play Activity Recognition (IN_VEHICLE transitions).
  • Rules: Optional plugin module. Zero runtime overhead for clients not needing automatic drive detection.
• :speed-bom (Bill of Materials)
  • Responsibility: Gradle platform artifact enforcing version alignment across SDK modules.
• :app (Sample / Demo Application)
  • Responsibility: End-to-end integration demo showing SpeedAssistant usage in real-world Activity, Compose, and Hilt environments.

---

2. Dependency Injection Strategy

• SDK Modules (:speed-core, :speed-ui):
  • Employs a lightweight internal service locator (SpeedCoreInternal) to avoid imposing heavy DI frameworks on consuming clients.
  • Public interfaces (ISpeedRepository, IPreferenceRepository) can be overridden at runtime via SpeedAssistant.useRepository() or SpeedAssistant.usePreferenceRepository().
• Sample App (:app):
  • Hilt is used for sample app dependency injection.
  • Test modules use @TestInstallIn to bind test doubles (e.g. FakeSpeedRepository).

---

3. UI Framework: Jetpack Compose

• New Features: All new UI must be written in Jetpack Compose.
• Canvas Rendering: Automotive gauges must use hardware-accelerated Compose Canvas drawing with precomputed trigonometric lookup tables and tokens.
• State Hoisting: UIs should be stateless. Hoist state to callers using StateFlow<SpeedData>.
• Naming: Composable functions must be PascalCase and annotated with @Composable (e.g., SpeedGauge, GaugeNeedle).

---

4. State Management & Concurrency

• Use Kotlin Coroutines and Flows.
• Expose state streams using Flow<SpeedData> or StateFlow.
• Thread boundary rules:
  • Location event handling and mathematical filtering run on Dispatchers.Default.
  • Service lifecycle and notification updates run on Dispatchers.Main.immediate.

---

5. Coding Conventions

• Language: Kotlin only (Kotlin 1.9+ / 2.0+).
• Formatting: Adhere to standard ktlint and detekt guidelines.
• Null Safety: Avoid !! (not-null assertions). Use safe calls (?.) or Elvis operators (?:).
• Data Classes: Use data class for immutable state models (SpeedData.SpeedChanged, TelematicsResult).
• Early-Exits (Guard Clauses): Return early in validation logic instead of deeply nesting code inside if statements.
• DRY & KISS: Extract repeated mathematical conversions into SpeedUnit and domain extensions.
• Meaningful KDoc: Document mathematical constants (e.g., alpha EMA factor, Schmitt trigger delta values) and unit expectations on all public APIs.