# sanyi1963bp/vox-libris architecture

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

- Interactive diagram: https://gitdiagram.com/sanyi1963bp/vox-libris
- Repository: https://github.com/sanyi1963bp/vox-libris

## Overview

Vox Libris is an offline-first Android ebook catalog and sentence-level reader. The main workflow is: the reader selects a book folder, the app scans files and metadata into its catalog, then opens a book, extracts and segments its text, and reads it through Android TTS while saving progress and bookmarks. The graph also preserves browsing, covers, reader tools, export/statistics, and optional AI chat. Relationships are limited to README statements and SOURCE INDEX references; unsampled wiring is not asserted.

Main entry points: [`app/src/main/java/hu/konyvtar/tts/tts/TtsService.kt`](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/tts/TtsService.kt) (Speech service), [`app/src/main/java/hu/konyvtar/tts/MainActivity.kt`](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/MainActivity.kt) (Main activity), [`app/src/main/java/hu/konyvtar/tts/ui/ReaderScreen.kt`](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/ui/ReaderScreen.kt) (Reader screen), [`app/src/main/java/hu/konyvtar/tts/vm/LibraryViewModel.kt`](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/vm/LibraryViewModel.kt) (Library state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and navigation"]
  node_activity["Main activity<br/>[MainActivity.kt]"]
  node_library_ui["Library and shelf<br/>[LibraryScreen.kt]"]
  node_browser_ui["File browser<br/>[ExplorerScreen.kt]"]
  node_reader_ui["Reader screen<br/>[ReaderScreen.kt]"]
end

subgraph group_library["Library and catalog"]
  node_library_vm["Library state"]
  node_browser_vm["Browser state"]
  node_scanner["Library scanner<br/>[LibraryScanner.kt]"]
  node_metadata["Metadata extraction"]
  node_catalog[("Book catalog<br/>[Catalog.kt]")]
  node_covers["Cover scanning<br/>[CoverScanner.kt]"]
  node_cover_extract["Cover extraction<br/>[CoverExtractor.kt]"]
  node_db[("Reading records<br/>[AppDb.kt]")]
end

subgraph group_reading["Reading and playback"]
  node_extractor["Text extraction<br/>[TextExtractor.kt]"]
  node_epub["EPUB parser<br/>[EpubParser.kt]"]
  node_html["HTML cleanup<br/>[HtmlText.kt]"]
  node_sentences["Sentence segmentation<br/>[Sentences.kt]"]
  node_tts["Speech service<br/>[TtsService.kt]"]
  node_android_tts["Android speech engine"]
end

subgraph group_support["Reader tools and integrations"]
  node_prefs[("Preferences<br/>[Prefs.kt]")]
  node_pronounce["Pronunciation rules<br/>[Pronounce.kt]"]
  node_ai_chat["AI chat<br/>[AiChatScreen.kt]"]
  node_ai_context["Book context<br/>[BookContext.kt]"]
  node_ai_client["AI client<br/>[AiClient.kt]"]
  node_exports["Export and statistics<br/>[Exporter.kt]"]
end

node_reader(("Reader"))

node_reader -->|"opens app"| node_activity
node_activity -->|"shows views"| node_library_ui
node_activity -->|"routes to"| node_browser_ui
node_activity -->|"routes to"| node_reader_ui
node_library_ui -->|"uses state"| node_library_vm
node_browser_ui -->|"uses state"| node_browser_vm
node_library_vm -->|"starts scan"| node_scanner
node_scanner -->|"extracts metadata"| node_metadata
node_scanner -->|"updates catalog"| node_catalog
node_library_vm -->|"loads books"| node_catalog
node_library_vm -->|"starts cover scan"| node_covers
node_covers -->|"extracts covers"| node_cover_extract
node_covers -->|"reads catalog"| node_catalog
node_reader_ui -->|"controls playback"| node_tts
node_tts -->|"loads book text"| node_extractor
node_extractor -->|"dispatches EPUB"| node_epub
node_epub -->|"cleans markup"| node_html
node_tts -->|"segments speech"| node_sentences
node_tts -->|"speaks text"| node_android_tts
node_tts -->|"saves progress"| node_db
node_tts -->|"loads settings"| node_prefs
node_tts -->|"applies rules"| node_pronounce
node_reader_ui -->|"manages bookmarks"| node_db
node_reader_ui -->|"opens chat"| node_ai_chat
node_ai_chat -->|"builds context"| node_ai_context
node_ai_chat -->|"sends prompts"| node_ai_client
node_reader -->|"exports records"| node_exports

click node_activity "https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/MainActivity.kt"
click node_library_ui "https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/ui/LibraryScreen.kt"
click node_browser_ui "https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/ui/ExplorerScreen.kt"
click node_reader_ui "https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/ui/ReaderScreen.kt"
click node_library_vm "https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/vm/LibraryViewModel.kt"
click node_browser_vm "https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/vm/BrowserViewModel.kt"
click node_scanner "https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/data/LibraryScanner.kt"
click node_metadata "https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/data/MetadataExtractor.kt"
click node_catalog "https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/data/Catalog.kt"
click node_covers "https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/data/CoverScanner.kt"
click node_cover_extract "https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/data/CoverExtractor.kt"
click node_db "https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/data/AppDb.kt"
click node_extractor "https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/reader/TextExtractor.kt"
click node_epub "https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/reader/EpubParser.kt"
click node_html "https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/reader/HtmlText.kt"
click node_sentences "https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/reader/Sentences.kt"
click node_tts "https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/tts/TtsService.kt"
click node_prefs "https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/data/Prefs.kt"
click node_pronounce "https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/data/Pronounce.kt"
click node_ai_chat "https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/ui/AiChatScreen.kt"
click node_ai_context "https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/ai/BookContext.kt"
click node_ai_client "https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/ai/AiClient.kt"
click node_exports "https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/data/Exporter.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_activity,node_library_ui,node_browser_ui,node_reader_ui toneBlue
class node_library_vm,node_browser_vm,node_scanner,node_metadata,node_catalog,node_covers,node_cover_extract,node_db toneAmber
class node_extractor,node_epub,node_html,node_sentences,node_tts,node_android_tts toneMint
class node_prefs,node_pronounce,node_ai_chat,node_ai_context,node_ai_client,node_exports toneRose
class node_reader toneIndigo
```

## Components

### App and navigation

- [Main activity](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/MainActivity.kt): `app/src/main/java/hu/konyvtar/tts/MainActivity.kt`
- [Library and shelf](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/ui/LibraryScreen.kt): `app/src/main/java/hu/konyvtar/tts/ui/LibraryScreen.kt`
- [File browser](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/ui/ExplorerScreen.kt): `app/src/main/java/hu/konyvtar/tts/ui/ExplorerScreen.kt`
- [Reader screen](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/ui/ReaderScreen.kt): `app/src/main/java/hu/konyvtar/tts/ui/ReaderScreen.kt`

### Library and catalog

- [Library state](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/vm/LibraryViewModel.kt): `app/src/main/java/hu/konyvtar/tts/vm/LibraryViewModel.kt`
- [Browser state](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/vm/BrowserViewModel.kt): `app/src/main/java/hu/konyvtar/tts/vm/BrowserViewModel.kt`
- [Library scanner](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/data/LibraryScanner.kt): `app/src/main/java/hu/konyvtar/tts/data/LibraryScanner.kt`
- [Metadata extraction](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/data/MetadataExtractor.kt): `app/src/main/java/hu/konyvtar/tts/data/MetadataExtractor.kt`
- [Book catalog](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/data/Catalog.kt): `app/src/main/java/hu/konyvtar/tts/data/Catalog.kt`
- [Cover scanning](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/data/CoverScanner.kt): `app/src/main/java/hu/konyvtar/tts/data/CoverScanner.kt`
- [Cover extraction](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/data/CoverExtractor.kt): `app/src/main/java/hu/konyvtar/tts/data/CoverExtractor.kt`
- [Reading records](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/data/AppDb.kt): `app/src/main/java/hu/konyvtar/tts/data/AppDb.kt`

### Reading and playback

- [Text extraction](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/reader/TextExtractor.kt): `app/src/main/java/hu/konyvtar/tts/reader/TextExtractor.kt`
- [EPUB parser](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/reader/EpubParser.kt): `app/src/main/java/hu/konyvtar/tts/reader/EpubParser.kt`
- [HTML cleanup](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/reader/HtmlText.kt): `app/src/main/java/hu/konyvtar/tts/reader/HtmlText.kt`
- [Sentence segmentation](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/reader/Sentences.kt): `app/src/main/java/hu/konyvtar/tts/reader/Sentences.kt`
- [Speech service](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/tts/TtsService.kt): `app/src/main/java/hu/konyvtar/tts/tts/TtsService.kt`
- **Android speech engine**

### Reader tools and integrations

- [Preferences](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/data/Prefs.kt): `app/src/main/java/hu/konyvtar/tts/data/Prefs.kt`
- [Pronunciation rules](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/data/Pronounce.kt): `app/src/main/java/hu/konyvtar/tts/data/Pronounce.kt`
- [AI chat](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/ui/AiChatScreen.kt): `app/src/main/java/hu/konyvtar/tts/ui/AiChatScreen.kt`
- [Book context](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/ai/BookContext.kt): `app/src/main/java/hu/konyvtar/tts/ai/BookContext.kt`
- [AI client](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/ai/AiClient.kt): `app/src/main/java/hu/konyvtar/tts/ai/AiClient.kt`
- [Export and statistics](https://github.com/sanyi1963bp/vox-libris/blob/main/app/src/main/java/hu/konyvtar/tts/data/Exporter.kt): `app/src/main/java/hu/konyvtar/tts/data/Exporter.kt`

### Other components

- **Reader**

## Connections

- Reader → Main activity: opens app
- Main activity → Library and shelf: shows views (evidence: `app/src/main/java/hu/konyvtar/tts/MainActivity.kt`)
- Main activity → File browser: routes to (evidence: `app/src/main/java/hu/konyvtar/tts/MainActivity.kt`)
- Main activity → Reader screen: routes to (evidence: `app/src/main/java/hu/konyvtar/tts/MainActivity.kt`)
- Library and shelf → Library state: uses state (evidence: `app/src/main/java/hu/konyvtar/tts/ui/LibraryScreen.kt`)
- File browser → Browser state: uses state (evidence: `app/src/main/java/hu/konyvtar/tts/ui/ExplorerScreen.kt`)
- Library state → Library scanner: starts scan (evidence: `app/src/main/java/hu/konyvtar/tts/vm/LibraryViewModel.kt`)
- Library scanner → Metadata extraction: extracts metadata (evidence: `app/src/main/java/hu/konyvtar/tts/data/LibraryScanner.kt`)
- Library scanner → Book catalog: updates catalog (evidence: `app/src/main/java/hu/konyvtar/tts/data/LibraryScanner.kt`)
- Library state → Book catalog: loads books (evidence: `app/src/main/java/hu/konyvtar/tts/vm/LibraryViewModel.kt`)
- Library state → Cover scanning: starts cover scan (evidence: `app/src/main/java/hu/konyvtar/tts/vm/LibraryViewModel.kt`)
- Cover scanning → Cover extraction: extracts covers (evidence: `app/src/main/java/hu/konyvtar/tts/data/CoverScanner.kt`)
- Cover scanning → Book catalog: reads catalog (evidence: `app/src/main/java/hu/konyvtar/tts/data/CoverScanner.kt`)
- Reader screen → Speech service: controls playback (evidence: `app/src/main/java/hu/konyvtar/tts/ui/ReaderScreen.kt`)
- Speech service → Text extraction: loads book text (evidence: `app/src/main/java/hu/konyvtar/tts/tts/TtsService.kt`)
- Text extraction → EPUB parser: dispatches EPUB (evidence: `app/src/main/java/hu/konyvtar/tts/reader/TextExtractor.kt`)
- EPUB parser → HTML cleanup: cleans markup (evidence: `app/src/main/java/hu/konyvtar/tts/reader/EpubParser.kt`)
- Speech service → Sentence segmentation: segments speech (evidence: `app/src/main/java/hu/konyvtar/tts/tts/TtsService.kt`)
- Speech service → Android speech engine: speaks text
- Speech service → Reading records: saves progress (evidence: `app/src/main/java/hu/konyvtar/tts/tts/TtsService.kt`)
- Speech service → Preferences: loads settings (evidence: `app/src/main/java/hu/konyvtar/tts/tts/TtsService.kt`)
- Speech service → Pronunciation rules: applies rules (evidence: `app/src/main/java/hu/konyvtar/tts/tts/TtsService.kt`)
- Reader screen → Reading records: manages bookmarks (evidence: `app/src/main/java/hu/konyvtar/tts/ui/ReaderScreen.kt`)
- Reader screen → AI chat: opens chat (evidence: `app/src/main/java/hu/konyvtar/tts/MainActivity.kt`)
- AI chat → Book context: builds context (evidence: `app/src/main/java/hu/konyvtar/tts/ui/AiChatScreen.kt`)
- AI chat → AI client: sends prompts (evidence: `app/src/main/java/hu/konyvtar/tts/ui/AiChatScreen.kt`)
- Reader → Export and statistics: exports records
