# devgitpit/supertonic-android architecture

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

- Interactive diagram: https://gitdiagram.com/devgitpit/supertonic-android
- Repository: https://github.com/devgitpit/supertonic-android

## Overview

Supertonic is an Android systemwide text-to-speech app with an in-app reading and playback experience. Users can enter text or choose an ebook, select language and voice settings, then play or export synthesized audio; the app also supports queues, history, saved audio, pronunciation rules, and model downloads. The documented synthesis path normalizes text in Kotlin, chunks it in Rust through JNI, and runs on-device ONNX inference. Several relationships below rely on the README or SOURCE INDEX because the relevant source excerpts are partial; uncertain wiring is omitted.

Main entry points: [`app/src/main/java/com/brahmadeo/supertonic/tts/MainActivity.kt`](https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/MainActivity.kt) (App entry), [`rust/src/lib.rs`](https://github.com/devgitpit/supertonic-android/blob/main/rust/src/lib.rs) (JNI synthesis), [`app/src/main/java/com/brahmadeo/supertonic/tts/service/PlaybackService.kt`](https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/service/PlaybackService.kt) (Playback service), [`app/src/main/java/com/brahmadeo/supertonic/tts/EbookOutlineActivity.kt`](https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/EbookOutlineActivity.kt) (Ebook outline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Android app"]
  node_main["App entry<br/>[MainActivity.kt]"]
  node_mainui["Main screen<br/>[MainScreen.kt]"]
  node_downloads["Model downloads<br/>[DownloadScreen.kt]"]
  node_assets["Model assets<br/>[AssetManager.kt]"]
  node_playback["Playback activity"]
  node_playui["Playback screen<br/>[PlaybackScreen.kt]"]
  node_service["Playback service<br/>[PlaybackService.kt]"]
  node_queue[("Playback queue<br/>[QueueManager.kt]")]
  node_history[("History store<br/>[HistoryManager.kt]")]
  node_saved["Saved audio"]
end

subgraph group_content["Reading and text"]
  node_ebooklibrary["Ebook library"]
  node_ebookoutline["Ebook outline"]
  node_ebookmanager[("Book tracking<br/>[EbookManager.kt]")]
  node_ebookparser["Document parser<br/>[EbookParser.kt]"]
  node_lexicon[("Pronunciation rules<br/>[LexiconManager.kt]")]
  node_normalizer["Text normalization<br/>[TextNormalizer.kt]"]
  node_numbers["Number expansion<br/>[NumberUtils.kt]"]
end

subgraph group_engine["Speech engine"]
  node_ttsservice["System TTS service"]
  node_jni["JNI engine API<br/>[SupertonicTTS.kt]"]
end

subgraph group_rust["Rust processing"]
  node_rustlib["JNI synthesis<br/>[lib.rs]"]
  node_chunker["Language chunking<br/>[mod.rs]"]
  node_helper["Synthesis helper<br/>[helper.rs]"]
  node_thermal["Thermal control<br/>[thermal.rs]"]
  node_filter["Audio filtering<br/>[filter.rs]"]
end

node_user(("User"))

node_user -->|"opens app"| node_main
node_main -->|"shows"| node_mainui
node_main -->|"binds"| node_service
node_main -->|"loads models"| node_assets
node_main -->|"shows"| node_downloads
node_downloads -.->|"downloads"| node_assets
node_main -->|"uses history"| node_history
node_main -->|"uses queue"| node_queue
node_user -->|"chooses book"| node_ebooklibrary
node_ebooklibrary -->|"tracks books"| node_ebookmanager
node_ebooklibrary -->|"opens outline"| node_ebookoutline
node_ebookoutline -->|"parses content"| node_ebookparser
node_ebookoutline -->|"records book"| node_ebookmanager
node_ebookoutline -->|"starts reading"| node_playback
node_playback -->|"shows"| node_playui
node_playback -->|"binds"| node_service
node_service -->|"manages queue"| node_queue
node_service -->|"normalizes text"| node_normalizer
node_normalizer -->|"expands numbers"| node_numbers
node_normalizer -->|"applies rules"| node_lexicon
node_service -->|"synthesizes"| node_jni
node_ttsservice -->|"normalizes input"| node_normalizer
node_ttsservice -->|"synthesizes"| node_jni
node_jni -->|"calls JNI"| node_rustlib
node_rustlib -->|"chunks text"| node_chunker
node_rustlib -->|"uses helpers"| node_helper
node_rustlib -->|"controls thermal"| node_thermal
node_helper -->|"uses normalizers"| node_chunker
node_rustlib -->|"filters audio"| node_filter
node_user -.->|"manages audio"| node_saved

click node_main "https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/MainActivity.kt"
click node_mainui "https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/ui/MainScreen.kt"
click node_downloads "https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/ui/DownloadScreen.kt"
click node_assets "https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/utils/AssetManager.kt"
click node_playback "https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/PlaybackActivity.kt"
click node_playui "https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/ui/PlaybackScreen.kt"
click node_service "https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/service/PlaybackService.kt"
click node_queue "https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/utils/QueueManager.kt"
click node_history "https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/utils/HistoryManager.kt"
click node_saved "https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/ui/SavedAudioScreen.kt"
click node_ebooklibrary "https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/EbookLibraryActivity.kt"
click node_ebookoutline "https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/EbookOutlineActivity.kt"
click node_ebookmanager "https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/utils/EbookManager.kt"
click node_ebookparser "https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/utils/EbookParser.kt"
click node_lexicon "https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/utils/LexiconManager.kt"
click node_normalizer "https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/utils/TextNormalizer.kt"
click node_numbers "https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/utils/NumberUtils.kt"
click node_ttsservice "https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/service/SupertonicTextToSpeechService.kt"
click node_jni "https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/SupertonicTTS.kt"
click node_rustlib "https://github.com/devgitpit/supertonic-android/blob/main/rust/src/lib.rs"
click node_chunker "https://github.com/devgitpit/supertonic-android/blob/main/rust/src/lang/mod.rs"
click node_helper "https://github.com/devgitpit/supertonic-android/blob/main/rust/src/helper.rs"
click node_thermal "https://github.com/devgitpit/supertonic-android/blob/main/rust/src/thermal.rs"
click node_filter "https://github.com/devgitpit/supertonic-android/blob/main/rust/src/filter.rs"

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,node_mainui,node_downloads,node_assets,node_playback,node_playui,node_service,node_queue,node_history,node_saved,node_user toneBlue
class node_ebooklibrary,node_ebookoutline,node_ebookmanager,node_ebookparser,node_lexicon,node_normalizer,node_numbers toneAmber
class node_ttsservice,node_jni toneMint
class node_rustlib,node_chunker,node_helper,node_thermal,node_filter toneRose
```

## Components

### Android app

- [App entry](https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/MainActivity.kt): `app/src/main/java/com/brahmadeo/supertonic/tts/MainActivity.kt`
- [Main screen](https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/ui/MainScreen.kt): `app/src/main/java/com/brahmadeo/supertonic/tts/ui/MainScreen.kt`
- [Model downloads](https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/ui/DownloadScreen.kt): `app/src/main/java/com/brahmadeo/supertonic/tts/ui/DownloadScreen.kt`
- [Model assets](https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/utils/AssetManager.kt): `app/src/main/java/com/brahmadeo/supertonic/tts/utils/AssetManager.kt`
- [Playback activity](https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/PlaybackActivity.kt): `app/src/main/java/com/brahmadeo/supertonic/tts/PlaybackActivity.kt`
- [Playback screen](https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/ui/PlaybackScreen.kt): `app/src/main/java/com/brahmadeo/supertonic/tts/ui/PlaybackScreen.kt`
- [Playback service](https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/service/PlaybackService.kt): `app/src/main/java/com/brahmadeo/supertonic/tts/service/PlaybackService.kt`
- [Playback queue](https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/utils/QueueManager.kt): `app/src/main/java/com/brahmadeo/supertonic/tts/utils/QueueManager.kt`
- [History store](https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/utils/HistoryManager.kt): `app/src/main/java/com/brahmadeo/supertonic/tts/utils/HistoryManager.kt`
- [Saved audio](https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/ui/SavedAudioScreen.kt): `app/src/main/java/com/brahmadeo/supertonic/tts/ui/SavedAudioScreen.kt`

### Reading and text

- [Ebook library](https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/EbookLibraryActivity.kt): `app/src/main/java/com/brahmadeo/supertonic/tts/EbookLibraryActivity.kt`
- [Ebook outline](https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/EbookOutlineActivity.kt): `app/src/main/java/com/brahmadeo/supertonic/tts/EbookOutlineActivity.kt`
- [Book tracking](https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/utils/EbookManager.kt): `app/src/main/java/com/brahmadeo/supertonic/tts/utils/EbookManager.kt`
- [Document parser](https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/utils/EbookParser.kt): `app/src/main/java/com/brahmadeo/supertonic/tts/utils/EbookParser.kt`
- [Pronunciation rules](https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/utils/LexiconManager.kt): `app/src/main/java/com/brahmadeo/supertonic/tts/utils/LexiconManager.kt`
- [Text normalization](https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/utils/TextNormalizer.kt): `app/src/main/java/com/brahmadeo/supertonic/tts/utils/TextNormalizer.kt`
- [Number expansion](https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/utils/NumberUtils.kt): `app/src/main/java/com/brahmadeo/supertonic/tts/utils/NumberUtils.kt`

### Speech engine

- [System TTS service](https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/service/SupertonicTextToSpeechService.kt): `app/src/main/java/com/brahmadeo/supertonic/tts/service/SupertonicTextToSpeechService.kt`
- [JNI engine API](https://github.com/devgitpit/supertonic-android/blob/main/app/src/main/java/com/brahmadeo/supertonic/tts/SupertonicTTS.kt): `app/src/main/java/com/brahmadeo/supertonic/tts/SupertonicTTS.kt`

### Rust processing

- [JNI synthesis](https://github.com/devgitpit/supertonic-android/blob/main/rust/src/lib.rs): `rust/src/lib.rs`
- [Language chunking](https://github.com/devgitpit/supertonic-android/blob/main/rust/src/lang/mod.rs): `rust/src/lang/mod.rs`
- [Synthesis helper](https://github.com/devgitpit/supertonic-android/blob/main/rust/src/helper.rs): `rust/src/helper.rs`
- [Thermal control](https://github.com/devgitpit/supertonic-android/blob/main/rust/src/thermal.rs): `rust/src/thermal.rs`
- [Audio filtering](https://github.com/devgitpit/supertonic-android/blob/main/rust/src/filter.rs): `rust/src/filter.rs`

### Other components

- **User**

## Connections

- User → App entry: opens app (evidence: `app/src/main/java/com/brahmadeo/supertonic/tts/MainActivity.kt`)
- App entry → Main screen: shows (evidence: `app/src/main/java/com/brahmadeo/supertonic/tts/MainActivity.kt`)
- App entry → Playback service: binds (evidence: `app/src/main/java/com/brahmadeo/supertonic/tts/MainActivity.kt`)
- App entry → Model assets: loads models (evidence: `app/src/main/java/com/brahmadeo/supertonic/tts/MainActivity.kt`)
- App entry → Model downloads: shows (evidence: `app/src/main/java/com/brahmadeo/supertonic/tts/MainActivity.kt`)
- Model downloads → Model assets: downloads
- App entry → History store: uses history (evidence: `app/src/main/java/com/brahmadeo/supertonic/tts/MainActivity.kt`)
- App entry → Playback queue: uses queue (evidence: `app/src/main/java/com/brahmadeo/supertonic/tts/MainActivity.kt`)
- User → Ebook library: chooses book (evidence: `app/src/main/java/com/brahmadeo/supertonic/tts/EbookLibraryActivity.kt`)
- Ebook library → Book tracking: tracks books (evidence: `app/src/main/java/com/brahmadeo/supertonic/tts/EbookLibraryActivity.kt`)
- Ebook library → Ebook outline: opens outline (evidence: `app/src/main/java/com/brahmadeo/supertonic/tts/EbookLibraryActivity.kt`)
- Ebook outline → Document parser: parses content (evidence: `app/src/main/java/com/brahmadeo/supertonic/tts/EbookOutlineActivity.kt`)
- Ebook outline → Book tracking: records book (evidence: `app/src/main/java/com/brahmadeo/supertonic/tts/EbookOutlineActivity.kt`)
- Ebook outline → Playback activity: starts reading (evidence: `app/src/main/java/com/brahmadeo/supertonic/tts/EbookOutlineActivity.kt`)
- Playback activity → Playback screen: shows (evidence: `app/src/main/java/com/brahmadeo/supertonic/tts/PlaybackActivity.kt`)
- Playback activity → Playback service: binds (evidence: `app/src/main/java/com/brahmadeo/supertonic/tts/PlaybackActivity.kt`)
- Playback service → Playback queue: manages queue (evidence: `app/src/main/java/com/brahmadeo/supertonic/tts/service/PlaybackService.kt`)
- Playback service → Text normalization: normalizes text (evidence: `app/src/main/java/com/brahmadeo/supertonic/tts/service/PlaybackService.kt`)
- Text normalization → Number expansion: expands numbers (evidence: `app/src/main/java/com/brahmadeo/supertonic/tts/utils/TextNormalizer.kt`)
- Text normalization → Pronunciation rules: applies rules (evidence: `app/src/main/java/com/brahmadeo/supertonic/tts/utils/TextNormalizer.kt`)
- Playback service → JNI engine API: synthesizes (evidence: `app/src/main/java/com/brahmadeo/supertonic/tts/service/PlaybackService.kt`)
- System TTS service → Text normalization: normalizes input (evidence: `app/src/main/java/com/brahmadeo/supertonic/tts/service/SupertonicTextToSpeechService.kt`)
- System TTS service → JNI engine API: synthesizes (evidence: `app/src/main/java/com/brahmadeo/supertonic/tts/service/SupertonicTextToSpeechService.kt`)
- JNI engine API → JNI synthesis: calls JNI (evidence: `rust/src/lib.rs`)
- JNI synthesis → Language chunking: chunks text (evidence: `rust/src/lib.rs`)
- JNI synthesis → Synthesis helper: uses helpers (evidence: `rust/src/lib.rs`)
- JNI synthesis → Thermal control: controls thermal (evidence: `rust/src/lib.rs`)
- Synthesis helper → Language chunking: uses normalizers (evidence: `rust/src/helper.rs`)
- JNI synthesis → Audio filtering: filters audio (evidence: `rust/src/lib.rs`)
- User → Saved audio: manages audio
