# pilot51/voicenotify architecture

> Architecture diagram of the GitHub repository pilot51/voicenotify, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pilot51/voicenotify
- Repository: https://github.com/pilot51/voicenotify

## Overview

##### Project type and purpose
- Voice Notify is a single-module Android application written in Kotlin, using Jetpack Compose for UI, Room + DataStore for persistence, and Android’s NotificationListenerService and Text-to-Speech (TTS) APIs to speak incoming notifications.

##### File structure
- Top-level
- build scripts (build.gradle.kts, settings.gradle.kts, gradle/…)
- README, LICENSE, CI workflows
- app/
- schemas/ – Room database migration JSON
- src/main/AndroidManifest.xml – declares services, widget, tile, activities
- src/main/java/com/pilot51/voicenotify/
– Service.kt (NotificationListenerService subclass)
– VoiceNotifyTileService.kt (Quick Settings tile)
– AppWidget.kt (home-screen widget)
– MainActivity.kt + Compose screens (/ui) and view models
– prefs/ DataStoreManager, PreferenceHelper, Room entities, DAOs, Repository
– Utils, Constants, PermissionHelper, Shake (gesture detection), VNApplication
- No separate backend—entire logic runs on device, interacting with Android system services and local storage.

##### Key insights from README
- Core flow: listen for notifications → filter/transform based on user preferences → speak via TTS → optionally log to database → allow UI to view/change settings and logs.
- Provides suspend widget, quick-settings tile, quiet time, shake-to-silence, per-app overrides, backup/restore.

##### Main components and their interactions
a. Components
1. Android System Services
- NotificationListenerService (Service.kt)
- TextToSpeech engine
- Quick Settings Tile framework (VoiceNotifyTileService)
- AppWidgetProvider (AppWidget)
- Backup/Restore (zip to external storage)
2. Data Layer
- DataStore (DataStoreManager) for lightweight preferences
- Room Database (AppDatabase, entities in prefs/db) + AppRepository
3. Business Logic / Domain
- NotificationProcessor (in Service.kt + Utils)
- PreferenceHelper to fetch/interpret settings
- Shake detector to suppress speech
4. Presentation Layer
- MainActivity + Compose screens (AppListScreen, MainScreen, TtsConfigScreen, PreferenceRows, dialogs)
- ViewModels (AppListViewModel, PreferencesViewModel)
b. Data flows & relationships
1. Android system posts a status-bar notification → NotificationListenerService.onNotificationPosted()
2. Service fetches relevant prefs via PreferenceHelper/DataStoreManager or AppRepository
3. Applies filtering rules (ignore apps/text, quiet time, screen/headset state, shake)
4. Formats TTS message (Utils, Constants, NotifyList)
5. Sends utterance to Android TTS engine
6. Service logs notification details to Room via AppRepository
7. UI screens read prefs and log records from DataStore and Room via ViewModels
8. User changes settings → DataStoreManager or AppRepository updates persistence
9. Backup/Restore screen bundles DataStore + Room DB into ZIP and writes to external storage
10. Widgets and quick tile call into Service to toggle “suspended” state
c. Architectural patterns & principles
– MVVM for UI (Compose + ViewModel)
– Repository abstraction over DataStore + Room
– Single Android module—on-device micro-architecture layered by function
– Clear separation: System integration (services, widgets) vs domain logic vs data vs presentation
d. Key technologies
– Kotlin + Kotlin DSL Gradle
– Jetpack Compose
– AndroidX Room, DataStore
– Android NotificationListenerService, TileService, AppWidgetProvider
– Android TTS API
– Migration JSON under app/schemas for Room

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Android System"
        NM["NotificationManager"]:::system
        TTS["TTS Engine"]:::system
        Storage["External Storage"]:::external
    end

    subgraph "System Integration"
        Service["NotificationListenerService"]:::integration
        Tile["Quick Settings TileService"]:::integration
        Widget["AppWidgetProvider"]:::integration
    end

    subgraph "Business Logic"
        Constants["Constants"]:::logic
        NotifyList["NotifyList"]:::logic
        Utils["Utils"]:::logic
        Shake["ShakeDetector"]:::logic
        Permission["PermissionHelper"]:::logic
        PrefHelper["PreferenceHelper"]:::logic
    end

    subgraph "Data Layer"
        DS["DataStoreManager"]:::data
        DB["AppDatabase"]:::data
        Entities["Entities (App, Settings)"]:::data
        Repo["AppRepository"]:::data
    end

    subgraph "Presentation/UI"
        MainAct["MainActivity + Compose Screens"]:::ui
        VM1["AppListViewModel"]:::ui
        VM2["PreferencesViewModel"]:::ui
        Backup["BackupDialog"]:::ui
    end

    NM -->|"onNotificationPosted()"| Service
    Service -->|"fetch prefs"| PrefHelper
    PrefHelper --> DS
    DS --> Repo
    Service -->|"apply rules"| Constants
    Service --> NotifyList
    Service --> Utils
    Service --> Shake
    Service --> Permission
    Service -->|"speak()"| TTS
    Service -->|"logNotification()"| Repo
    Repo --> DB
    DB --> Entities
    MainAct --> VM1
    MainAct --> VM2
    VM1 --> DS
    VM1 --> Repo
    VM2 --> DS
    VM2 --> Repo
    Backup --> Repo
    Backup -->|"write zip"| Storage
    Tile -->|"toggleSuspend()"| Service
    Widget -->|"toggleSuspend()"| Service

    click Service "https://github.com/pilot51/voicenotify/blob/main/app/src/main/java/com/pilot51/voicenotify/Service.kt"
    click Utils "https://github.com/pilot51/voicenotify/blob/main/app/src/main/java/com/pilot51/voicenotify/Utils.kt"
    click Tile "https://github.com/pilot51/voicenotify/blob/main/app/src/main/java/com/pilot51/voicenotify/VoiceNotifyTileService.kt"
    click Widget "https://github.com/pilot51/voicenotify/blob/main/app/src/main/java/com/pilot51/voicenotify/AppWidget.kt"
    click DS "https://github.com/pilot51/voicenotify/blob/main/app/src/main/java/com/pilot51/voicenotify/prefs/DataStoreManager.kt"
    click PrefHelper "https://github.com/pilot51/voicenotify/blob/main/app/src/main/java/com/pilot51/voicenotify/prefs/PreferenceHelper.kt"
    click DB "https://github.com/pilot51/voicenotify/blob/main/app/src/main/java/com/pilot51/voicenotify/prefs/db/AppDatabase.kt"
    click Entities "https://github.com/pilot51/voicenotify/blob/main/app/src/main/java/com/pilot51/voicenotify/prefs/db/App.kt"
    click Repo "https://github.com/pilot51/voicenotify/blob/main/app/src/main/java/com/pilot51/voicenotify/prefs/db/AppRepository.kt"
    click Constants "https://github.com/pilot51/voicenotify/blob/main/app/src/main/java/com/pilot51/voicenotify/Constants.kt"
    click NotifyList "https://github.com/pilot51/voicenotify/blob/main/app/src/main/java/com/pilot51/voicenotify/NotifyList.kt"
    click Shake "https://github.com/pilot51/voicenotify/blob/main/app/src/main/java/com/pilot51/voicenotify/Shake.kt"
    click Permission "https://github.com/pilot51/voicenotify/blob/main/app/src/main/java/com/pilot51/voicenotify/PermissionHelper.kt"
    click MainAct "https://github.com/pilot51/voicenotify/blob/main/app/src/main/java/com/pilot51/voicenotify/MainActivity.kt"
    click VM1 "https://github.com/pilot51/voicenotify/blob/main/app/src/main/java/com/pilot51/voicenotify/ui/AppListViewModel.kt"
    click VM2 "https://github.com/pilot51/voicenotify/blob/main/app/src/main/java/com/pilot51/voicenotify/ui/PreferencesViewModel.kt"
    click Backup "https://github.com/pilot51/voicenotify/blob/main/app/src/main/java/com/pilot51/voicenotify/ui/dialog/main/BackupDialog.kt"

    classDef system fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef integration fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20
    classDef logic fill:#fff9c4,stroke:#f57f17,color:#f57f17
    classDef data fill:#ffecb3,stroke:#ef6c00,color:#ef6c00
    classDef ui fill:#e1bee7,stroke:#6a1b9a,color:#6a1b9a
    classDef external fill:#eeeeee,stroke:#9e9e9e,color:#424242
```
