danvics/openreader
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
openreader/docs-site/docs/reference/stack.md
Richard R f1aa1c3e3b feat(compute): add external compute worker backend and integration 
Introduce support for external compute worker mode (`COMPUTE_MODE=worker`) using a new `WorkerComputeBackend`. This enables offloading heavy ONNX Whisper alignment and PDF layout parsing to a standalone worker service (Redis + BullMQ), improving scalability and compatibility with serverless/limited environments.

- Add `@openreader/compute-core` as a shared package for ONNX inference and PDF parsing logic.
- Implement `WorkerComputeBackend` and worker contract/types for remote job execution.
- Update compute backend selection logic and remove previous worker mode guards.
- Extend `WhisperAlignInput` and `PdfLayoutInput` types to support object keys for remote data access.
- Refactor local compute backend to use `@openreader/compute-core` and support both buffer and object key inputs.
- Update job runner, TTS segment alignment, and PDF layout parsing flows to use new compute backend APIs.
- Add scripts, Docker workflow, and documentation for deploying and running the compute worker.
- Update environment variable docs and examples for worker mode, including storage requirements and configuration.
- Document published images and stack changes to reflect the new compute worker architecture.

BREAKING CHANGE: `COMPUTE_MODE=worker` now requires an external compute worker service and S3-compatible object storage. Embedded SeaweedFS (`weed mini`) is not supported in worker mode. See the new documentation for deployment and configuration details.
2026-05-19 15:21:25 -06:00

4.1 KiB
Raw Blame History

title
Stack

Framework

Containerization and runtime

  • Docker (linux/amd64 and linux/arm64)
  • Shared entrypoint that runs DB migrations by default and can bootstrap embedded SeaweedFS before app startup

Next.js client

Next.js server

  • APIs: Route Handlers for sync, blob/content access, migrations, audiobook export, TTS/Whisper proxying
  • State sync: request-based today (not realtime push updates)
  • Authentication: Better Auth server handlers/adapters with anonymous session support
  • Metadata DB: Drizzle ORM with SQLite (better-sqlite3) by default and optional Postgres (pg)
    • App tables are manually maintained in Drizzle schema files
    • Auth tables are auto-generated by the Better Auth CLI and migrated alongside app tables via Drizzle
  • Blob storage: embedded SeaweedFS (weed mini) by default, or external S3-compatible storage via AWS SDK v3
  • TTS providers: OpenAI-compatible API (openai SDK), Replicate (replicate client), DeepInfra, and custom OpenAI-compatible endpoints — credentials are encrypted at rest
  • Audio pipeline: ffmpeg (ffmpeg-static) for audiobook assembly, archiver for export packaging
  • Utilities: lru-cache for in-process caching, fast-xml-parser for EPUB/XML parsing, uuid for identifier generation, zod for schema validation

External compute worker (optional)

Monorepo packages under compute/:

  • @openreader/compute-core — ONNX runtime lifecycle, model management, and inference logic shared between local and worker modes
    • ONNX runtime: onnxruntime-node with @huggingface/tokenizers
    • Whisper alignment: onnx-community/whisper-base_timestamped (int8) for word-level timestamps
    • PDF layout: Bei0001/PP-DocLayoutV3-ONNX for document block detection and layout parsing
    • PDF rendering: pdfjs-dist, @napi-rs/canvas for server-side page rasterization
    • Utilities: jszip, ffmpeg-static
  • @openreader/compute-worker — standalone Node.js worker service
    • HTTP server: Fastify v5
    • Job queue: BullMQ + ioredis (queues: whisper-align, pdf-layout)
    • Storage: AWS SDK v3 S3 client for reading/writing blobs
    • Logging: Pino
    • Validation: Zod
  • Compute mode is controlled by COMPUTE_MODE env var: local (in-process), worker (remote queue via HTTP + Redis), or disabled

Tooling and testing

  • ESLint
  • TypeScript
  • Playwright end-to-end tests
  • Drizzle migration/generation scripts
  • Docusaurus documentation site (docs-site/)