# koodo-reader/koodo-reader architecture

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

- Interactive diagram: https://gitdiagram.com/koodo-reader/koodo-reader
- Repository: https://github.com/koodo-reader/koodo-reader

## Overview

1. **What this repo is**
   - Koodo Reader is a cross-platform ebook reader with one shared TypeScript/React codebase, packaged for Electron desktop, web, and Docker-based deployment.
   - The architecture is primarily a client-side application; there is no large custom backend in this repo.

2. **Runtime boundaries**
   - The main separation is **Electron main process** versus **renderer/web app**.
   - `main.js` is the desktop bootstrap, while `httpServer.js` supports serving the app in web/server mode.
   - Most product logic lives in `src/`, and is reused across desktop and web builds.

3. **App shell and routing**
   - `src/index.tsx` boots the React app, `src/router/` defines the top-level navigation, and `src/pages/` contains the route-level screens.
   - The major page boundaries are `login`, `manager`, `reader`, and `redirect`, which correspond to authentication, library management, reading, and route handoff.

4. **Primary user-facing subsystems**
   - `manager` is the library/admin surface for books, shelves, notes, settings, backup, and import/export flows.
   - `reader` is the reading surface and contains layout, navigation, progress, text selection, and reading controls.
   - `login` handles cloud/service authentication, which is relevant because the app syncs with external storage providers.

5. **UI composition pattern**
   - `src/containers/` provides page-level layout and feature wrappers such as header, sidebar, panels, lists, viewer, and settings sections.
   - `src/components/` contains reusable UI widgets and dialogs, including import, delete, backup, settings, speech, OPDS, update, and sorting dialogs.
   - This indicates a strongly componentized frontend with feature dialogs and panels assembled into the page shells.

6. **State management**
   - `src/store/` uses Redux-style actions and reducers to coordinate book state, manager state, reader state, sidebar state, progress, backup page state, and view area state.
   - The store is the main in-app coordination layer between UI actions and persistence/data services.
   - It is especially important for drawing the architecture because many dialogs and panels are state-driven rather than locally self-managed.

7. **Domain model and persistence**
   - `src/models/` defines the core domain entities: `Book`, `BookLocation`, `Bookmark`, `Note`, `Plugin`, `HtmlBook`, and `DictHistory`.
   - The data layer is split between `src/utils/storage/databaseService.ts` and `src/utils/storage/syncService.ts`.
   - This suggests a local-first model where book metadata, reading progress, notes, and related entities are stored locally and optionally synchronized.

8. **File and content processing pipeline**
   - `src/utils/file/` handles book import, local file access, backup/restore, export, cover extraction, configuration, and background assets.
   - `src/utils/reader/` contains reading-specific behavior such as document handling, style/theme control, TTS, mouse interaction, notes, and launch logic.
   - This is the core data flow for imported content: file intake → parsing/normalization → persistence → reading/rendering.

9. **External services and cloud integration**
   - `src/utils/request/` is split into `common`, `reader`, `thirdparty`, and `user`, which implies distinct API boundaries for app services, user/session operations, reader features, and third-party integrations.
   - The README explicitly lists sync/import support for OneDrive, Google Drive, Dropbox, iCloud, MEGA, pCloud, Yandex Disk, Box, FTP/SFTP, WebDAV, SMB, and object storage.
   - Architecturally, these are not just “export targets”; they are a major synchronization/import boundary for the app.

10. **Embedded client-side engines**
   - `public/lib/` bundles substantial runtime dependencies: `pdfjs`, `7z-wasm`, `libunrar`, `sqljs-wasm`, `onnxruntime-web`, `tesseractjs`, and others.
   - This means many heavyweight operations happen inside the client runtime, not on a remote server: PDF rendering, archive extraction, OCR, local SQL storage, and ML-based features.
   - These libraries materially shape the architecture because they enable broad format support without a separate backend service.

11. **Reading feature surface**
   - The reader subsystem supports text selection, translation/dictionary popups, bookmarks, notes, highlights, speech/TTS, themes, layout modes, and progress tracking.
   - The `readerSettings` components and constants like `viewMode`, `themeList`, `ttsList`, and `popupList` show that reading behavior is highly configurable and centrally modeled.

12. **Internationalization and content localization**
   - `src/i18n.tsx` and `src/assets/locales/*.json` drive the app’s multilingual UI.
   - The `scripts/` directory contains translation extraction/merge tooling, which indicates i18n is part of the repository’s build/content workflow rather than an afterthought.

13. **Packaging and deployment**
   - `webpack.config.js`, `electron-builder.env`, `Dockerfile`, and the GitHub Actions workflows cover desktop packaging, release artifacts, appx publishing, and Docker publishing.
   - `docker-compose.yml` and `docker-compose-secret.yml` indicate a containerized deployment path, likely for the web build.
   - The repo therefore spans both a packaged desktop application and a deployable web application from the same source tree.

14. **How to think about the architecture diagram**
   - Draw the center as a React/TypeScript client with Redux state.
   - Surround it with three major boundaries: desktop/web shell, local persistence/storage, and external sync/import services.
   - Add the embedded client-side libraries as a separate processing layer for file parsing, rendering, OCR, archive handling, and local database access.

Main entry points: [`src/router/index.tsx`](https://github.com/koodo-reader/koodo-reader/blob/dev/src/router/index.tsx) (router), [`src/components/dialogs/importDialog/index.tsx`](https://github.com/koodo-reader/koodo-reader/blob/dev/src/components/dialogs/importDialog/index.tsx) (components), [`src/pages/manager/index.tsx`](https://github.com/koodo-reader/koodo-reader/blob/dev/src/pages/manager/index.tsx) (manager), [`src/pages/reader/index.tsx`](https://github.com/koodo-reader/koodo-reader/blob/dev/src/pages/reader/index.tsx) (reader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime shells"]
  node_mainjs["main.js<br/>electron main<br/>[main.js]"]
  node_httpserver["httpServer.js<br/>web server<br/>[httpServer.js]"]
end

subgraph group_app["React app"]
  node_indextsx["src/index.tsx<br/>app bootstrap<br/>[index.tsx]"]
  node_router["router<br/>navigation<br/>[index.tsx]"]
end

subgraph group_features["User features"]
  node_loginpage["login<br/>auth page<br/>[index.tsx]"]
  node_managerpage["manager<br/>library page<br/>[index.tsx]"]
  node_readerpage["reader<br/>reading page<br/>[index.tsx]"]
  node_redirectpage["redirect<br/>handoff page<br/>[index.tsx]"]
  node_containers["containers<br/>page shells<br/>[index.tsx]"]
  node_components["components<br/>widgets/dialogs<br/>[index.tsx]"]
end

subgraph group_data["Data & services"]
  node_store[("store<br/>redux state<br/>[index.tsx]")]
  node_models["models<br/>[Book.ts]"]
  node_storage[("storage<br/>persistence<br/>[databaseService.ts]")]
  node_fileutils["file utils<br/>import/export pipeline<br/>[bookUtil.ts]"]
  node_readerutils["reader utils<br/>reading logic<br/>[docUtil.ts]"]
  node_request["request<br/>api clients<br/>[common.ts]"]
  node_database[("databaseService<br/>local db<br/>[databaseService.ts]")]
  node_syncservice[("syncService<br/>cloud sync<br/>[syncService.ts]")]
end

subgraph group_platform["Platform assets"]
  node_i18n["i18n<br/>localization<br/>[i18n.tsx]"]
  node_libs["public/lib<br/>embedded engines"]
  node_deploy["build & deploy<br/>packaging<br/>[webpack.config.js]"]
end

node_mainjs -->|"launches"| node_indextsx
node_httpserver -->|"serves"| node_indextsx
node_indextsx -->|"boots"| node_router
node_router -->|"routes"| node_loginpage
node_router -->|"routes"| node_managerpage
node_router -->|"routes"| node_readerpage
node_router -->|"routes"| node_redirectpage
node_managerpage -->|"assembles"| node_containers
node_readerpage -->|"assembles"| node_containers
node_loginpage -->|"uses"| node_components
node_managerpage -->|"uses"| node_components
node_readerpage -->|"uses"| node_components
node_containers -->|"binds"| node_store
node_components -->|"dispatches"| node_store
node_store -->|"tracks"| node_models
node_store -->|"persists"| node_storage
node_fileutils -->|"loads/saves"| node_storage
node_readerutils -->|"reads"| node_storage
node_readerutils -->|"runs on"| node_libs
node_fileutils -->|"uses"| node_libs
node_request -->|"supports"| node_syncservice
node_syncservice -->|"syncs"| node_storage
node_i18n -->|"localizes"| node_components
node_i18n -->|"localizes"| node_managerpage
node_i18n -->|"localizes"| node_readerpage
node_deploy -->|"packages"| node_mainjs
node_deploy -->|"packages"| node_httpserver

click node_mainjs "https://github.com/koodo-reader/koodo-reader/blob/dev/main.js"
click node_httpserver "https://github.com/koodo-reader/koodo-reader/blob/dev/httpServer.js"
click node_indextsx "https://github.com/koodo-reader/koodo-reader/blob/dev/src/index.tsx"
click node_router "https://github.com/koodo-reader/koodo-reader/blob/dev/src/router/index.tsx"
click node_loginpage "https://github.com/koodo-reader/koodo-reader/blob/dev/src/pages/login/index.tsx"
click node_managerpage "https://github.com/koodo-reader/koodo-reader/blob/dev/src/pages/manager/index.tsx"
click node_readerpage "https://github.com/koodo-reader/koodo-reader/blob/dev/src/pages/reader/index.tsx"
click node_redirectpage "https://github.com/koodo-reader/koodo-reader/blob/dev/src/pages/redirect/index.tsx"
click node_containers "https://github.com/koodo-reader/koodo-reader/blob/dev/src/containers/pageWidget/index.tsx"
click node_components "https://github.com/koodo-reader/koodo-reader/blob/dev/src/components/dialogs/importDialog/index.tsx"
click node_store "https://github.com/koodo-reader/koodo-reader/blob/dev/src/store/index.tsx"
click node_models "https://github.com/koodo-reader/koodo-reader/blob/dev/src/models/Book.ts"
click node_storage "https://github.com/koodo-reader/koodo-reader/blob/dev/src/utils/storage/databaseService.ts"
click node_fileutils "https://github.com/koodo-reader/koodo-reader/blob/dev/src/utils/file/bookUtil.ts"
click node_readerutils "https://github.com/koodo-reader/koodo-reader/blob/dev/src/utils/reader/docUtil.ts"
click node_request "https://github.com/koodo-reader/koodo-reader/blob/dev/src/utils/request/common.ts"
click node_database "https://github.com/koodo-reader/koodo-reader/blob/dev/src/utils/storage/databaseService.ts"
click node_syncservice "https://github.com/koodo-reader/koodo-reader/blob/dev/src/utils/storage/syncService.ts"
click node_i18n "https://github.com/koodo-reader/koodo-reader/blob/dev/src/i18n.tsx"
click node_libs "https://github.com/koodo-reader/koodo-reader/tree/dev/public/lib"
click node_deploy "https://github.com/koodo-reader/koodo-reader/blob/dev/webpack.config.js"

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_mainjs,node_httpserver toneBlue
class node_indextsx,node_router toneAmber
class node_loginpage,node_managerpage,node_readerpage,node_redirectpage,node_containers,node_components toneMint
class node_store,node_models,node_storage,node_fileutils,node_readerutils,node_request,node_database,node_syncservice toneRose
class node_i18n,node_libs,node_deploy toneIndigo
```

## Components

### Runtime shells

Desktop and web/bootstrap entrypoints.

- [main.js](https://github.com/koodo-reader/koodo-reader/blob/dev/main.js): electron main · Desktop bootstrap and Electron main-process entrypoint. · `main.js`
- [httpServer.js](https://github.com/koodo-reader/koodo-reader/blob/dev/httpServer.js): web server · Serves the app in web/container mode. · `httpServer.js`

### React app

Shared client application shell and routes.

- [src/index.tsx](https://github.com/koodo-reader/koodo-reader/blob/dev/src/index.tsx): app bootstrap · React application bootstrap. · `src/index.tsx`
- [router](https://github.com/koodo-reader/koodo-reader/blob/dev/src/router/index.tsx): navigation · Top-level routing and route wiring. · `src/router/index.tsx`

### User features

Primary manager, reader, and login surfaces.

- [login](https://github.com/koodo-reader/koodo-reader/blob/dev/src/pages/login/index.tsx): auth page · Cloud/service sign-in surface. · `src/pages/login/index.tsx`
- [manager](https://github.com/koodo-reader/koodo-reader/blob/dev/src/pages/manager/index.tsx): library page · Library management, shelves, notes, settings, backup, and import/export. · `src/pages/manager/index.tsx`
- [reader](https://github.com/koodo-reader/koodo-reader/blob/dev/src/pages/reader/index.tsx): reading page · Primary reading surface and controls. · `src/pages/reader/index.tsx`
- [redirect](https://github.com/koodo-reader/koodo-reader/blob/dev/src/pages/redirect/index.tsx): handoff page · Route handoff and navigation redirection. · `src/pages/redirect/index.tsx`
- [containers](https://github.com/koodo-reader/koodo-reader/blob/dev/src/containers/pageWidget/index.tsx): page shells · Layout wrappers for header, sidebar, panels, lists, and viewer. · `src/containers/pageWidget/index.tsx`
- [components](https://github.com/koodo-reader/koodo-reader/blob/dev/src/components/dialogs/importDialog/index.tsx): widgets/dialogs · Reusable UI widgets and feature dialogs. · `src/components/dialogs/importDialog/index.tsx`

### Data & services

State, domain, persistence, and service layers.

- [store](https://github.com/koodo-reader/koodo-reader/blob/dev/src/store/index.tsx): redux state · Central UI and workflow state coordination. · `src/store/index.tsx`
- [models](https://github.com/koodo-reader/koodo-reader/blob/dev/src/models/Book.ts): domain models · Core ebook, note, bookmark, plugin, and history entities. · `src/models/Book.ts`
- [storage](https://github.com/koodo-reader/koodo-reader/blob/dev/src/utils/storage/databaseService.ts): persistence · Local database and sync persistence services. · `src/utils/storage/databaseService.ts`
- [file utils](https://github.com/koodo-reader/koodo-reader/blob/dev/src/utils/file/bookUtil.ts): import/export pipeline · Book intake, backup/restore, export, cover, config, and local file handling. · `src/utils/file/bookUtil.ts`
- [reader utils](https://github.com/koodo-reader/koodo-reader/blob/dev/src/utils/reader/docUtil.ts): reading logic · Document handling, theme/style control, notes, TTS, and input interactions. · `src/utils/reader/docUtil.ts`
- [request](https://github.com/koodo-reader/koodo-reader/blob/dev/src/utils/request/common.ts): api clients · App, reader, user, and third-party service requests. · `src/utils/request/common.ts`
- [databaseService](https://github.com/koodo-reader/koodo-reader/blob/dev/src/utils/storage/databaseService.ts): local db · Local-first structured storage for books and reading data. · `src/utils/storage/databaseService.ts`
- [syncService](https://github.com/koodo-reader/koodo-reader/blob/dev/src/utils/storage/syncService.ts): cloud sync · Synchronization layer for external storage providers. · `src/utils/storage/syncService.ts`

### Platform assets

Bundled engines, i18n, and deployment assets.

- [i18n](https://github.com/koodo-reader/koodo-reader/blob/dev/src/i18n.tsx): localization · Multilingual UI loading and translation wiring. · `src/i18n.tsx`
- [public/lib](https://github.com/koodo-reader/koodo-reader/tree/dev/public/lib): embedded engines · Bundled runtime engines for PDF, archive extraction, OCR, SQL, and ML. · `public/lib`
- [build & deploy](https://github.com/koodo-reader/koodo-reader/blob/dev/webpack.config.js): packaging · Webpack, Docker, and release workflows. · `webpack.config.js`

## Connections

- main.js → src/index.tsx: launches · Desktop shell starts the shared client app.
- httpServer.js → src/index.tsx: serves · Web/container runtime serves the same app bundle.
- src/index.tsx → router: boots · App bootstrap initializes routing.
- router → login: routes · Routes to authentication.
- router → manager: routes · Routes to library management.
- router → reader: routes · Routes to reading view.
- router → redirect: routes · Routes through handoff/redirect flows.
- manager → containers: assembles · Manager page composes shared layout and panels.
- reader → containers: assembles · Reader page composes viewer and controls.
- login → components: uses · Login surface uses shared dialogs/widgets.
- manager → components: uses · Manager surface uses import, backup, sort, and settings dialogs.
- reader → components: uses · Reader surface uses popups, settings, TTS, and view controls.
- containers → store: binds · Page shells are driven by shared state.
- components → store: dispatches · Dialogs and widgets coordinate through global state.
- store → models: tracks · Redux state centers on domain entities.
- store → storage: persists · State changes flow into local persistence.
- file utils → storage: loads/saves · Import, backup, and export update local storage.
- reader utils → storage: reads · Reader behavior consumes persisted book and progress data.
- reader utils → public/lib: runs on · Reader processing relies on embedded client engines.
- file utils → public/lib: uses · File intake and extraction use bundled runtime libraries.
- request → syncService: supports · API clients back cloud sync and service access.
- syncService → storage: syncs · Sync layer reconciles local data with external providers.
- i18n → components: localizes · UI components render translated text.
- i18n → manager: localizes · Manager surface uses shared translations.
- i18n → reader: localizes · Reader surface uses shared translations.
- build & deploy → main.js: packages · Build and release tooling package the desktop runtime.
- build & deploy → httpServer.js: packages · Container and web deployment package the server entrypoint.