# ykatchou/ylauncher architecture

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

- Interactive diagram: https://gitdiagram.com/ykatchou/ylauncher
- Repository: https://github.com/ykatchou/ylauncher

## Overview

#### Purpose and runtime
yLauncher is a native Android home-screen launcher: a minimalist, gesture-driven interface for launching installed apps, organizing favorites/folders/panels, showing notification summaries, and hosting widgets. It is Kotlin 2.1 on Android (min SDK 26, compile SDK 36), using Jetpack Compose/Material 3, MVVM with StateFlow, Hilt, Room, DataStore, and Navigation Compose.

#### Application bootstrap and composition
Android launches through the manifest and Compose activity; the application class initializes process-level dependencies. Hilt’s module defines the dependency boundary for repositories, persistence, and platform integrations.
- `app/src/main/AndroidManifest.xml`
- `app/src/main/java/com/ykatchou/ylauncher/MainActivity.kt`
- `app/src/main/java/com/ykatchou/ylauncher/YLauncherApp.kt`
- `app/src/main/java/com/ykatchou/ylauncher/di/AppModule.kt`

#### Home workspace and state orchestration
The home screen is the primary workspace: it renders a selected panel’s favorites, folders, clock, notification badges, widgets, gesture targets, and configurable HAL button. `HomeViewModel` coordinates initial loading and mutations across app inventory, persisted favorites/folders/panels, and preferences; UI editing surfaces feed those changes back through it.
- `app/src/main/java/com/ykatchou/ylauncher/ui/home/HomeScreen.kt`
- `app/src/main/java/com/ykatchou/ylauncher/ui/home/HomeViewModel.kt`
- `app/src/main/java/com/ykatchou/ylauncher/ui/home/EditFavoritesSheet.kt`
- `app/src/main/java/com/ykatchou/ylauncher/ui/home/EditPanelsDialog.kt`

#### Installed-app discovery and drawer flow
`AppRepository` is the boundary to Android’s installed-app/package data and produces app information consumed by both home and drawer. The drawer ViewModel maintains searchable app-list state; the screen supports live filtering, single-match auto-launch, alphabet navigation, and `!`-prefixed DuckDuckGo bang search behavior. Launching crosses into Android intents via the launcher utility.
- `app/src/main/java/com/ykatchou/ylauncher/data/repository/AppRepository.kt`
- `app/src/main/java/com/ykatchou/ylauncher/ui/drawer/AppDrawerViewModel.kt`
- `app/src/main/java/com/ykatchou/ylauncher/ui/drawer/AppDrawerScreen.kt`
- `app/src/main/java/com/ykatchou/ylauncher/util/AppLauncher.kt`

#### Persistence and preference boundary
Room persists launcher-owned layout entities—favorites, folders, and panels—behind DAOs and a central database. DataStore-backed preferences hold user configuration such as gestures, visual settings, hidden apps, and action selection. Models form the shared data vocabulary between repository/ViewModel/UI layers.
- `app/src/main/java/com/ykatchou/ylauncher/data/db/YLauncherDatabase.kt`
- `app/src/main/java/com/ykatchou/ylauncher/data/db/FavoriteDao.kt`
- `app/src/main/java/com/ykatchou/ylauncher/data/db/FolderDao.kt`
- `app/src/main/java/com/ykatchou/ylauncher/data/repository/PrefsRepository.kt`

#### Android system integrations
Platform APIs provide notification access, usage statistics, flashlight control, app-widget hosting, app launching, and screen-lock-related actions. `NotificationService` is the privileged notification ingestion boundary; its output maps to app notification models for home display. Widget host code embeds Android widgets in Compose-facing UI.
- `app/src/main/java/com/ykatchou/ylauncher/service/NotificationService.kt`
- `app/src/main/java/com/ykatchou/ylauncher/data/model/AppNotification.kt`
- `app/src/main/java/com/ykatchou/ylauncher/widget/LauncherWidgetHost.kt`
- `app/src/main/java/com/ykatchou/ylauncher/ui/components/AppWidgetContainer.kt`

#### Configurable actions, settings, and monetization
The HAL button and home gestures resolve configured actions through a dedicated action model/executor, isolating UI events from platform side effects. Settings is the user-facing configuration surface. Billing supports optional purchase flows through Google Play Billing; review and Play Store helpers integrate with Play services/store intents.
- `app/src/main/java/com/ykatchou/ylauncher/ui/hal/HalAction.kt`
- `app/src/main/java/com/ykatchou/ylauncher/ui/hal/HalActionExecutor.kt`
- `app/src/main/java/com/ykatchou/ylauncher/ui/settings/SettingsScreen.kt`
- `app/src/main/java/com/ykatchou/ylauncher/billing/BillingManager.kt>

Main entry points: [`app/src/main/java/com/ykatchou/ylauncher/ui/home/HomeViewModel.kt`](https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/ui/home/HomeViewModel.kt) (Home view model), [`app/src/main/java/com/ykatchou/ylauncher/ui/home/HomeScreen.kt`](https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/ui/home/HomeScreen.kt) (Home screen), [`app/src/main/java/com/ykatchou/ylauncher/di/AppModule.kt`](https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/di/AppModule.kt) (Hilt module), [`app/src/main/java/com/ykatchou/ylauncher/ui/drawer/AppDrawerViewModel.kt`](https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/ui/drawer/AppDrawerViewModel.kt) (Drawer view model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["App bootstrap"]
  node_manifest["Android manifest<br/>Android entry"]
  node_app["YLauncher app<br/>[YLauncherApp.kt]"]
  node_activity["Main activity<br/>Compose host<br/>[MainActivity.kt]"]
  node_di["Hilt module<br/>DI boundary<br/>[AppModule.kt]"]
end

subgraph group_workspace["Launcher UI"]
  node_home_screen["Home screen<br/>Compose workspace<br/>[HomeScreen.kt]"]
  node_home_vm["Home view model<br/>StateFlow MVVM<br/>[HomeViewModel.kt]"]
  node_drawer_screen["App drawer<br/>Compose screen<br/>[AppDrawerScreen.kt]"]
  node_drawer_vm["Drawer view model<br/>StateFlow MVVM"]
  node_settings["Settings<br/>Compose screen<br/>[SettingsScreen.kt]"]
  node_actions["HAL action executor<br/>Action dispatcher"]
end

subgraph group_data["Data and state"]
  node_app_repo["App repository<br/>Package-data boundary<br/>[AppRepository.kt]"]
  node_database[("Launcher database<br/>Room database")]
  node_prefs["Preferences repository<br/>DataStore boundary<br/>[PrefsRepository.kt]"]
end

subgraph group_platform["Android integrations"]
  node_notifications["Notification service<br/>Privileged service"]
  node_widgets["Widget host<br/>AppWidget integration"]
  node_launcher["App launcher<br/>Intent utility<br/>[AppLauncher.kt]"]
  node_billing["Billing manager<br/>Play Billing"]
end

node_manifest -->|"starts"| node_app
node_manifest -->|"launches"| node_activity
node_app -->|"initializes"| node_di
node_activity -->|"hosts navigation"| node_home_screen
node_di -.->|"injects dependencies"| node_home_vm
node_di -.->|"injects dependencies"| node_drawer_vm
node_home_screen -->|"observes and dispatches"| node_home_vm
node_drawer_screen -->|"observes and dispatches"| node_drawer_vm
node_home_vm -->|"loads apps"| node_app_repo
node_home_vm -->|"reads and updates layout"| node_database
node_home_vm -->|"reads configuration"| node_prefs
node_home_vm -->|"shows summaries"| node_notifications
node_home_screen -->|"embeds widgets"| node_widgets
node_home_screen -->|"triggers gestures and HAL"| node_actions
node_drawer_vm -->|"queries apps"| node_app_repo
node_drawer_screen -->|"launches selection"| node_launcher
node_actions -->|"launch-app action"| node_launcher
node_settings -->|"updates configuration"| node_prefs
node_settings -->|"starts purchase flow"| node_billing

click node_manifest "https://github.com/ykatchou/ylauncher/blob/main/app/src/main/AndroidManifest.xml"
click node_app "https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/YLauncherApp.kt"
click node_activity "https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/MainActivity.kt"
click node_di "https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/di/AppModule.kt"
click node_home_screen "https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/ui/home/HomeScreen.kt"
click node_home_vm "https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/ui/home/HomeViewModel.kt"
click node_drawer_screen "https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/ui/drawer/AppDrawerScreen.kt"
click node_drawer_vm "https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/ui/drawer/AppDrawerViewModel.kt"
click node_settings "https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/ui/settings/SettingsScreen.kt"
click node_actions "https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/ui/hal/HalActionExecutor.kt"
click node_app_repo "https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/data/repository/AppRepository.kt"
click node_database "https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/data/db/YLauncherDatabase.kt"
click node_prefs "https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/data/repository/PrefsRepository.kt"
click node_notifications "https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/service/NotificationService.kt"
click node_widgets "https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/widget/LauncherWidgetHost.kt"
click node_launcher "https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/util/AppLauncher.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_manifest,node_app,node_activity,node_di toneBlue
class node_home_screen,node_home_vm,node_drawer_screen,node_drawer_vm,node_settings,node_actions toneAmber
class node_app_repo,node_database,node_prefs toneMint
class node_notifications,node_widgets,node_launcher,node_billing toneRose
```

## Components

### App bootstrap

- [Android manifest](https://github.com/ykatchou/ylauncher/blob/main/app/src/main/AndroidManifest.xml): Android entry · `app/src/main/AndroidManifest.xml`
- [YLauncher app](https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/YLauncherApp.kt): Application · Initializes process-level dependencies. · `app/src/main/java/com/ykatchou/ylauncher/YLauncherApp.kt`
- [Main activity](https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/MainActivity.kt): Compose host · `app/src/main/java/com/ykatchou/ylauncher/MainActivity.kt`
- [Hilt module](https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/di/AppModule.kt): DI boundary · `app/src/main/java/com/ykatchou/ylauncher/di/AppModule.kt`

### Launcher UI

- [Home screen](https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/ui/home/HomeScreen.kt): Compose workspace · Renders the selected panel, widgets, badges, and gesture targets. · `app/src/main/java/com/ykatchou/ylauncher/ui/home/HomeScreen.kt`
- [Home view model](https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/ui/home/HomeViewModel.kt): StateFlow MVVM · Coordinates workspace loading and mutations. · `app/src/main/java/com/ykatchou/ylauncher/ui/home/HomeViewModel.kt`
- [App drawer](https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/ui/drawer/AppDrawerScreen.kt): Compose screen · `app/src/main/java/com/ykatchou/ylauncher/ui/drawer/AppDrawerScreen.kt`
- [Drawer view model](https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/ui/drawer/AppDrawerViewModel.kt): StateFlow MVVM · Maintains searchable installed-app state. · `app/src/main/java/com/ykatchou/ylauncher/ui/drawer/AppDrawerViewModel.kt`
- [Settings](https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/ui/settings/SettingsScreen.kt): Compose screen · `app/src/main/java/com/ykatchou/ylauncher/ui/settings/SettingsScreen.kt`
- [HAL action executor](https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/ui/hal/HalActionExecutor.kt): Action dispatcher · Resolves configured gestures and HAL actions into side effects. · `app/src/main/java/com/ykatchou/ylauncher/ui/hal/HalActionExecutor.kt`

### Data and state

- [App repository](https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/data/repository/AppRepository.kt): Package-data boundary · Reads installed application information from Android. · `app/src/main/java/com/ykatchou/ylauncher/data/repository/AppRepository.kt`
- [Launcher database](https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/data/db/YLauncherDatabase.kt): Room database · Persists favorites, folders, and panels. · `app/src/main/java/com/ykatchou/ylauncher/data/db/YLauncherDatabase.kt`
- [Preferences repository](https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/data/repository/PrefsRepository.kt): DataStore boundary · Stores configuration, hidden apps, and action selection. · `app/src/main/java/com/ykatchou/ylauncher/data/repository/PrefsRepository.kt`

### Android integrations

- [Notification service](https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/service/NotificationService.kt): Privileged service · Ingests Android notifications for home summaries. · `app/src/main/java/com/ykatchou/ylauncher/service/NotificationService.kt`
- [Widget host](https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/widget/LauncherWidgetHost.kt): AppWidget integration · Hosts Android widgets in Compose UI. · `app/src/main/java/com/ykatchou/ylauncher/widget/LauncherWidgetHost.kt`
- [App launcher](https://github.com/ykatchou/ylauncher/blob/main/app/src/main/java/com/ykatchou/ylauncher/util/AppLauncher.kt): Intent utility · Launches selected apps through Android intents. · `app/src/main/java/com/ykatchou/ylauncher/util/AppLauncher.kt`
- **Billing manager**: Play Billing · Runs optional purchase flows.

## Connections

- Android manifest → YLauncher app: starts
- Android manifest → Main activity: launches
- YLauncher app → Hilt module: initializes
- Main activity → Home screen: hosts navigation
- Hilt module → Home view model: injects dependencies
- Hilt module → Drawer view model: injects dependencies
- Home screen → Home view model: observes and dispatches
- App drawer → Drawer view model: observes and dispatches
- Home view model → App repository: loads apps
- Home view model → Launcher database: reads and updates layout
- Home view model → Preferences repository: reads configuration
- Home view model → Notification service: shows summaries
- Home screen → Widget host: embeds widgets
- Home screen → HAL action executor: triggers gestures and HAL
- Drawer view model → App repository: queries apps
- App drawer → App launcher: launches selection
- HAL action executor → App launcher: launch-app action
- Settings → Preferences repository: updates configuration
- Settings → Billing manager: starts purchase flow