# sameerasw/essentials architecture

> Architecture diagram of the GitHub repository sameerasw/essentials, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sameerasw/essentials
- Repository: https://github.com/sameerasw/essentials

## Overview

Essentials is an Android utility and system-customization app for Pixel and other Android devices. Users configure features in the app or invoke them through system surfaces such as Quick Settings, widgets, shortcuts, accessibility, and voice search; app services and handlers then apply the requested device behavior. Major branches include DIY automation, the Island overlay, search and keyboard tools, and image watermarking. The README documents Shizuku/root support for advanced commands. Several feature paths are supported by the tree and README, but their internal wiring was not sampled, so those links are intentionally not inferred.

Main entry points: [`app/src/main/java/com/sameerasw/essentials/services/handlers`](https://github.com/sameerasw/essentials/tree/main/app/src/main/java/com/sameerasw/essentials/services/handlers) (System handlers), [`app/src/main/java/com/sameerasw/essentials/services/automation/AutomationManager.kt`](https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/services/automation/AutomationManager.kt) (Automation manager), [`app/src/main/java/com/sameerasw/essentials/appfunctions/BaseEssentialsAppFunctionService.kt`](https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/appfunctions/BaseEssentialsAppFunctionService.kt) (Assistant functions), [`app/src/main/java/com/sameerasw/essentials/island/service/IslandCoordinator.kt`](https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/island/service/IslandCoordinator.kt) (Island coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App experience"]
  node_ui["Feature screens"]
  node_settings[("Settings storage")]
end

subgraph group_device["Device features"]
  node_quicktiles["Quick Settings tiles"]
  node_widgets["Home widgets"]
  node_accessibility["Accessibility service"]
  node_handlers["System handlers"]
end

subgraph group_automation["Automation"]
  node_automation_editor["Automation editor"]
  node_automation_service["Automation service"]
  node_automation_manager["Automation manager"]
  node_automation_modules["Trigger modules"]
  node_automation_actions["Action executors"]
  node_diy["DIY automation model"]
  node_appfunctions["Assistant functions"]
end

subgraph group_island["Island overlay"]
  node_island_service["Island coordinator"]
  node_island_plugins["Island plugins"]
  node_island_ui["Island presentation<br/>[IslandRoot.kt]"]
end

subgraph group_tools["Search and tools"]
  node_search_results["Pixel search results"]
  node_voice_session["Voice search session"]
  node_keyboard["Essentials keyboard"]
  node_suggestions["Suggestion engine"]
  node_watermark["Image watermarking<br/>[WatermarkEngine.kt]"]
end

node_person(("Device user"))
node_shell(("Shizuku or root"))
node_android(("Android system"))
node_image_user(("Image creator"))

node_person -->|"configures features"| node_ui
node_ui -->|"reads and writes"| node_settings
node_person -->|"invokes controls"| node_quicktiles
node_person -->|"uses widgets"| node_widgets
node_person -->|"enables service"| node_accessibility
node_accessibility -->|"initializes handlers"| node_handlers
node_quicktiles -->|"controls device"| node_android
node_handlers -->|"applies behavior"| node_android
node_handlers -.->|"advanced commands"| node_shell
node_person -->|"creates automation"| node_automation_editor
node_automation_editor -->|"stores automation"| node_diy
node_automation_service -->|"connects service"| node_automation_manager
node_automation_manager -->|"starts modules"| node_automation_modules
node_automation_manager -->|"dispatches actions"| node_automation_actions
node_appfunctions -->|"executes device actions"| node_automation_actions
node_appfunctions -->|"adds automation"| node_diy
node_android -->|"starts service"| node_automation_service
node_island_service -->|"coordinates plugins"| node_island_plugins
node_island_service -->|"hosts overlay"| node_island_ui
node_android -->|"invokes assistant"| node_voice_session
node_voice_session -->|"launches results"| node_search_results
node_person -->|"types text"| node_keyboard
node_keyboard -->|"requests suggestions"| node_suggestions
node_image_user -->|"processes image"| node_watermark

click node_ui "https://github.com/sameerasw/essentials/tree/main/app/src/main/java/com/sameerasw/essentials/ui/activities"
click node_settings "https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/data/repository/SettingsRepository.kt"
click node_quicktiles "https://github.com/sameerasw/essentials/tree/main/app/src/main/java/com/sameerasw/essentials/services/tiles"
click node_widgets "https://github.com/sameerasw/essentials/tree/main/app/src/main/java/com/sameerasw/essentials/services/widgets"
click node_accessibility "https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/services/tiles/ScreenOffAccessibilityService.kt"
click node_handlers "https://github.com/sameerasw/essentials/tree/main/app/src/main/java/com/sameerasw/essentials/services/handlers"
click node_automation_editor "https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/ui/activities/AutomationEditorActivity.kt"
click node_automation_service "https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/services/automation/AutomationService.kt"
click node_automation_manager "https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/services/automation/AutomationManager.kt"
click node_automation_modules "https://github.com/sameerasw/essentials/tree/main/app/src/main/java/com/sameerasw/essentials/services/automation/modules"
click node_automation_actions "https://github.com/sameerasw/essentials/tree/main/app/src/main/java/com/sameerasw/essentials/services/automation/executors"
click node_diy "https://github.com/sameerasw/essentials/tree/main/app/src/main/java/com/sameerasw/essentials/domain/diy"
click node_appfunctions "https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/appfunctions/BaseEssentialsAppFunctionService.kt"
click node_island_service "https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/island/service/IslandCoordinator.kt"
click node_island_plugins "https://github.com/sameerasw/essentials/tree/main/app/src/main/java/com/sameerasw/essentials/island/plugins"
click node_island_ui "https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/island/ui/IslandRoot.kt"
click node_search_results "https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/ui/activities/PixelSearchResultsActivity.kt"
click node_voice_session "https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/services/EssentialsVoiceInteractionSessionService.kt"
click node_keyboard "https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/ime/EssentialsInputMethodService.kt"
click node_suggestions "https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/ime/SuggestionEngine.kt"
click node_watermark "https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/domain/watermark/WatermarkEngine.kt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ui,node_settings,node_person toneBlue
class node_quicktiles,node_widgets,node_accessibility,node_handlers toneAmber
class node_automation_editor,node_automation_service,node_automation_manager,node_automation_modules,node_automation_actions,node_diy,node_appfunctions toneMint
class node_island_service,node_island_plugins,node_island_ui toneRose
class node_search_results,node_voice_session,node_keyboard,node_suggestions,node_watermark,node_shell,node_android,node_image_user toneIndigo
```

## Components

### App experience

- [Feature screens](https://github.com/sameerasw/essentials/tree/main/app/src/main/java/com/sameerasw/essentials/ui/activities): `app/src/main/java/com/sameerasw/essentials/ui/activities`
- [Settings storage](https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/data/repository/SettingsRepository.kt): `app/src/main/java/com/sameerasw/essentials/data/repository/SettingsRepository.kt`

### Device features

- [Quick Settings tiles](https://github.com/sameerasw/essentials/tree/main/app/src/main/java/com/sameerasw/essentials/services/tiles): `app/src/main/java/com/sameerasw/essentials/services/tiles`
- [Home widgets](https://github.com/sameerasw/essentials/tree/main/app/src/main/java/com/sameerasw/essentials/services/widgets): `app/src/main/java/com/sameerasw/essentials/services/widgets`
- [Accessibility service](https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/services/tiles/ScreenOffAccessibilityService.kt): `app/src/main/java/com/sameerasw/essentials/services/tiles/ScreenOffAccessibilityService.kt`
- [System handlers](https://github.com/sameerasw/essentials/tree/main/app/src/main/java/com/sameerasw/essentials/services/handlers): `app/src/main/java/com/sameerasw/essentials/services/handlers`

### Automation

- [Automation editor](https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/ui/activities/AutomationEditorActivity.kt): `app/src/main/java/com/sameerasw/essentials/ui/activities/AutomationEditorActivity.kt`
- [Automation service](https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/services/automation/AutomationService.kt): `app/src/main/java/com/sameerasw/essentials/services/automation/AutomationService.kt`
- [Automation manager](https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/services/automation/AutomationManager.kt): `app/src/main/java/com/sameerasw/essentials/services/automation/AutomationManager.kt`
- [Trigger modules](https://github.com/sameerasw/essentials/tree/main/app/src/main/java/com/sameerasw/essentials/services/automation/modules): `app/src/main/java/com/sameerasw/essentials/services/automation/modules`
- [Action executors](https://github.com/sameerasw/essentials/tree/main/app/src/main/java/com/sameerasw/essentials/services/automation/executors): `app/src/main/java/com/sameerasw/essentials/services/automation/executors`
- [DIY automation model](https://github.com/sameerasw/essentials/tree/main/app/src/main/java/com/sameerasw/essentials/domain/diy): `app/src/main/java/com/sameerasw/essentials/domain/diy`
- [Assistant functions](https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/appfunctions/BaseEssentialsAppFunctionService.kt): `app/src/main/java/com/sameerasw/essentials/appfunctions/BaseEssentialsAppFunctionService.kt`

### Island overlay

- [Island coordinator](https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/island/service/IslandCoordinator.kt): `app/src/main/java/com/sameerasw/essentials/island/service/IslandCoordinator.kt`
- [Island plugins](https://github.com/sameerasw/essentials/tree/main/app/src/main/java/com/sameerasw/essentials/island/plugins): `app/src/main/java/com/sameerasw/essentials/island/plugins`
- [Island presentation](https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/island/ui/IslandRoot.kt): `app/src/main/java/com/sameerasw/essentials/island/ui/IslandRoot.kt`

### Search and tools

- [Pixel search results](https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/ui/activities/PixelSearchResultsActivity.kt): `app/src/main/java/com/sameerasw/essentials/ui/activities/PixelSearchResultsActivity.kt`
- [Voice search session](https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/services/EssentialsVoiceInteractionSessionService.kt): `app/src/main/java/com/sameerasw/essentials/services/EssentialsVoiceInteractionSessionService.kt`
- [Essentials keyboard](https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/ime/EssentialsInputMethodService.kt): `app/src/main/java/com/sameerasw/essentials/ime/EssentialsInputMethodService.kt`
- [Suggestion engine](https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/ime/SuggestionEngine.kt): `app/src/main/java/com/sameerasw/essentials/ime/SuggestionEngine.kt`
- [Image watermarking](https://github.com/sameerasw/essentials/blob/main/app/src/main/java/com/sameerasw/essentials/domain/watermark/WatermarkEngine.kt): `app/src/main/java/com/sameerasw/essentials/domain/watermark/WatermarkEngine.kt`

### Other components

- **Device user**
- **Shizuku or root**
- **Android system**
- **Image creator**

## Connections

- Device user → Feature screens: configures features
- Feature screens → Settings storage: reads and writes
- Device user → Quick Settings tiles: invokes controls
- Device user → Home widgets: uses widgets
- Device user → Accessibility service: enables service
- Accessibility service → System handlers: initializes handlers
- Quick Settings tiles → Android system: controls device
- System handlers → Android system: applies behavior
- System handlers → Shizuku or root: advanced commands
- Device user → Automation editor: creates automation
- Automation editor → DIY automation model: stores automation
- Automation service → Automation manager: connects service
- Automation manager → Trigger modules: starts modules
- Automation manager → Action executors: dispatches actions
- Assistant functions → Action executors: executes device actions
- Assistant functions → DIY automation model: adds automation
- Android system → Automation service: starts service
- Island coordinator → Island plugins: coordinates plugins
- Island coordinator → Island presentation: hosts overlay
- Android system → Voice search session: invokes assistant
- Voice search session → Pixel search results: launches results
- Device user → Essentials keyboard: types text
- Essentials keyboard → Suggestion engine: requests suggestions
- Image creator → Image watermarking: processes image