# junith-k/auto-unstack architecture

> Architecture diagram of the GitHub repository junith-k/auto-unstack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/junith-k/auto-unstack
- Repository: https://github.com/junith-k/auto-unstack

## Overview

1. **Overall shape**
   - This is a **single-module Android app** built in Kotlin.
   - It has one user-facing screen for settings and one background automation component that the Android system binds as an **AccessibilityService**.
   - There is **no backend, no network layer, and no external data flow**; all behavior is local on-device.

2. **Primary user boundary: the settings activity**
   - `MainActivity.kt` is the app entry point and likely hosts the Compose-based settings UI described in the README.
   - Its main job is to let the user enable or disable the feature through a simple toggle.
   - This is the only explicit UI boundary in the repo, so the architecture is intentionally small and centered on configuration rather than content display.

3. **State persistence boundary**
   - `PreferencesManager.kt` wraps `SharedPreferences`.
   - It stores the user’s enable/disable setting and acts as the shared state source between the UI and the service.
   - This creates a clean separation: UI writes preference state, service reads it before acting.

4. **Core automation subsystem: accessibility service**
   - `NotificationExpandService.kt` is the core engine of the app.
   - It runs under Android’s accessibility framework and monitors system UI events related to the notification shade.
   - Its responsibility is to inspect the notification hierarchy, detect grouped stacks/badges, and trigger expansion actions by simulating taps.

5. **Event-driven data flow**
   - The app’s main flow is:
     - User enables the toggle in the UI.
     - The toggle is persisted in `SharedPreferences`.
     - Android binds and runs the accessibility service once the user grants accessibility permission.
     - The service reacts to notification-shade events only when the shade is open and the feature is enabled.
     - It performs local UI interaction on the notification stack, then idles again.
   - The system, not the app, drives most of the runtime lifecycle.

6. **Platform integration boundary**
   - `AndroidManifest.xml` and `res/xml/accessibility_service_config.xml` define the service as an Android accessibility component.
   - These files are what connect the app to the OS permission model and event stream.
   - The config file is especially important because it constrains what the service listens to and how Android presents it in Accessibility settings.

7. **Technology stack implications**
   - The project uses **Jetpack Compose** for the settings UI.
   - It relies on **Android Accessibility APIs** for automation.
   - It uses **SharedPreferences** for lightweight local storage.
   - The app targets modern Android tooling via Gradle Kotlin DSL and standard Android build structure, but the architecture itself stays simple and mostly OS-driven.

8. **Runtime behavior constraints**
   - The service is designed to operate only when the **notification shade is active**.
   - The README emphasizes smart filtering and cooldown behavior, so the service likely includes guard logic to avoid repeated taps or unnecessary event handling.
   - This means the service is not a constant background worker; it is an event-reactive component with narrow activation windows.

9. **Device- and vendor-specific scope**
   - The app is explicitly tailored to **Samsung grouped notifications**.
   - That means its detection logic is likely dependent on Samsung’s UI patterns, notification badge presentation, and clickable stack behavior.
   - When diagramming the architecture, treat Samsung UI conventions as an external dependency boundary, not just generic Android notifications.

10. **Security/privacy boundary**
   - There are no analytics, telemetry, or remote sync components.
   - The only privileged access is the accessibility permission, used to inspect UI structure and invoke taps.
   - The app claims not to read notification content directly; it focuses on UI metadata and interaction, which is important for understanding the scope of data access.

11. **Packaging and deployment**
   - The repository is structured as a standard Android app that builds into APKs via Gradle.
   - Release signing is handled externally through keystore environment variables, which affects build/deploy but not runtime architecture.
   - This reinforces that the app is distributed as a standalone utility rather than a service-backed product.

12. **Architectural summary**
   - The cleanest diagram is: **Compose settings UI → SharedPreferences → AccessibilityService → Android system notification UI**.
   - The app is intentionally minimal: one screen for control, one persistence layer for state, one service for automation, and Android itself as the event source and execution environment.

Main entry points: [`app/src/main/java/com/autounstack/app/NotificationExpandService.kt`](https://github.com/junith-k/auto-unstack/blob/main/app/src/main/java/com/autounstack/app/NotificationExpandService.kt) (Expand Service), [`app/src/main/AndroidManifest.xml`](https://github.com/junith-k/auto-unstack/blob/main/app/src/main/AndroidManifest.xml) (Manifest), [`app/src/main/java/com/autounstack/app/MainActivity.kt`](https://github.com/junith-k/auto-unstack/blob/main/app/src/main/java/com/autounstack/app/MainActivity.kt) (MainActivity), [`app/src/main/java/com/autounstack/app/PreferencesManager.kt`](https://github.com/junith-k/auto-unstack/blob/main/app/src/main/java/com/autounstack/app/PreferencesManager.kt) (Prefs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI"]
  node_main_activity["MainActivity<br/>compose activity<br/>[MainActivity.kt]"]
end

subgraph group_state["State"]
  node_preferences_manager[("Prefs")]
end

subgraph group_automation["Automation"]
  node_notification_expand_service{{"Expand Service<br/>accessibility service"}}
end

subgraph group_platform["Android"]
  node_android_manifest["Manifest"]
  node_accessibility_config["A11y Config<br/>service config"]
end

node_android_system(("Android System<br/>os runtime"))
node_notification_shade["Shade UI<br/>system ui"]
node_samsung_notifications["Samsung UI<br/>vendor ui"]

node_main_activity -->|"toggles feature"| node_preferences_manager
node_android_manifest -->|"starts app"| node_main_activity
node_android_manifest -->|"registers service"| node_notification_expand_service
node_android_manifest -->|"uses config"| node_accessibility_config
node_notification_expand_service -->|"reads state"| node_preferences_manager
node_notification_expand_service -->|"binds to OS"| node_android_system
node_android_system -->|"dispatches events"| node_notification_shade
node_notification_expand_service -->|"inspects UI"| node_notification_shade
node_notification_expand_service -->|"targets patterns"| node_samsung_notifications

click node_main_activity "https://github.com/junith-k/auto-unstack/blob/main/app/src/main/java/com/autounstack/app/MainActivity.kt"
click node_preferences_manager "https://github.com/junith-k/auto-unstack/blob/main/app/src/main/java/com/autounstack/app/PreferencesManager.kt"
click node_notification_expand_service "https://github.com/junith-k/auto-unstack/blob/main/app/src/main/java/com/autounstack/app/NotificationExpandService.kt"
click node_android_manifest "https://github.com/junith-k/auto-unstack/blob/main/app/src/main/AndroidManifest.xml"
click node_accessibility_config "https://github.com/junith-k/auto-unstack/blob/main/app/src/main/res/xml/accessibility_service_config.xml"

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_main_activity toneBlue
class node_preferences_manager toneAmber
class node_notification_expand_service toneMint
class node_android_manifest,node_accessibility_config toneRose
class node_android_system,node_notification_shade,node_samsung_notifications toneNeutral
```

## Components

### UI

User-facing settings entrypoint and control surface

- [MainActivity](https://github.com/junith-k/auto-unstack/blob/main/app/src/main/java/com/autounstack/app/MainActivity.kt): compose activity · Settings screen entrypoint with the feature toggle · `app/src/main/java/com/autounstack/app/MainActivity.kt`

### State

Lightweight local persistence for feature enablement

- [Prefs](https://github.com/junith-k/auto-unstack/blob/main/app/src/main/java/com/autounstack/app/PreferencesManager.kt): shared prefs · Stores the enabled or disabled setting shared by UI and service · `app/src/main/java/com/autounstack/app/PreferencesManager.kt`

### Automation

Accessibility-driven notification expansion engine

- [Expand Service](https://github.com/junith-k/auto-unstack/blob/main/app/src/main/java/com/autounstack/app/NotificationExpandService.kt): accessibility service · Monitors notification shade events and triggers expansion actions · `app/src/main/java/com/autounstack/app/NotificationExpandService.kt`

### Android

Manifest and accessibility configuration that bind the app into the OS

- [Manifest](https://github.com/junith-k/auto-unstack/blob/main/app/src/main/AndroidManifest.xml): app manifest · Declares the app components and accessibility service integration · `app/src/main/AndroidManifest.xml`
- [A11y Config](https://github.com/junith-k/auto-unstack/blob/main/app/src/main/res/xml/accessibility_service_config.xml): service config · Constrains the accessibility events and exposure shown in system settings · `app/src/main/res/xml/accessibility_service_config.xml`

### Other components

- **Android System**: os runtime · Event source and execution environment that binds and drives the service
- **Shade UI**: system ui · Notification shade hierarchy inspected and manipulated by the service
- **Samsung UI**: vendor ui · Samsung-specific grouped notification patterns targeted by the app

## Connections

- MainActivity → Prefs: toggles feature · The settings screen updates persisted enablement state
- Manifest → MainActivity: starts app · Declares the activity as the user-facing entrypoint
- Manifest → Expand Service: registers service · Makes the accessibility service available to Android
- Manifest → A11y Config: uses config · Links the service declaration to its accessibility metadata
- Expand Service → Prefs: reads state · Checks whether the feature is enabled before acting
- Expand Service → Android System: binds to OS · Runs only when Android binds the accessibility service
- Android System → Shade UI: dispatches events · Provides accessibility events from the notification shade
- Expand Service → Shade UI: inspects UI · Traverses notification hierarchy and triggers expansion actions
- Expand Service → Samsung UI: targets patterns · Detection logic is tuned to Samsung grouped notification behavior
