Skip to content

Architecture

Jump to bottom
sameerasw edited this page Aug 9, 2026 · 1 revision

🏗️ Architecture

Essentials follows an MVVM (Model-View-ViewModel) architectural pattern layered over a Feature-Based Modular Architecture.

High-Level Architecture

┌──────────────────────────────────────────┐
│           Jetpack Compose UI             │
│  (MainActivity, Feature Screens, Sheets) │
└───────────────────┬──────────────────────┘
                    │ observes state
                    ▼
┌──────────────────────────────────────────┐
│              ViewModels Layer            │
│  (MainViewModel, PermissionViewModel,    │
│   BatteryViewModel, DIYViewModel, ...)   │
└───────┬──────────────────┬──────────────┘
        │ reads/writes      │ delegates
        ▼                   ▼
┌────────────────┐  ┌────────────────────┐
│  Repositories  │  │ Domain Controllers │
│  (Settings,    │  │ (Caffeinate,       │
│   GitHub, etc) │  │  StatusBar, etc.)  │
└───────┬────────┘  └────────────────────┘
        │
        ▼
┌──────────────────────────────────────────┐
│     Storage / System APIs                │
│  SharedPreferences  │  Secure Settings   │
│  Sysfs              │  Shell (Shizuku/su)│
└──────────────────────────────────────────┘
        ▲
┌───────┴──────────────────────────────────┐
│        Background Services               │
│  (NotificationListener, Accessibility,  │
│   WorkerManager, Tile Services)          │
└──────────────────────────────────────────┘

ViewModels

State is split across domain-specific ViewModels to avoid a monolithic MainViewModel:

ViewModel Responsibilities
MainViewModel Root state coordinator — delegates to sub-ViewModels
PermissionViewModel Tracks all permission states (WRITE_SECURE_SETTINGS, Shizuku, Accessibility, Overlay, etc.)
SettingsViewModel App preferences, default tabs, pinned features, QS tile order
SecurityViewModel App lock biometric, remote lock, screen locked security
BatteryViewModel Battery statistics, charging state logs, ring cutout overlays, Maps power saving
QuickSettingsTilesViewModel QS tile active states and tile customization
StatusBarIconViewModel Status bar icon blacklist (icon_blacklist), Smart Wi-Fi/Data auto-hiding
AppUpdatesViewModel GitHub release tracking, APK download management
DIYViewModel Automation rules, action execution, GenAI prompt generator
WatermarkViewModel Photo watermark engine, EXIF parsing, image processing
CaffeinateViewModel Screen awake timer state management
LocationReachedViewModel GPS geofencing destination state
WatchViewModel WearOS companion sync state
GitHubAuthViewModel GitHub OAuth device flow

Data Layer

SettingsRepository

The central persistence layer wrapping SharedPreferences (essentials_prefs):

  • Uses Gson for JSON serialization of complex types (sets, lists, maps)
  • Provides typed read/write helpers (getString, getBoolean, getInt, getSet)
  • Feature settings keys are defined as KEY_* constants in the repository class

GitHubRepository

Handles GitHub REST API calls for release checking and OAuth.

System Settings Interoperability

  • WRITE_SECURE_SETTINGS — Used to modify Settings.Secure values (AOD, refresh rate, icon blacklist, etc.)
  • WRITE_SETTINGS — Used to modify Settings.System (animation scales, font scale, brightness mode)
  • Shizuku/Root Shell — Used for privileged pm commands, dumpsys queries, and sysfs node writes

Feature Registry System

Features are defined as anonymous object : Feature(...) instances in FeatureRegistry.ALL_FEATURES.

Each feature declares:

  • id — Unique string key
  • title — String resource
  • category — Category string resource
  • description / aboutDescription — UI text
  • permissionKeys — Which permission keys are required (mapped via PermissionRegistry)
  • parentFeatureId — Optional parent for nested feature groups
  • showToggle / hasMoreSettings / isVisibleInMain — UI display flags
  • animationRes — Optional Lottie animation for the detail screen
  • isDeviceSupported() — Device compatibility check (e.g., Pixel-only features)

See Feature-Registry for implementation details.

Service Architecture

Background services are structured into distinct responsibilities:

services/
├── NotificationListener.kt        — Monitors all notifications (60k+ lines of logic)
├── ScreenOffAccessibilityService  — Master accessibility service for all screen/key events
├── CaffeinateWakeLockService       — Foreground wake lock service
├── BatteryNotificationService     — Monitors battery events for all devices
├── LocationReachedService          — Background GPS geofence monitoring
├── NotificationLightingService     — Renders edge lighting overlays
├── CalendarSyncManager             — WearOS calendar data sync
├── DeviceInfoSyncManager           — Sends device state to WearOS
├── EssentialsWearableListenerService — Receives commands from WearOS
├── InputEventListenerService       — Hardware button event capture
├── LiveWallpaperService            — Live wallpaper rendering engine
├── automation/                     — DIY rule evaluation and execution
├── dreams/                         — Screensaver/Daydream service
├── handlers/                       — Specialized event handlers
├── receivers/                      — Broadcast receivers
├── tiles/                          — 33 QS tile service implementations
└── widgets/                        — Glance widget providers

UI Architecture

The UI is built entirely in Jetpack Compose using Material 3 Expressive components:

  • MainActivity — Root host for all Compose content
  • Feature screens are composable functions organized by feature area in ui/features/
  • Bottom sheets (ModalBottomSheet) for sub-settings and pickers
  • Core components in ui/core/ are reused across all features:
    • RoundedCardContainer — groups related settings
    • IconToggleItem — standard setting row with icon + switch
    • FeatureCard — top-level feature discovery card with pastel icon
    • SegmentedPicker — connected button group for mode selection
    • EssentialsBottomSheet — standard bottom sheet wrapper

Localization

String resources are managed via strings.xml with Crowdin integration for community translations. The crowdin.yml file defines the Crowdin project sync configuration.

Validation script:

python3 scripts/validate_strings.py        # Check for errors
python3 scripts/validate_strings.py --fix  # Auto-fix quote escaping

Clone this wiki locally