koodo-reader/koodo-reader

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.