# huangder/lumi_books architecture

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

- Interactive diagram: https://gitdiagram.com/huangder/lumi_books
- Repository: https://github.com/huangder/lumi_books

## Overview

Lumi is a local-first Android ebook and comic reader. A reader imports or authorizes books, manages them on the bookshelf, opens a format-specific reader, and saves reading progress and annotations locally. The app also offers TTS, reading statistics, WebDAV synchronization and backup, and optional PDF conversion through MinerU. The tree and README establish these product areas; sampled source excerpts are limited, so uncertain internal call wiring is not shown.

Main entry points: [`app/src/main/java/com/huangder/lumibooks/ui/reader/ReaderScreen.kt`](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/ui/reader/ReaderScreen.kt) (Reader screen), [`app/src/main/java/com/huangder/lumibooks/data/repository/BookRepositoryImpl.kt`](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/data/repository/BookRepositoryImpl.kt) (Book repository), [`app/src/main/java/com/huangder/lumibooks/ui/navigation/NavGraph.kt`](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/ui/navigation/NavGraph.kt) (Navigation), [`app/src/main/java/com/huangder/lumibooks/tts/TtsController.kt`](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/tts/TtsController.kt) (TTS playback)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App experience"]
  node_reader["Reader<br/>[MainActivity.kt]"]
  node_navigation["Navigation<br/>[NavGraph.kt]"]
  node_home["Home and stats<br/>[HomeScreen.kt]"]
  node_settings["Reader settings"]
end

subgraph group_library["Library and data"]
  node_bookshelf["Bookshelf<br/>[BookshelfScreen.kt]"]
  node_import["Book import"]
  node_storage_access["Authorized storage"]
  node_book_repository["Book repository"]
  node_reading_repository["Reading repository"]
  node_database[("Local database<br/>[AppDatabase.kt]")]
  node_preferences[("Preferences")]
end

subgraph group_reading["Reading experience"]
  node_reader_screen["Reader screen<br/>[ReaderScreen.kt]"]
  node_reader_viewmodel["Reader state<br/>[ReaderViewModel.kt]"]
  node_epub["EPUB reader"]
  node_raster["Raster reader"]
  node_text_layout["Text layout engine"]
end

subgraph group_services["Reading services"]
  node_tts["TTS playback<br/>[TtsController.kt]"]
  node_tts_service["Playback service"]
  node_system_tts["System TTS engine<br/>[TtsEngine.kt]"]
  node_external_tts["External TTS"]
end

subgraph group_cloud["Sync and conversion"]
  node_webdav_sync["WebDAV sync"]
  node_webdav_server(("WebDAV server"))
  node_backup["Backup and restore"]
  node_pdf_conversion["PDF conversion"]
  node_mineru(("MinerU service"))
end

node_user(("Reader"))
node_system_tts_actor(("Android TTS"))

node_user -->|"opens app"| node_reader
node_reader -->|"shows destinations"| node_navigation
node_navigation -->|"routes"| node_home
node_navigation -->|"routes"| node_bookshelf
node_navigation -->|"routes"| node_reader_screen
node_user -->|"selects books"| node_import
node_import -->|"authorizes or reads"| node_storage_access
node_import -->|"adds books"| node_book_repository
node_bookshelf -->|"loads and manages"| node_book_repository
node_book_repository -->|"reads and writes"| node_database
node_reader_screen -->|"handles reading state"| node_reader_viewmodel
node_reader_viewmodel -->|"loads book"| node_book_repository
node_reader_viewmodel -->|"saves progress"| node_reading_repository
node_reading_repository -->|"reads and writes"| node_database
node_reader_screen -->|"renders EPUB"| node_epub
node_reader_screen -->|"renders PDF or CBZ"| node_raster
node_reader_screen -->|"lays out text"| node_text_layout
node_settings -->|"reads and saves settings"| node_preferences
node_home -->|"loads statistics"| node_reading_repository
node_reader_screen -->|"starts playback"| node_tts
node_tts_service -->|"controls playback"| node_tts
node_tts -->|"speaks with"| node_system_tts
node_system_tts -->|"uses engine"| node_system_tts_actor
node_tts -.->|"selects provider"| node_external_tts
node_webdav_sync -->|"syncs book data"| node_book_repository
node_webdav_sync -->|"syncs reading data"| node_reading_repository
node_webdav_sync -.->|"transfers data"| node_webdav_server
node_backup -->|"archives data"| node_database
node_backup -->|"archives settings"| node_preferences
node_pdf_conversion -.->|"requests conversion"| node_mineru

click node_reader "https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/MainActivity.kt"
click node_navigation "https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/ui/navigation/NavGraph.kt"
click node_home "https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/ui/home/HomeScreen.kt"
click node_settings "https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/ui/settings/ReaderSettingsPreviewActivity.kt"
click node_bookshelf "https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/ui/bookshelf/BookshelfScreen.kt"
click node_import "https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/ui/home/ImportBooksSheet.kt"
click node_storage_access "https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/util/AuthorizedStorageManager.kt"
click node_book_repository "https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/data/repository/BookRepositoryImpl.kt"
click node_reading_repository "https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/data/repository/ReadingRepositoryImpl.kt"
click node_database "https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/data/local/database/AppDatabase.kt"
click node_preferences "https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/data/local/DataStoreManager.kt"
click node_reader_screen "https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/ui/reader/ReaderScreen.kt"
click node_reader_viewmodel "https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/ui/reader/ReaderViewModel.kt"
click node_epub "https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/ui/reader/EpubWebViewReader.kt"
click node_raster "https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/ui/reader/RasterReaderScreen.kt"
click node_text_layout "https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/ui/reader/engine/PageLayoutEngine.kt"
click node_tts "https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/tts/TtsController.kt"
click node_tts_service "https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/service/TtsForegroundService.kt"
click node_system_tts "https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/tts/TtsEngine.kt"
click node_external_tts "https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/tts/ExternalTtsEngine.kt"
click node_webdav_sync "https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/data/sync/WebdavSyncManager.kt"
click node_backup "https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/data/backup/BackupArchiveManager.kt"
click node_pdf_conversion "https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/pdfconversion/PdfConversionManager.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_reader,node_navigation,node_home,node_settings toneBlue
class node_bookshelf,node_import,node_storage_access,node_book_repository,node_reading_repository,node_database,node_preferences toneAmber
class node_reader_screen,node_reader_viewmodel,node_epub,node_raster,node_text_layout toneMint
class node_tts,node_tts_service,node_system_tts,node_external_tts toneRose
class node_webdav_sync,node_webdav_server,node_backup,node_pdf_conversion,node_mineru,node_user,node_system_tts_actor toneIndigo
```

## Components

### App experience

- [Reader](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/MainActivity.kt): `app/src/main/java/com/huangder/lumibooks/MainActivity.kt`
- [Navigation](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/ui/navigation/NavGraph.kt): `app/src/main/java/com/huangder/lumibooks/ui/navigation/NavGraph.kt`
- [Home and stats](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/ui/home/HomeScreen.kt): `app/src/main/java/com/huangder/lumibooks/ui/home/HomeScreen.kt`
- [Reader settings](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/ui/settings/ReaderSettingsPreviewActivity.kt): `app/src/main/java/com/huangder/lumibooks/ui/settings/ReaderSettingsPreviewActivity.kt`

### Library and data

- [Bookshelf](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/ui/bookshelf/BookshelfScreen.kt): `app/src/main/java/com/huangder/lumibooks/ui/bookshelf/BookshelfScreen.kt`
- [Book import](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/ui/home/ImportBooksSheet.kt): `app/src/main/java/com/huangder/lumibooks/ui/home/ImportBooksSheet.kt`
- [Authorized storage](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/util/AuthorizedStorageManager.kt): `app/src/main/java/com/huangder/lumibooks/util/AuthorizedStorageManager.kt`
- [Book repository](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/data/repository/BookRepositoryImpl.kt): `app/src/main/java/com/huangder/lumibooks/data/repository/BookRepositoryImpl.kt`
- [Reading repository](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/data/repository/ReadingRepositoryImpl.kt): `app/src/main/java/com/huangder/lumibooks/data/repository/ReadingRepositoryImpl.kt`
- [Local database](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/data/local/database/AppDatabase.kt): `app/src/main/java/com/huangder/lumibooks/data/local/database/AppDatabase.kt`
- [Preferences](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/data/local/DataStoreManager.kt): `app/src/main/java/com/huangder/lumibooks/data/local/DataStoreManager.kt`

### Reading experience

- [Reader screen](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/ui/reader/ReaderScreen.kt): `app/src/main/java/com/huangder/lumibooks/ui/reader/ReaderScreen.kt`
- [Reader state](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/ui/reader/ReaderViewModel.kt): `app/src/main/java/com/huangder/lumibooks/ui/reader/ReaderViewModel.kt`
- [EPUB reader](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/ui/reader/EpubWebViewReader.kt): `app/src/main/java/com/huangder/lumibooks/ui/reader/EpubWebViewReader.kt`
- [Raster reader](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/ui/reader/RasterReaderScreen.kt): `app/src/main/java/com/huangder/lumibooks/ui/reader/RasterReaderScreen.kt`
- [Text layout engine](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/ui/reader/engine/PageLayoutEngine.kt): `app/src/main/java/com/huangder/lumibooks/ui/reader/engine/PageLayoutEngine.kt`

### Reading services

- [TTS playback](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/tts/TtsController.kt): `app/src/main/java/com/huangder/lumibooks/tts/TtsController.kt`
- [Playback service](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/service/TtsForegroundService.kt): `app/src/main/java/com/huangder/lumibooks/service/TtsForegroundService.kt`
- [System TTS engine](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/tts/TtsEngine.kt): `app/src/main/java/com/huangder/lumibooks/tts/TtsEngine.kt`
- [External TTS](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/tts/ExternalTtsEngine.kt): `app/src/main/java/com/huangder/lumibooks/tts/ExternalTtsEngine.kt`

### Sync and conversion

- [WebDAV sync](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/data/sync/WebdavSyncManager.kt): `app/src/main/java/com/huangder/lumibooks/data/sync/WebdavSyncManager.kt`
- **WebDAV server**
- [Backup and restore](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/data/backup/BackupArchiveManager.kt): `app/src/main/java/com/huangder/lumibooks/data/backup/BackupArchiveManager.kt`
- [PDF conversion](https://github.com/huangder/lumi_books/blob/main/app/src/main/java/com/huangder/lumibooks/pdfconversion/PdfConversionManager.kt): `app/src/main/java/com/huangder/lumibooks/pdfconversion/PdfConversionManager.kt`
- **MinerU service**

### Other components

- **Reader**
- **Android TTS**

## Connections

- Reader → Reader: opens app
- Reader → Navigation: shows destinations
- Navigation → Home and stats: routes
- Navigation → Bookshelf: routes
- Navigation → Reader screen: routes
- Reader → Book import: selects books
- Book import → Authorized storage: authorizes or reads
- Book import → Book repository: adds books
- Bookshelf → Book repository: loads and manages
- Book repository → Local database: reads and writes
- Reader screen → Reader state: handles reading state
- Reader state → Book repository: loads book
- Reader state → Reading repository: saves progress
- Reading repository → Local database: reads and writes
- Reader screen → EPUB reader: renders EPUB
- Reader screen → Raster reader: renders PDF or CBZ
- Reader screen → Text layout engine: lays out text
- Reader settings → Preferences: reads and saves settings
- Home and stats → Reading repository: loads statistics
- Reader screen → TTS playback: starts playback
- Playback service → TTS playback: controls playback
- TTS playback → System TTS engine: speaks with
- System TTS engine → Android TTS: uses engine
- TTS playback → External TTS: selects provider
- WebDAV sync → Book repository: syncs book data
- WebDAV sync → Reading repository: syncs reading data
- WebDAV sync → WebDAV server: transfers data
- Backup and restore → Local database: archives data
- Backup and restore → Preferences: archives settings
- PDF conversion → MinerU service: requests conversion