Skip to content

File Structure

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

📁 File Structure

Full package and directory layout of the Essentials Android project.

Root Project Layout

essentials/
├── app/                            # Main application module
├── build.gradle.kts                # Root build script
├── settings.gradle.kts             # Module settings
├── gradle/                         # Gradle wrapper & version catalog
├── docs/                           # Architecture documentation
│   ├── ARCHITECTURE.md
│   ├── FEATURES_MODULES.md
│   ├── SERVICES_AND_PERMISSIONS.md
│   ├── STRUCTURE.md
│   └── android_settings_reference.md
├── scripts/                        # Development and CI scripts
│   └── validate_strings.py         # String localization validator
├── fastlane/                       # Fastlane deployment (optional)
├── crowdin.yml                     # Crowdin localization config
└── grant_perms.sh                  # ADB permission grant helper script

App Module: Source Layout

app/src/main/java/com/sameerasw/essentials/
│
├── EssentialsApp.kt                # Application class (Sentry init, global state)
├── MainActivity.kt                 # Root Activity — Compose host + navigation
│
├── data/                           # Data layer
│   ├── model/                      # Data classes and DTOs
│   └── repository/
│       ├── SettingsRepository.kt   # SharedPreferences wrapper (Gson JSON)
│       ├── GitHubRepository.kt     # GitHub API calls
│       └── UpdateRepository.kt     # App update tracking
│
├── domain/                         # Business logic layer
│   ├── controller/
│   │   ├── CaffeinateController.kt
│   │   └── StatusBarController.kt
│   ├── model/
│   │   ├── Feature.kt              # Feature abstract base class
│   │   ├── SearchSetting.kt        # Searchable setting model
│   │   └── ...
│   ├── registry/
│   │   ├── FeatureRegistry.kt      # ALL feature definitions (1653 lines)
│   │   ├── PermissionRegistry.kt   # Permission → feature mappings
│   │   └── SearchRegistry.kt       # Global search index
│   ├── diy/                        # DIY automation models
│   ├── genai/                      # GenAI integration
│   ├── watermark/                  # Watermark engine
│   ├── DIYTabs.kt
│   ├── HapticFeedbackType.kt
│   ├── MapsState.kt
│   ├── ScreenOffMethod.kt
│   └── StatusBarIcon.kt
│
├── services/                       # Background services
│   ├── AppDetectionService.kt
│   ├── BatteryNotificationService.kt
│   ├── CaffeinateWakeLockService.kt
│   ├── CalendarSyncManager.kt
│   ├── CalendarSyncWorker.kt
│   ├── DailyWallpaperWorker.kt
│   ├── DeviceInfoSyncManager.kt
│   ├── EssentialsConditionProvider.kt
│   ├── EssentialsWearableListenerService.kt
│   ├── InputEventListenerService.kt
│   ├── LiveWallpaperService.kt
│   ├── LocationReachedService.kt
│   ├── NotificationLightingService.kt
│   ├── NotificationListener.kt     # Main notification listener (~60k lines)
│   ├── ScreenOffWidgetProvider.kt
│   ├── AppUpdateWorker.kt
│   ├── automation/                 # DIY automation engine
│   ├── dreams/                     # Daydream screensaver
│   ├── handlers/                   # Feature-specific event handlers
│   ├── receivers/                  # Broadcast receivers
│   ├── tiles/                      # 33 QS tile services + QsTileRegistry
│   └── widgets/                    # Glance app widgets
│
├── ui/                             # Jetpack Compose UI
│   ├── activities/                 # Sub-activities
│   │   ├── AppLockActivity.kt
│   │   ├── PixelSearchbarSettingsActivity.kt
│   │   ├── WallpaperActivity.kt
│   │   ├── WatermarkActivity.kt
│   │   └── YourAndroidActivity.kt
│   ├── components/                 # Shared composable components
│   ├── composables/                # One-off composable utilities
│   ├── core/
│   │   ├── cards/
│   │   │   ├── IconToggleItem.kt   # Standard toggle row
│   │   │   └── FeatureCard.kt      # Top-level feature card
│   │   ├── containers/
│   │   │   └── RoundedCardContainer.kt
│   │   ├── pickers/
│   │   │   └── SegmentedPicker.kt
│   │   └── sheets/
│   │       └── EssentialsBottomSheet.kt
│   ├── features/                   # Feature-scoped UI modules
│   │   ├── apps/                   # App standby, user dictionary
│   │   ├── audio/                  # ShutUp, sound mode, notification snoozing
│   │   ├── automation/             # DIY rules editor + AI assistant
│   │   ├── battery/                # Battery stats, charging logs
│   │   ├── display/                # Refresh rate, smart pixels, AOD
│   │   ├── freeze/                 # App freezer UI + tags
│   │   ├── hardware/               # Torch, flashlight pulse, button remap
│   │   ├── lighting/               # Notification edge lighting + pickers
│   │   ├── location/               # Geofencing destination cards
│   │   ├── network/                # Private DNS, network modes
│   │   ├── power/                  # Caffeinate, battery notification, Maps
│   │   ├── security/               # AppLock, RemoteLock, screen locked
│   │   ├── system/                 # Status bar, animations, lock screen
│   │   ├── tiles/                  # QS tile manager UI
│   │   ├── wallpaper/              # Live wallpaper controls
│   │   ├── watch/                  # WearOS companion UI
│   │   └── watermark/              # Watermark engine UI
│   ├── ime/                        # Keyboard (IME) extension composables
│   ├── modifiers/                  # Compose modifier extensions
│   ├── state/                      # Compose state holders
│   └── theme/                      # Material 3 theming, pitch black AMOLED
│
├── utils/                          # Utility helpers
│   ├── battery/                    # Battery ring drawer, history log
│   ├── hardware/                   # SurfaceFlinger, refresh rate, torch
│   ├── security/                   # Shizuku binder, Root shell, Biometric
│   └── ui/                         # HapticUtil, ColorUtil, permission guidance
│       ├── HapticUtil.kt           # Haptic feedback helper
│       ├── ColorUtil.kt            # Pastel/vibrant color generation
│       └── ...
│
└── viewmodels/                     # Domain ViewModels
    ├── MainViewModel.kt            # Root state coordinator
    ├── PermissionViewModel.kt
    ├── SettingsViewModel.kt
    ├── SecurityViewModel.kt
    ├── BatteryViewModel.kt
    ├── QuickSettingsTilesViewModel.kt
    ├── StatusBarIconViewModel.kt
    ├── AppUpdatesViewModel.kt
    ├── CaffeinateViewModel.kt
    ├── DIYViewModel.kt
    ├── LocationReachedViewModel.kt
    ├── WatchViewModel.kt
    ├── WatermarkViewModel.kt
    └── GitHubAuthViewModel.kt

Resources Layout

app/src/main/res/
├── drawable/           # Vector drawables (rounded_* icons)
├── raw/                # Lottie animation JSON files
│   ├── sound_animation.json
│   ├── aod_animation.json
│   ├── flash_animation.json
│   ├── lighting_animation.json
│   └── ...
├── values/
│   ├── strings.xml     # All English strings
│   ├── arrays.xml      # Keyword arrays for search
│   └── ...
└── values-*/           # Localized translations (Crowdin-managed)

Manifest Key Components

Declared in AndroidManifest.xml:

  • ScreenOffAccessibilityService — accessibility service
  • NotificationListener — notification listener service
  • CaffeinateWakeLockService — foreground service
  • All 33 QS tile services
  • ScreenOffWidgetProvider — app widget
  • EssentialsWearableListenerService — Wearable listener
  • EssentialsConditionProvider — condition provider
  • LiveWallpaperService — live wallpaper
  • All broadcast receivers

Grant Permissions Script

The grant_perms.sh script at the project root automates ADB permission grants for development:

./grant_perms.sh    # grants WRITE_SECURE_SETTINGS and other ADB-granted permissions

Clone this wiki locally