# arjncx-lang/pitch-black-launcher architecture

> Architecture diagram of the GitHub repository arjncx-lang/pitch-black-launcher, 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/arjncx-lang/pitch-black-launcher
- Repository: https://github.com/arjncx-lang/pitch-black-launcher

## Overview

#### Purpose and Android Entry Point
Lightest Launcher is a minimalist Android home-screen launcher focused on passive system updates, black OLED-oriented rendering, installed-app search, and immediate app launching. The Android app entry and launcher-role declaration are rooted in `app/src/main/AndroidManifest.xml`; runtime composition begins in `app/src/main/java/com/lightest/launcher/MainActivity.kt`.

#### UI Composition and Navigation
`MainActivity.kt` is the primary control surface, likely hosting the Compose launcher screen and coordinating app-list, search, HUD, settings, and app-detail interactions. UI modules are separated by responsibility:
- App-detail actions: `app/src/main/java/com/lightest/launcher/ui/AppDetailDialog.kt`
- Settings UI: `app/src/main/java/com/lightest/launcher/ui/SettingsScreen.kt`
- Visual system: `app/src/main/java/com/lightest/launcher/ui/theme/Theme.kt`

The resource layer supplies launcher branding, search/charging icons, and black-oriented visual assets under `app/src/main/res/drawable` and `app/src/main/res/values`.

#### Installed-App Discovery and Launch Flow
The domain model is `app/src/main/java/com/lightest/launcher/model/AppInfo.kt`. `app/src/main/java/com/lightest/launcher/data/LauncherRepository.kt` forms the device-package boundary: it should query Android’s package/activity APIs, create `AppInfo` entries, and provide the launcher’s searchable app dataset. User flow is: activity loads repository data → UI displays/filter apps → user selects an app → Android launch intent transfers control to that application.

#### Icon Caching Boundary
`app/src/main/java/com/lightest/launcher/data/IconCache.kt` isolates app-icon retrieval and reuse from app-list UI. This prevents repeated package-manager/icon decoding work during rendering and search. The cache sits between repository/package metadata and UI presentation, using `AppInfo.kt` identity or package-level data to resolve icons.

#### Passive Device-State HUD
System telemetry is represented as independent UI-state producers:
- Time: `app/src/main/java/com/lightest/launcher/ui/TimeState.kt`
- Battery/charging: `app/src/main/java/com/lightest/launcher/ui/BatteryState.kt`
- Volume: `app/src/main/java/com/lightest/launcher/ui/VolumeState.kt`
- Temperature and aggregate stats: `app/src/main/java/com/lightest/launcher/ui/DeviceTemperature.kt`, `app/src/main/java/com/lightest/launcher/ui/SystemStatsState.kt`

These components define the platform-event boundary. They consume Android broadcasts or system services and expose state to the activity/UI, rather than requiring a separate backend or persistent polling service. Time ticks, battery changes, and volume changes trigger focused UI state updates.

#### Settings Persistence
`app/src/main/java/com/lightest/launcher/data/SettingsPrefs.kt` is the persistence boundary for launcher preferences, consumed by `SettingsScreen.kt` and the root UI. It should keep user choices local to the device; the repository contains no server, API client, database, or cloud integration.

#### Build, Runtime, and Delivery
This is a single-module Android/Gradle project: `settings.gradle.kts`, root `build.gradle.kts`, and `app/build.gradle.kts` define build composition. The runtime is Android/Kotlin, with Android resources and manifest permissions/components controlling OS integration. Release optimization/obfuscation is configured through `app/proguard-rules.pro` and `app/src/main/keepRules/rules.keep`. A prebuilt distributable exists at `Lightest-Launcher-v1.7.0.apk`.

Main entry points: [`app/src/main/java/com/lightest/launcher/MainActivity.kt`](https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/MainActivity.kt) (Main activity), [`app/src/main/java/com/lightest/launcher/data/LauncherRepository.kt`](https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/data/LauncherRepository.kt) (Launcher repository), [`app/src/main/AndroidManifest.xml`](https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/AndroidManifest.xml) (Launcher manifest), [`app/src/main/java/com/lightest/launcher/model/AppInfo.kt`](https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/model/AppInfo.kt) (App info)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Android runtime"]
  node_manifest["Launcher manifest<br/>Android entry declaration"]
  node_activity["Main activity<br/>Android/Compose host<br/>[MainActivity.kt]"]
  node_android{{"Android platform<br/>OS services"}}
end

subgraph group_data["Launcher data"]
  node_repository["Launcher repository<br/>package-data boundary"]
  node_appinfo["App info<br/>domain model<br/>[AppInfo.kt]"]
  node_icons["Icon cache<br/>[IconCache.kt]"]
  node_prefs[("Settings prefs<br/>local preferences<br/>[SettingsPrefs.kt]")]
end

subgraph group_hud["Passive HUD state"]
  node_time["Time state<br/>UI-state producer<br/>[TimeState.kt]"]
  node_battery["Battery state<br/>UI-state producer<br/>[BatteryState.kt]"]
  node_volume["Volume state<br/>UI-state producer<br/>[VolumeState.kt]"]
  node_stats["System stats<br/>UI-state producer"]
  node_temperature["Device temperature<br/>telemetry source"]
end

subgraph group_ui["Compose UI"]
  node_launcher_ui["Launcher screen<br/>Compose launcher UI"]
  node_detail["App detail dialog<br/>Compose dialog<br/>[AppDetailDialog.kt]"]
  node_settings_ui["Settings screen<br/>Compose settings UI<br/>[SettingsScreen.kt]"]
  node_theme["OLED theme and assets<br/>visual system<br/>[Theme.kt]"]
end

subgraph group_delivery["Build and delivery"]
  node_gradle["Gradle build<br/>Android build pipeline<br/>[build.gradle.kts]"]
  node_apk["Release APK<br/>distributable"]
end

node_manifest -->|"launches"| node_activity
node_android -->|"recognizes launcher role"| node_manifest
node_activity -->|"loads apps"| node_repository
node_repository -->|"queries packages and activities"| node_android
node_repository -->|"creates"| node_appinfo
node_activity -->|"hosts"| node_launcher_ui
node_appinfo -->|"searchable app list"| node_launcher_ui
node_icons -->|"app icons"| node_launcher_ui
node_android -->|"resolves package icons"| node_icons
node_launcher_ui -->|"selected app"| node_detail
node_launcher_ui -->|"launch intent"| node_android
node_activity -->|"opens"| node_settings_ui
node_settings_ui -->|"reads and writes"| node_prefs
node_prefs -->|"applies preferences"| node_activity
node_android -->|"time ticks"| node_time
node_android -->|"battery broadcasts"| node_battery
node_android -->|"audio service changes"| node_volume
node_android -->|"system telemetry"| node_temperature
node_temperature -->|"temperature data"| node_stats
node_time -->|"HUD state"| node_launcher_ui
node_battery -->|"HUD state"| node_launcher_ui
node_volume -->|"HUD state"| node_launcher_ui
node_stats -->|"HUD state"| node_launcher_ui
node_theme -->|"styles"| node_launcher_ui
node_gradle -->|"packages release"| node_apk

click node_manifest "https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/AndroidManifest.xml"
click node_activity "https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/MainActivity.kt"
click node_repository "https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/data/LauncherRepository.kt"
click node_appinfo "https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/model/AppInfo.kt"
click node_icons "https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/data/IconCache.kt"
click node_prefs "https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/data/SettingsPrefs.kt"
click node_time "https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/ui/TimeState.kt"
click node_battery "https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/ui/BatteryState.kt"
click node_volume "https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/ui/VolumeState.kt"
click node_stats "https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/ui/SystemStatsState.kt"
click node_temperature "https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/ui/DeviceTemperature.kt"
click node_detail "https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/ui/AppDetailDialog.kt"
click node_settings_ui "https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/ui/SettingsScreen.kt"
click node_theme "https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/ui/theme/Theme.kt"
click node_gradle "https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/build.gradle.kts"
click node_apk "https://github.com/arjncx-lang/pitch-black-launcher/blob/main/Lightest-Launcher-v1.7.0.apk"

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_activity,node_android toneBlue
class node_repository,node_appinfo,node_icons,node_prefs toneAmber
class node_time,node_battery,node_volume,node_stats,node_temperature toneMint
class node_launcher_ui,node_detail,node_settings_ui,node_theme toneRose
class node_gradle,node_apk toneIndigo
```

## Components

### Android runtime

- [Launcher manifest](https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/AndroidManifest.xml): Android entry declaration · Declares the launcher role and Android components. · `app/src/main/AndroidManifest.xml`
- [Main activity](https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/MainActivity.kt): Android/Compose host · Composes the launcher and coordinates primary interactions. · `app/src/main/java/com/lightest/launcher/MainActivity.kt`
- **Android platform**: OS services · Provides package APIs, broadcasts, system services, and launch intents.

### Launcher data

- [Launcher repository](https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/data/LauncherRepository.kt): package-data boundary · Discovers launchable installed applications. · `app/src/main/java/com/lightest/launcher/data/LauncherRepository.kt`
- [App info](https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/model/AppInfo.kt): domain model · `app/src/main/java/com/lightest/launcher/model/AppInfo.kt`
- [Icon cache](https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/data/IconCache.kt): icon cache · Reuses resolved package icons during list rendering and search. · `app/src/main/java/com/lightest/launcher/data/IconCache.kt`
- [Settings prefs](https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/data/SettingsPrefs.kt): local preferences · Persists launcher choices on device. · `app/src/main/java/com/lightest/launcher/data/SettingsPrefs.kt`

### Passive HUD state

- [Time state](https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/ui/TimeState.kt): UI-state producer · `app/src/main/java/com/lightest/launcher/ui/TimeState.kt`
- [Battery state](https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/ui/BatteryState.kt): UI-state producer · `app/src/main/java/com/lightest/launcher/ui/BatteryState.kt`
- [Volume state](https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/ui/VolumeState.kt): UI-state producer · `app/src/main/java/com/lightest/launcher/ui/VolumeState.kt`
- [System stats](https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/ui/SystemStatsState.kt): UI-state producer · Aggregates temperature and related device stats. · `app/src/main/java/com/lightest/launcher/ui/SystemStatsState.kt`
- [Device temperature](https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/ui/DeviceTemperature.kt): telemetry source · `app/src/main/java/com/lightest/launcher/ui/DeviceTemperature.kt`

### Compose UI

- **Launcher screen**: Compose launcher UI · Displays, filters, and selects installed apps.
- [App detail dialog](https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/ui/AppDetailDialog.kt): Compose dialog · Provides actions for a selected application. · `app/src/main/java/com/lightest/launcher/ui/AppDetailDialog.kt`
- [Settings screen](https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/ui/SettingsScreen.kt): Compose settings UI · `app/src/main/java/com/lightest/launcher/ui/SettingsScreen.kt`
- [OLED theme and assets](https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/src/main/java/com/lightest/launcher/ui/theme/Theme.kt): visual system · Supplies black-oriented styling, branding, and icons. · `app/src/main/java/com/lightest/launcher/ui/theme/Theme.kt`

### Build and delivery

- [Gradle build](https://github.com/arjncx-lang/pitch-black-launcher/blob/main/app/build.gradle.kts): Android build pipeline · Builds the single Android application module. · `app/build.gradle.kts`
- [Release APK](https://github.com/arjncx-lang/pitch-black-launcher/blob/main/Lightest-Launcher-v1.7.0.apk): distributable · `Lightest-Launcher-v1.7.0.apk`

## Connections

- Launcher manifest → Main activity: launches
- Android platform → Launcher manifest: recognizes launcher role
- Main activity → Launcher repository: loads apps
- Launcher repository → Android platform: queries packages and activities
- Launcher repository → App info: creates
- Main activity → Launcher screen: hosts
- App info → Launcher screen: searchable app list
- Icon cache → Launcher screen: app icons
- Android platform → Icon cache: resolves package icons
- Launcher screen → App detail dialog: selected app
- Launcher screen → Android platform: launch intent · Transfers control to the selected application.
- Main activity → Settings screen: opens
- Settings screen → Settings prefs: reads and writes
- Settings prefs → Main activity: applies preferences
- Android platform → Time state: time ticks
- Android platform → Battery state: battery broadcasts
- Android platform → Volume state: audio service changes
- Android platform → Device temperature: system telemetry
- Device temperature → System stats: temperature data
- Time state → Launcher screen: HUD state
- Battery state → Launcher screen: HUD state
- Volume state → Launcher screen: HUD state
- System stats → Launcher screen: HUD state
- OLED theme and assets → Launcher screen: styles
- Gradle build → Release APK: packages release