forked from akai/readest
loveheaven
60203a8dc3
Add two complementary English documents under apps/readest-app/docs/ to help new contributors ramp up on the Readest codebase: - code-layout.md: directory-level inventory of the monorepo, covering apps/readest-app, packages/, the Tauri native shell, workers, and the conventions used for stores, services, and components. - architecture.md: high-level architecture with Mermaid diagrams. Maps the three runtimes (browser webview, Tauri Rust host, Next.js server), the dual API routers (pages/api legacy + app/api), Zustand stores, AppService / DatabaseService abstraction with its three backing implementations, foliate-js / pdfjs / simplecc / jieba integration, and cross-cutting subsystems (sync, cloud library, AI/RAG, translation, TTS, dictionaries, OPDS, Hardcover/Readwise, annotations, Send to Readest). Also documents the COOP/COEP middleware, allow_paths_in_scopes security gate, and the runtime re-config trick used for the single-image Docker deploy. No code changes; documentation only.
342 lines
10 KiB
Markdown
342 lines
10 KiB
Markdown
# Readest App Code Layout
|
|
|
|
This note summarizes the runtime boundaries inside `apps/readest-app`, with two goals:
|
|
|
|
- explain which directories are server-side, client-side, or mixed
|
|
- explain the directory-level role of `apps/readest-app/src/services`
|
|
|
|
## First: `src-tauri`
|
|
|
|
`apps/readest-app/src-tauri` is the Tauri native shell layer for all Tauri targets, not just desktop.
|
|
|
|
- Desktop: Windows, macOS, Linux
|
|
- Mobile: Android, iOS
|
|
|
|
That is visible in `apps/readest-app/src-tauri/tauri.conf.json`, which contains both `bundle.android` and `bundle.iOS` configuration, plus mobile deep-link settings.
|
|
|
|
So the rough split is:
|
|
|
|
- `apps/readest-app/src`: the Next.js/React app
|
|
- `apps/readest-app/src-tauri`: the native host layer for Tauri desktop and mobile builds
|
|
|
|
## Directory classification inside `apps/readest-app`
|
|
|
|
### Mostly server-side directories
|
|
|
|
- `apps/readest-app/src/app/api`
|
|
Next.js App Router server endpoints (`route.ts`). These run on the server / edge runtime, not in the browser.
|
|
|
|
- `apps/readest-app/src/pages/api`
|
|
Next.js Pages Router API endpoints. This is where the classic server handlers live, including sync, storage, send, DeepL, and user endpoints.
|
|
|
|
- `apps/readest-app/src/app/runtime-config.js`
|
|
A server route that emits runtime JavaScript config for the client.
|
|
|
|
- `apps/readest-app/workers`
|
|
Worker-side backend code outside the normal page UI tree. For example, `workers/send-email` is operational backend code.
|
|
|
|
### Mostly client-side directories
|
|
|
|
- `apps/readest-app/src/components`
|
|
Reusable React UI components.
|
|
|
|
- `apps/readest-app/src/context`
|
|
React context providers and app state wiring.
|
|
|
|
- `apps/readest-app/src/hooks`
|
|
Client-side React hooks.
|
|
|
|
- `apps/readest-app/src/store`
|
|
Frontend state stores.
|
|
|
|
- `apps/readest-app/src/styles`
|
|
Styling, theme assets, and UI presentation helpers.
|
|
|
|
- `apps/readest-app/src/data`
|
|
Static or bundled app data.
|
|
|
|
- `apps/readest-app/src/i18n`
|
|
Internationalization resources and setup.
|
|
|
|
- `apps/readest-app/src/workers`
|
|
Browser worker code used by the frontend.
|
|
|
|
- `apps/readest-app/public`
|
|
Static assets served to the frontend.
|
|
|
|
- `apps/readest-app/extension`
|
|
Browser-extension-specific client code.
|
|
|
|
- `apps/readest-app/extensions`
|
|
Platform integration extensions such as Windows thumbnail support.
|
|
|
|
### Mixed or shared directories
|
|
|
|
- `apps/readest-app/src/app`
|
|
Mostly frontend routes and UI, but not purely client-side. In Next App Router, `page.tsx`, `layout.tsx`, and related files can mix server rendering and client components. The exception is `src/app/api`, which is server-only.
|
|
|
|
- `apps/readest-app/src/pages`
|
|
Mixed. `src/pages/api` is server-only; `src/pages/reader/[ids].tsx` is frontend page code; `_document.tsx` is server-side document wiring.
|
|
|
|
- `apps/readest-app/src/services`
|
|
Shared domain/service layer. Most of this is not “backend-only”; it contains platform adapters, client logic, network clients, sync logic, and some code that is reused by server routes.
|
|
|
|
- `apps/readest-app/src/utils`
|
|
Shared helpers used by both frontend code and server handlers.
|
|
|
|
- `apps/readest-app/src/libs`
|
|
Shared library code. Some of it is server-oriented, some client-oriented, some neutral.
|
|
|
|
- `apps/readest-app/src/helpers`
|
|
General helper code, usually shared.
|
|
|
|
- `apps/readest-app/src/types`
|
|
Shared type definitions.
|
|
|
|
- `apps/readest-app/src/__tests__`
|
|
Test code covering both client and server behavior.
|
|
|
|
- `apps/readest-app/e2e`
|
|
End-to-end test suite.
|
|
|
|
- `apps/readest-app/scripts`
|
|
Build, release, and maintenance scripts.
|
|
|
|
- `apps/readest-app/docs`
|
|
App-specific documentation.
|
|
|
|
|
|
## `src/app` and `src/pages` at directory level
|
|
|
|
### `src/app`
|
|
|
|
- `src/app/api`: server-side HTTP endpoints
|
|
- `src/app/auth`: auth pages and auth-related UI/helpers
|
|
- `src/app/library`: library UI
|
|
- `src/app/o`: frontend route
|
|
- `src/app/offline`: frontend offline page
|
|
- `src/app/opds`: OPDS browsing UI
|
|
- `src/app/reader`: reader UI
|
|
- `src/app/runtime-config.js`: server-generated runtime config endpoint
|
|
- `src/app/s`: share landing UI
|
|
- `src/app/send`: send/import UI
|
|
- `src/app/updater`: updater UI
|
|
- `src/app/user`: account/subscription/settings UI
|
|
|
|
So `src/app` is mostly application UI, with one explicitly server-only subtree: `src/app/api`, plus the runtime-config route.
|
|
|
|
### `src/pages`
|
|
|
|
- `src/pages/api`: server-side API routes
|
|
- `src/pages/reader`: frontend page route(s)
|
|
- `src/pages/_app.tsx`: application wrapper for Pages Router
|
|
- `src/pages/_document.tsx`: server-side document shell
|
|
|
|
So `src/pages` is mixed, not purely client-side.
|
|
|
|
## `src/services` breakdown
|
|
|
|
The most important point is this:
|
|
|
|
- `src/services` is mostly a shared application/service layer
|
|
- it is not the same thing as “backend code”
|
|
- actual HTTP server entrypoints are mainly under `src/pages/api` and `src/app/api`
|
|
|
|
### Top-level files in `src/services`
|
|
|
|
- `appService.ts`
|
|
Base application service abstraction.
|
|
|
|
- `nativeAppService.ts`
|
|
Native/Tauri-facing app service implementation.
|
|
|
|
- `nodeAppService.ts`
|
|
Node-capable service implementation.
|
|
|
|
- `webAppService.ts`
|
|
Web/browser-oriented service implementation.
|
|
|
|
- `bookService.ts`
|
|
Book-level operations such as covers, metadata shaping, and book-related domain logic.
|
|
|
|
- `libraryService.ts`
|
|
Library management logic.
|
|
|
|
- `settingsService.ts`
|
|
Reading and persisting settings.
|
|
|
|
- `backupService.ts`
|
|
Backup/import-export related logic.
|
|
|
|
- `cloudService.ts`
|
|
Cloud-related app behavior.
|
|
|
|
- `fontService.ts`
|
|
Custom font handling.
|
|
|
|
- `imageService.ts`
|
|
Image-related helper logic.
|
|
|
|
- `ingestService.ts`
|
|
Import / ingest pipeline for incoming content.
|
|
|
|
- `persistence.ts`
|
|
Shared persistence utilities.
|
|
|
|
- `transformService.ts`
|
|
Content transformation entrypoints.
|
|
|
|
- `commandRegistry.ts`
|
|
Command registration / dispatch.
|
|
|
|
- `transferManager.ts` and `transferMessages.ts`
|
|
Transfer pipeline coordination.
|
|
|
|
- `environment.ts` and `runtimeConfig.ts`
|
|
Runtime environment detection and injected runtime configuration.
|
|
|
|
- `constants.ts` and `errors.ts`
|
|
Shared constants and error types.
|
|
|
|
These top-level files are mostly shared client/application-layer code, with some runtime branching for web, node, and Tauri.
|
|
|
|
### `src/services/database`
|
|
|
|
Platform-specific database access and migrations.
|
|
|
|
- `webDatabaseService.ts`: browser/web DB implementation
|
|
- `nodeDatabaseService.ts`: Node-side DB implementation
|
|
- `nativeDatabaseService.ts`: native/Tauri DB implementation
|
|
- `migrate.ts` and `migrations/`: schema and migration logic
|
|
|
|
This is shared infrastructure code, not an HTTP backend directory.
|
|
|
|
### `src/services/sync`
|
|
|
|
Sync clients and replica-sync orchestration.
|
|
|
|
- legacy/remote sync client code such as `KOSyncClient.ts`
|
|
- replica sync flow: bootstrap, publish, pull, apply, persistence, cursor storage, encryption, and passphrase handling
|
|
- adapter subdirectory for sync categories such as dictionary, font, texture, OPDS catalog, and settings
|
|
|
|
This is mostly client-side sync orchestration talking to backend endpoints like `src/pages/api/sync.ts` and `src/pages/api/sync/replicas.ts`.
|
|
|
|
### `src/services/send`
|
|
|
|
“Send to Readest” and content conversion logic.
|
|
|
|
- `sendAddress.ts`, `devicePrefs.ts`, `inboxDrainer.ts`
|
|
- `conversion/`: article/page-to-EPUB conversion pipeline, sanitization, TOC building, asset bundling, and worker protocol
|
|
|
|
This is mostly application logic used by frontend flows and server endpoints together.
|
|
|
|
### `src/services/metadata`
|
|
|
|
Book metadata lookup services.
|
|
|
|
- provider implementations like Google Books and Open Library
|
|
- shared metadata types and orchestration service
|
|
|
|
This is shared integration logic. Actual HTTP exposure happens via route handlers such as `src/app/api/metadata/search`.
|
|
|
|
### `src/services/dictionaries`
|
|
|
|
Dictionary import, parsing, lookup, and provider registry.
|
|
|
|
- readers/parsers for StarDict, SLOB, and related formats
|
|
- provider adapters for dictionary/web/wikipedia/wiktionary sources
|
|
- dictionary service, deduplication, content ID, and lookup candidate generation
|
|
|
|
This is primarily client/application functionality.
|
|
|
|
### `src/services/annotation`
|
|
|
|
Annotation models and provider adapters.
|
|
|
|
- annotation types and normalization
|
|
- provider adapters such as Foliate and MR export/import
|
|
|
|
Mostly shared reader-side logic.
|
|
|
|
### `src/services/nav`
|
|
|
|
Navigation, fragments, grouping, locations, and lookup utilities for books.
|
|
|
|
Mostly client-side reader logic.
|
|
|
|
### `src/services/opds`
|
|
|
|
OPDS feed handling and subscription state.
|
|
|
|
- feed parsing/checking
|
|
- auto-download support
|
|
- stream and subscription helpers
|
|
|
|
Mostly frontend/domain logic, sometimes paired with server proxy routes.
|
|
|
|
### `src/services/translators`
|
|
|
|
Translation provider integration.
|
|
|
|
- provider adapters for DeepL, Google, Azure, Yandex
|
|
- preprocessing, cache, polish, and translator utilities
|
|
|
|
Mixed integration code. Some providers are used via server APIs to avoid exposing secrets.
|
|
|
|
### `src/services/tts`
|
|
|
|
Text-to-speech abstraction and implementations.
|
|
|
|
- `WebSpeechClient.ts`: browser TTS
|
|
- `NativeTTSClient.ts`: native/Tauri TTS
|
|
- `EdgeTTSClient.ts`: remote/provider-backed TTS
|
|
- controller/data/types/utilities
|
|
|
|
Mixed runtime code, mostly used by the reader frontend.
|
|
|
|
### `src/services/ai`
|
|
|
|
AI chat/embedding/RAG related abstractions.
|
|
|
|
- adapters and providers
|
|
- prompts, chunking, retry logic, logging
|
|
- local AI store and RAG service
|
|
|
|
Mixed integration code. The services are shared, while actual HTTP endpoints live under `src/app/api/ai`.
|
|
|
|
### `src/services/hardcover` and `src/services/readwise`
|
|
|
|
Third-party reading service integrations.
|
|
|
|
- Hardcover sync client and mapping store
|
|
- Readwise client integration
|
|
|
|
Mostly client/application integration code.
|
|
|
|
### `src/services/rsvp`
|
|
|
|
RSVP reader mode logic.
|
|
|
|
- controller, persistence, utilities, and types
|
|
|
|
Client-side reading feature code.
|
|
|
|
### `src/services/transformers`
|
|
|
|
Text/content transformation modules.
|
|
|
|
- language, punctuation, whitespace, proofread, sanitization, footnote, style, simplecc, warichu
|
|
|
|
Shared pure logic, usually frontend-facing but not tied to a single runtime.
|
|
|
|
## Practical mental model
|
|
|
|
If you want a fast rule of thumb for this repo, use this:
|
|
|
|
- HTTP backend entrypoints: `src/pages/api`, `src/app/api`, `workers`
|
|
- frontend UI/routes: `src/app` except `api`, plus `src/components`, `src/hooks`, `src/store`
|
|
- shared app/domain logic: `src/services`, `src/utils`, `src/libs`, `src/types`
|
|
- native host layer for desktop + Android + iOS: `src-tauri`
|
|
|
|
That model matches the codebase much better than “everything under `src` is client code.”
|