# wjhhm2003/readx architecture

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

- Interactive diagram: https://gitdiagram.com/wjhhm2003/readx
- Repository: https://github.com/wjhhm2003/readx

## Overview

ReadX is an offline Android reader for locally imported EPUB, TXT, and PDF files. The main workflow is opening the library, importing or selecting a book, and reading it with format-specific navigation; annotations and reading state are stored locally. PDF conversion is a separate opt-in background workflow: configure OCR, extract text or recognize pages, package an EPUB, then add or export the result. README capability descriptions fill in some unsampled implementation details; edges based on them are cited to the README.

Main entry points: [`app/src/main/java/io/readx/app/data/LibraryRepository.kt`](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/data/LibraryRepository.kt) (Book import and library), [`app/src/main/java/io/readx/app/ui/LibraryViewModel.kt`](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/ui/LibraryViewModel.kt) (Library ViewModel), [`app/src/main/java/io/readx/app/pdf/PdfActivity.kt`](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/pdf/PdfActivity.kt) (PDF activity and routing), [`app/src/main/java/io/readx/app/conversion/PdfConversionWorker.kt`](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/conversion/PdfConversionWorker.kt) (Background conversion worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and library"]
  node_main_activity["App entry<br/>[MainActivity.kt]"]
  node_app_ui["Library and navigation UI<br/>[ReadXApp.kt]"]
  node_library_vm["Library ViewModel"]
  node_library_repo["Book import and library"]
end

subgraph group_reading["Text reading"]
  node_reader_screen["Reader screen"]
  node_book_parser["EPUB and TXT parser<br/>[BookParser.kt]"]
  node_web_reader["Local web reader<br/>[LocalWebReader.kt]"]
  node_pagination["Pagination coordinator<br/>[BookPagination.kt]"]
  node_page_cache["Page index cache<br/>[PageIndexCache.kt]"]
  node_text_anchor["Text anchors and selection<br/>[TextAnchor.kt]"]
end

subgraph group_pdf["PDF reading"]
  node_pdf_activity["PDF activity and routing<br/>[PdfActivity.kt]"]
  node_pdf_advanced["Advanced PDF viewer"]
  node_pdf_fallback["PDF fallback viewer"]
  node_pdf_marks["PDF annotation overlay"]
end

subgraph group_conversion["PDF conversion"]
  node_conversion_ui["Conversion controls<br/>[PdfConversionUi.kt]"]
  node_conversion_repo["Conversion task manager"]
  node_ocr_manager["OCR model manager<br/>[OcrModelManager.kt]"]
  node_conversion_worker["Background conversion worker"]
  node_page_extractor["PDF page extraction"]
  node_text_flow["OCR and text flow<br/>[PdfTextFlow.kt]"]
  node_epub_output["EPUB packaging<br/>[EpubOutput.kt]"]
end

subgraph group_state["Local state"]
  node_application["Application services"]
  node_database[("Library database<br/>[LibraryDatabase.kt]")]
  node_preferences["Reader preferences"]
end

node_reader_user(("Reader"))
node_saf["System file picker"]

node_reader_user -->|"opens app"| node_main_activity
node_main_activity -->|"sets content"| node_app_ui
node_app_ui -->|"presents state"| node_library_vm
node_library_vm -->|"manages books"| node_library_repo
node_saf -->|"provides files"| node_library_repo
node_library_repo -->|"parses imports"| node_book_parser
node_library_repo -->|"stores book data"| node_database
node_app_ui -->|"opens reader"| node_reader_screen
node_reader_screen -->|"renders text"| node_web_reader
node_reader_screen -->|"requests pages"| node_pagination
node_pagination -->|"measures chapters"| node_book_parser
node_pagination -->|"uses layout cache"| node_page_cache
node_web_reader -->|"resolves selections"| node_text_anchor
node_library_vm -->|"saves annotations"| node_database
node_app_ui -->|"opens PDF"| node_pdf_activity
node_pdf_activity -->|"routes supported devices"| node_pdf_advanced
node_pdf_activity -->|"routes fallback devices"| node_pdf_fallback
node_pdf_activity -->|"attaches overlay"| node_pdf_marks
node_library_vm -->|"exposes task state"| node_conversion_ui
node_conversion_ui -->|"starts and controls"| node_conversion_repo
node_library_vm -->|"starts conversion"| node_conversion_repo
node_conversion_repo -->|"checks OCR models"| node_ocr_manager
node_conversion_repo -->|"enqueues work"| node_conversion_worker
node_conversion_worker -->|"extracts pages"| node_page_extractor
node_conversion_worker -->|"processes page text"| node_text_flow
node_conversion_worker -->|"packages result"| node_epub_output
node_conversion_worker -->|"imports completed EPUB"| node_library_repo
node_main_activity -->|"uses app services"| node_application
node_application -->|"creates database"| node_database
node_application -->|"creates repository"| node_library_repo
node_application -->|"creates conversion manager"| node_conversion_repo
node_application -->|"deploys bundled models"| node_ocr_manager
node_reader_screen -->|"reads reader settings"| node_preferences
node_pdf_activity -->|"reads PDF settings"| node_preferences

click node_main_activity "https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/MainActivity.kt"
click node_app_ui "https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/ui/ReadXApp.kt"
click node_library_vm "https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/ui/LibraryViewModel.kt"
click node_library_repo "https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/data/LibraryRepository.kt"
click node_reader_screen "https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/ui/ImmersiveReaderScreen.kt"
click node_book_parser "https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/reader/BookParser.kt"
click node_web_reader "https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/reader/LocalWebReader.kt"
click node_pagination "https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/reader/BookPagination.kt"
click node_page_cache "https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/reader/PageIndexCache.kt"
click node_text_anchor "https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/reader/TextAnchor.kt"
click node_pdf_activity "https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/pdf/PdfActivity.kt"
click node_pdf_advanced "https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/pdf/HorizontalPdfScreen.kt"
click node_pdf_fallback "https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/pdf/FallbackPdfScreen.kt"
click node_pdf_marks "https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/pdf/PdfAnnotationOverlay.kt"
click node_conversion_ui "https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/ui/PdfConversionUi.kt"
click node_conversion_repo "https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/conversion/PdfConversionRepository.kt"
click node_ocr_manager "https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/conversion/OcrModelManager.kt"
click node_conversion_worker "https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/conversion/PdfConversionWorker.kt"
click node_page_extractor "https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/conversion/PdfPageExtractor.kt"
click node_text_flow "https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/conversion/PdfTextFlow.kt"
click node_epub_output "https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/conversion/EpubOutput.kt"
click node_application "https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/ReadXApplication.kt"
click node_database "https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/data/LibraryDatabase.kt"
click node_preferences "https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/ui/ReaderPreferences.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_main_activity,node_app_ui,node_library_vm,node_library_repo toneBlue
class node_reader_screen,node_book_parser,node_web_reader,node_pagination,node_page_cache,node_text_anchor toneAmber
class node_pdf_activity,node_pdf_advanced,node_pdf_fallback,node_pdf_marks toneMint
class node_conversion_ui,node_conversion_repo,node_ocr_manager,node_conversion_worker,node_page_extractor,node_text_flow,node_epub_output toneRose
class node_application,node_database,node_preferences,node_reader_user,node_saf toneIndigo
```

## Components

### App and library

- [App entry](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/MainActivity.kt): `app/src/main/java/io/readx/app/MainActivity.kt`
- [Library and navigation UI](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/ui/ReadXApp.kt): `app/src/main/java/io/readx/app/ui/ReadXApp.kt`
- [Library ViewModel](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/ui/LibraryViewModel.kt): `app/src/main/java/io/readx/app/ui/LibraryViewModel.kt`
- [Book import and library](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/data/LibraryRepository.kt): `app/src/main/java/io/readx/app/data/LibraryRepository.kt`

### Text reading

- [Reader screen](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/ui/ImmersiveReaderScreen.kt): `app/src/main/java/io/readx/app/ui/ImmersiveReaderScreen.kt`
- [EPUB and TXT parser](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/reader/BookParser.kt): `app/src/main/java/io/readx/app/reader/BookParser.kt`
- [Local web reader](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/reader/LocalWebReader.kt): `app/src/main/java/io/readx/app/reader/LocalWebReader.kt`
- [Pagination coordinator](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/reader/BookPagination.kt): `app/src/main/java/io/readx/app/reader/BookPagination.kt`
- [Page index cache](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/reader/PageIndexCache.kt): `app/src/main/java/io/readx/app/reader/PageIndexCache.kt`
- [Text anchors and selection](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/reader/TextAnchor.kt): `app/src/main/java/io/readx/app/reader/TextAnchor.kt`

### PDF reading

- [PDF activity and routing](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/pdf/PdfActivity.kt): `app/src/main/java/io/readx/app/pdf/PdfActivity.kt`
- [Advanced PDF viewer](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/pdf/HorizontalPdfScreen.kt): `app/src/main/java/io/readx/app/pdf/HorizontalPdfScreen.kt`
- [PDF fallback viewer](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/pdf/FallbackPdfScreen.kt): `app/src/main/java/io/readx/app/pdf/FallbackPdfScreen.kt`
- [PDF annotation overlay](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/pdf/PdfAnnotationOverlay.kt): `app/src/main/java/io/readx/app/pdf/PdfAnnotationOverlay.kt`

### PDF conversion

- [Conversion controls](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/ui/PdfConversionUi.kt): `app/src/main/java/io/readx/app/ui/PdfConversionUi.kt`
- [Conversion task manager](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/conversion/PdfConversionRepository.kt): `app/src/main/java/io/readx/app/conversion/PdfConversionRepository.kt`
- [OCR model manager](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/conversion/OcrModelManager.kt): `app/src/main/java/io/readx/app/conversion/OcrModelManager.kt`
- [Background conversion worker](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/conversion/PdfConversionWorker.kt): `app/src/main/java/io/readx/app/conversion/PdfConversionWorker.kt`
- [PDF page extraction](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/conversion/PdfPageExtractor.kt): `app/src/main/java/io/readx/app/conversion/PdfPageExtractor.kt`
- [OCR and text flow](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/conversion/PdfTextFlow.kt): `app/src/main/java/io/readx/app/conversion/PdfTextFlow.kt`
- [EPUB packaging](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/conversion/EpubOutput.kt): `app/src/main/java/io/readx/app/conversion/EpubOutput.kt`

### Local state

- [Application services](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/ReadXApplication.kt): `app/src/main/java/io/readx/app/ReadXApplication.kt`
- [Library database](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/data/LibraryDatabase.kt): `app/src/main/java/io/readx/app/data/LibraryDatabase.kt`
- [Reader preferences](https://github.com/wjhhm2003/readx/blob/main/app/src/main/java/io/readx/app/ui/ReaderPreferences.kt): `app/src/main/java/io/readx/app/ui/ReaderPreferences.kt`

### Other components

- **Reader**
- **System file picker**

## Connections

- Reader → App entry: opens app
- App entry → Library and navigation UI: sets content (evidence: `app/src/main/java/io/readx/app/MainActivity.kt`)
- Library and navigation UI → Library ViewModel: presents state (evidence: `app/src/main/java/io/readx/app/ui/ReadXApp.kt`)
- Library ViewModel → Book import and library: manages books (evidence: `app/src/main/java/io/readx/app/ui/LibraryViewModel.kt`)
- System file picker → Book import and library: provides files
- Book import and library → EPUB and TXT parser: parses imports (evidence: `app/src/main/java/io/readx/app/data/LibraryRepository.kt`)
- Book import and library → Library database: stores book data (evidence: `app/src/main/java/io/readx/app/data/LibraryRepository.kt`)
- Library and navigation UI → Reader screen: opens reader (evidence: `app/src/main/java/io/readx/app/ui/ReadXApp.kt`)
- Reader screen → Local web reader: renders text
- Reader screen → Pagination coordinator: requests pages
- Pagination coordinator → EPUB and TXT parser: measures chapters (evidence: `app/src/main/java/io/readx/app/reader/BookPagination.kt`)
- Pagination coordinator → Page index cache: uses layout cache (evidence: `app/src/main/java/io/readx/app/reader/BookPagination.kt`)
- Local web reader → Text anchors and selection: resolves selections (evidence: `app/src/main/java/io/readx/app/reader/LocalWebReader.kt`)
- Library ViewModel → Library database: saves annotations (evidence: `app/src/main/java/io/readx/app/ui/LibraryViewModel.kt`)
- Library and navigation UI → PDF activity and routing: opens PDF (evidence: `app/src/main/java/io/readx/app/ui/ReadXApp.kt`)
- PDF activity and routing → Advanced PDF viewer: routes supported devices (evidence: `app/src/main/java/io/readx/app/pdf/PdfActivity.kt`)
- PDF activity and routing → PDF fallback viewer: routes fallback devices
- PDF activity and routing → PDF annotation overlay: attaches overlay (evidence: `app/src/main/java/io/readx/app/pdf/PdfActivity.kt`)
- Library ViewModel → Conversion controls: exposes task state (evidence: `app/src/main/java/io/readx/app/ui/PdfConversionUi.kt`)
- Conversion controls → Conversion task manager: starts and controls
- Library ViewModel → Conversion task manager: starts conversion (evidence: `app/src/main/java/io/readx/app/ui/LibraryViewModel.kt`)
- Conversion task manager → OCR model manager: checks OCR models (evidence: `app/src/main/java/io/readx/app/conversion/PdfConversionRepository.kt`)
- Conversion task manager → Background conversion worker: enqueues work (evidence: `app/src/main/java/io/readx/app/conversion/PdfConversionRepository.kt`)
- Background conversion worker → PDF page extraction: extracts pages (evidence: `app/src/main/java/io/readx/app/conversion/PdfConversionWorker.kt`)
- Background conversion worker → OCR and text flow: processes page text (evidence: `app/src/main/java/io/readx/app/conversion/PdfConversionWorker.kt`)
- Background conversion worker → EPUB packaging: packages result (evidence: `app/src/main/java/io/readx/app/conversion/PdfConversionWorker.kt`)
- Background conversion worker → Book import and library: imports completed EPUB (evidence: `app/src/main/java/io/readx/app/conversion/PdfConversionWorker.kt`)
- App entry → Application services: uses app services (evidence: `app/src/main/java/io/readx/app/ReadXApplication.kt`)
- Application services → Library database: creates database (evidence: `app/src/main/java/io/readx/app/ReadXApplication.kt`)
- Application services → Book import and library: creates repository (evidence: `app/src/main/java/io/readx/app/ReadXApplication.kt`)
- Application services → Conversion task manager: creates conversion manager (evidence: `app/src/main/java/io/readx/app/ReadXApplication.kt`)
- Application services → OCR model manager: deploys bundled models (evidence: `app/src/main/java/io/readx/app/ReadXApplication.kt`)
- Reader screen → Reader preferences: reads reader settings
- PDF activity and routing → Reader preferences: reads PDF settings (evidence: `app/src/main/java/io/readx/app/pdf/PdfActivity.kt`)
