# darkwarrior2005/folio-app architecture

> Architecture diagram of the GitHub repository darkwarrior2005/folio-app, 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/darkwarrior2005/folio-app
- Repository: https://github.com/darkwarrior2005/folio-app

## Overview

Folio is an offline-first Android reading library. The main workflow is selecting files, importing and indexing them, organizing the resulting library, and reading through a format-specific engine while shared progress and annotations are stored locally. The graph also preserves the documented search, backup, music, Pomodoro, statistics, and privacy/settings capabilities. Several screen and service implementations were not sampled, so their connections are omitted or marked unverified rather than inferred from names.

Main entry points: [`app/src/main/java/app/folio/AppContainer.kt`](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/AppContainer.kt) (App services), [`app/src/main/java/app/folio/data/db/FolioDatabase.kt`](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/data/db/FolioDatabase.kt) (Room database), [`app/src/main/java/app/folio/reader/ReaderRegistry.kt`](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/reader/ReaderRegistry.kt) (Reader registry), [`app/src/main/java/app/folio/importer/ImportManager.kt`](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/importer/ImportManager.kt) (Import manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and UI"]
  node_activity["Android entry<br/>[MainActivity.kt]"]
  node_root["Compose navigation<br/>[FolioRoot.kt]"]
  node_container["App services<br/>[AppContainer.kt]"]
end

subgraph group_library["Library workflow"]
  node_import["Import manager<br/>[ImportManager.kt]"]
  node_index["Text indexing<br/>[IndexWorker.kt]"]
  node_libraryrepo["Library repository"]
  node_organization["Library organization"]
  node_search["Search"]
  node_libraryquery["Library filtering<br/>[LibraryQuery.kt]"]
end

subgraph group_reading["Reading experience"]
  node_readerscreen["Reader screen<br/>[ReaderScreen.kt]"]
  node_registry["Reader registry<br/>[ReaderRegistry.kt]"]
  node_epub["EPUB engine<br/>[EpubEngine.kt]"]
  node_pdf["PDF engine<br/>[PdfEngine.kt]"]
  node_comic["Comic engine<br/>[ComicEngine.kt]"]
  node_text["Text engine<br/>[TextEngine.kt]"]
end

subgraph group_storage["Local data"]
  node_readingrepo["Progress and sessions"]
  node_annotations["Annotations and ink"]
  node_database[("Room database<br/>[FolioDatabase.kt]")]
  node_files["Picked-file access<br/>[FileAccess.kt]"]
  node_cache["Local file cache<br/>[CacheStore.kt]"]
  node_backup["Backup and restore"]
  node_settings["Settings and privacy"]
end

subgraph group_focus["Focus and media"]
  node_pomodoro["Pomodoro timer<br/>[PomodoroEngine.kt]"]
  node_music["Reading music<br/>[MusicRepository.kt]"]
  node_stats["Reading statistics<br/>[StatsCalculator.kt]"]
end

node_reader(("Reader"))

node_reader -.->|"opens app"| node_activity
node_activity -->|"shows UI"| node_root
node_activity -->|"uses services"| node_container
node_container -->|"creates"| node_database
node_container -->|"provides"| node_libraryrepo
node_container -->|"provides"| node_readingrepo
node_container -->|"provides"| node_search
node_container -->|"creates"| node_import
node_container -->|"registers engines"| node_registry
node_container -->|"provides"| node_settings
node_import -->|"accesses picks"| node_files
node_import -->|"extracts metadata"| node_registry
node_import -->|"adds books"| node_libraryrepo
node_import -->|"stages files"| node_cache
node_libraryrepo -->|"filters library"| node_libraryquery
node_libraryrepo -->|"reads and writes"| node_database
node_search -->|"queries index"| node_database
node_index -->|"indexes text"| node_database
node_readerscreen -.->|"selects engine"| node_registry
node_registry -->|"dispatches format"| node_epub
node_registry -->|"dispatches format"| node_pdf
node_registry -->|"dispatches format"| node_comic
node_registry -->|"dispatches format"| node_text
node_readingrepo -->|"stores progress"| node_database
node_annotations -->|"stores annotations"| node_database
node_backup -->|"backs up data"| node_database
node_backup -->|"reads picked files"| node_files
node_backup -->|"restores covers"| node_cache
node_pomodoro -->|"records sessions"| node_readingrepo
node_pomodoro -->|"reads settings"| node_settings
node_music -->|"stores tracks"| node_database
node_stats -.->|"summarizes sessions"| node_readingrepo

click node_activity "https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/MainActivity.kt"
click node_root "https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/ui/FolioRoot.kt"
click node_container "https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/AppContainer.kt"
click node_import "https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/importer/ImportManager.kt"
click node_index "https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/importer/IndexWorker.kt"
click node_libraryrepo "https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/data/repo/LibraryRepository.kt"
click node_organization "https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/data/repo/OrganizationRepository.kt"
click node_search "https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/data/repo/SearchRepository.kt"
click node_libraryquery "https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/core/model/LibraryQuery.kt"
click node_readerscreen "https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/ui/screens/reader/ReaderScreen.kt"
click node_registry "https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/reader/ReaderRegistry.kt"
click node_epub "https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/reader/epub/EpubEngine.kt"
click node_pdf "https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/reader/pdf/PdfEngine.kt"
click node_comic "https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/reader/comic/ComicEngine.kt"
click node_text "https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/reader/text/TextEngine.kt"
click node_readingrepo "https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/data/repo/ReadingRepository.kt"
click node_annotations "https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/data/repo/AnnotationRepository.kt"
click node_database "https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/data/db/FolioDatabase.kt"
click node_files "https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/data/files/FileAccess.kt"
click node_cache "https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/data/files/CacheStore.kt"
click node_backup "https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/data/backup/BackupRepository.kt"
click node_settings "https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/data/settings/SettingsRepository.kt"
click node_pomodoro "https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/pomodoro/PomodoroEngine.kt"
click node_music "https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/data/repo/MusicRepository.kt"
click node_stats "https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/core/model/StatsCalculator.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_root,node_container toneBlue
class node_import,node_index,node_libraryrepo,node_organization,node_search,node_libraryquery toneAmber
class node_readerscreen,node_registry,node_epub,node_pdf,node_comic,node_text toneMint
class node_readingrepo,node_annotations,node_database,node_files,node_cache,node_backup,node_settings toneRose
class node_pomodoro,node_music,node_stats,node_reader toneIndigo
```

## Components

### App and UI

- [Android entry](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/MainActivity.kt): `app/src/main/java/app/folio/MainActivity.kt`
- [Compose navigation](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/ui/FolioRoot.kt): `app/src/main/java/app/folio/ui/FolioRoot.kt`
- [App services](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/AppContainer.kt): `app/src/main/java/app/folio/AppContainer.kt`

### Library workflow

- [Import manager](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/importer/ImportManager.kt): `app/src/main/java/app/folio/importer/ImportManager.kt`
- [Text indexing](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/importer/IndexWorker.kt): `app/src/main/java/app/folio/importer/IndexWorker.kt`
- [Library repository](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/data/repo/LibraryRepository.kt): `app/src/main/java/app/folio/data/repo/LibraryRepository.kt`
- [Library organization](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/data/repo/OrganizationRepository.kt): `app/src/main/java/app/folio/data/repo/OrganizationRepository.kt`
- [Search](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/data/repo/SearchRepository.kt): `app/src/main/java/app/folio/data/repo/SearchRepository.kt`
- [Library filtering](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/core/model/LibraryQuery.kt): `app/src/main/java/app/folio/core/model/LibraryQuery.kt`

### Reading experience

- [Reader screen](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/ui/screens/reader/ReaderScreen.kt): `app/src/main/java/app/folio/ui/screens/reader/ReaderScreen.kt`
- [Reader registry](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/reader/ReaderRegistry.kt): `app/src/main/java/app/folio/reader/ReaderRegistry.kt`
- [EPUB engine](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/reader/epub/EpubEngine.kt): `app/src/main/java/app/folio/reader/epub/EpubEngine.kt`
- [PDF engine](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/reader/pdf/PdfEngine.kt): `app/src/main/java/app/folio/reader/pdf/PdfEngine.kt`
- [Comic engine](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/reader/comic/ComicEngine.kt): `app/src/main/java/app/folio/reader/comic/ComicEngine.kt`
- [Text engine](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/reader/text/TextEngine.kt): `app/src/main/java/app/folio/reader/text/TextEngine.kt`

### Local data

- [Progress and sessions](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/data/repo/ReadingRepository.kt): `app/src/main/java/app/folio/data/repo/ReadingRepository.kt`
- [Annotations and ink](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/data/repo/AnnotationRepository.kt): `app/src/main/java/app/folio/data/repo/AnnotationRepository.kt`
- [Room database](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/data/db/FolioDatabase.kt): `app/src/main/java/app/folio/data/db/FolioDatabase.kt`
- [Picked-file access](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/data/files/FileAccess.kt): `app/src/main/java/app/folio/data/files/FileAccess.kt`
- [Local file cache](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/data/files/CacheStore.kt): `app/src/main/java/app/folio/data/files/CacheStore.kt`
- [Backup and restore](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/data/backup/BackupRepository.kt): `app/src/main/java/app/folio/data/backup/BackupRepository.kt`
- [Settings and privacy](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/data/settings/SettingsRepository.kt): `app/src/main/java/app/folio/data/settings/SettingsRepository.kt`

### Focus and media

- [Pomodoro timer](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/pomodoro/PomodoroEngine.kt): `app/src/main/java/app/folio/pomodoro/PomodoroEngine.kt`
- [Reading music](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/data/repo/MusicRepository.kt): `app/src/main/java/app/folio/data/repo/MusicRepository.kt`
- [Reading statistics](https://github.com/darkwarrior2005/folio-app/blob/main/app/src/main/java/app/folio/core/model/StatsCalculator.kt): `app/src/main/java/app/folio/core/model/StatsCalculator.kt`

### Other components

- **Reader**

## Connections

- Reader → Android entry: opens app
- Android entry → Compose navigation: shows UI (evidence: `app/src/main/java/app/folio/MainActivity.kt`)
- Android entry → App services: uses services (evidence: `app/src/main/java/app/folio/MainActivity.kt`)
- App services → Room database: creates (evidence: `app/src/main/java/app/folio/AppContainer.kt`)
- App services → Library repository: provides (evidence: `app/src/main/java/app/folio/AppContainer.kt`)
- App services → Progress and sessions: provides (evidence: `app/src/main/java/app/folio/AppContainer.kt`)
- App services → Search: provides (evidence: `app/src/main/java/app/folio/AppContainer.kt`)
- App services → Import manager: creates (evidence: `app/src/main/java/app/folio/AppContainer.kt`)
- App services → Reader registry: registers engines (evidence: `app/src/main/java/app/folio/AppContainer.kt`)
- App services → Settings and privacy: provides (evidence: `app/src/main/java/app/folio/AppContainer.kt`)
- Import manager → Picked-file access: accesses picks (evidence: `app/src/main/java/app/folio/importer/ImportManager.kt`)
- Import manager → Reader registry: extracts metadata (evidence: `app/src/main/java/app/folio/importer/ImportManager.kt`)
- Import manager → Library repository: adds books (evidence: `app/src/main/java/app/folio/importer/ImportManager.kt`)
- Import manager → Local file cache: stages files (evidence: `app/src/main/java/app/folio/importer/ImportManager.kt`)
- Library repository → Library filtering: filters library (evidence: `app/src/main/java/app/folio/data/repo/LibraryRepository.kt`)
- Library repository → Room database: reads and writes (evidence: `app/src/main/java/app/folio/data/repo/LibraryRepository.kt`)
- Search → Room database: queries index (evidence: `app/src/main/java/app/folio/data/repo/SearchRepository.kt`)
- Text indexing → Room database: indexes text (evidence: `app/src/main/java/app/folio/importer/IndexWorker.kt`)
- Reader screen → Reader registry: selects engine
- Reader registry → EPUB engine: dispatches format (evidence: `app/src/main/java/app/folio/AppContainer.kt`)
- Reader registry → PDF engine: dispatches format (evidence: `app/src/main/java/app/folio/AppContainer.kt`)
- Reader registry → Comic engine: dispatches format (evidence: `app/src/main/java/app/folio/AppContainer.kt`)
- Reader registry → Text engine: dispatches format (evidence: `app/src/main/java/app/folio/AppContainer.kt`)
- Progress and sessions → Room database: stores progress (evidence: `app/src/main/java/app/folio/data/db/FolioDatabase.kt`)
- Annotations and ink → Room database: stores annotations (evidence: `app/src/main/java/app/folio/data/db/FolioDatabase.kt`)
- Backup and restore → Room database: backs up data (evidence: `app/src/main/java/app/folio/data/backup/BackupRepository.kt`)
- Backup and restore → Picked-file access: reads picked files (evidence: `app/src/main/java/app/folio/data/backup/BackupRepository.kt`)
- Backup and restore → Local file cache: restores covers (evidence: `app/src/main/java/app/folio/data/backup/BackupRepository.kt`)
- Pomodoro timer → Progress and sessions: records sessions (evidence: `app/src/main/java/app/folio/pomodoro/PomodoroEngine.kt`)
- Pomodoro timer → Settings and privacy: reads settings (evidence: `app/src/main/java/app/folio/pomodoro/PomodoroEngine.kt`)
- Reading music → Room database: stores tracks (evidence: `app/src/main/java/app/folio/data/db/FolioDatabase.kt`)
- Reading statistics → Progress and sessions: summarizes sessions