How richardr1126/openreader works
OpenReader is a self-hostable document reader that turns EPUB, PDF, TXT, MD, and DOCX files into synchronized speech. The main user journey is to add or import a document, open it in a format-specific reader, create a playback plan, and listen as audio is generated progressively; the compute worker also supports exports and document processing. The graph preserves the documented provider, storage, and database options. Some subsystem links are based on README descriptions because their implementation files were not sampled.
Main entry points: route.ts Document API · routes.ts Worker API · page.tsx Web UI · handlers.ts Worker jobs
Components 34
Web application
- Web UI
src/app/(app)/app/page.tsx - Session client
src/hooks/useAuthSession.ts
Documents and readers
- Document library
src/components/doclist/useDocumentListController.ts - Document API
src/app/api/documents/route.ts - Document types
src/types/documents.ts - Format readers
src/components/views/EPUBViewer.tsx - Reader bootstrap
src/lib/server/reader/bootstrap.ts
Playback and TTS
- Plan controller
src/hooks/audio/useTtsPlanController.ts - Playback API
src/lib/client/api/tts.ts - Playback sessions
src/lib/server/tts/playback-sessions.ts - Audio player
src/components/player/TTSPlayer.tsx - TTS engine
packages/tts/src/generate.ts
Compute worker
- Worker API
packages/compute-worker/src/api/routes.ts - Operation contracts
packages/compute-worker/src/operations/contracts.ts - Worker jobs
packages/compute-worker/src/jobs/handlers.ts - Document inference
packages/compute-worker/src/inference/runtime.ts - Session controller
packages/compute-worker/src/api/playback/session-controller.ts - Session read model
packages/compute-worker/src/api/playback/session-read-model.ts - Playback storage
packages/compute-worker/src/playback/storage.ts - Artifact addressing
packages/compute-worker/src/storage/artifact-addressing.ts - Worker object storage
packages/compute-worker/src/infrastructure/storage.ts - NATS adapters
packages/compute-worker/src/infrastructure/nats-adapters.ts
Platform services
- Authentication
src/lib/server/auth/auth.ts - Blob storage
src/lib/server/storage/s3.ts - Compute client
src/lib/server/compute-worker/client.ts - Worker protocol
src/lib/server/compute-worker/protocol.ts - Compute admission
src/lib/server/compute-limits/admission.ts - SQL database
packages/database/src/schema.ts - Error responses
src/lib/server/errors/next-response.ts - Server logging
src/lib/server/logger.ts
Other components
- Reader user
- TTS providers
- S3-compatible storage
- NATS JetStream
Connections 37
- Reader user → Web UI: uses
- Web UI → Session client: checks session
- Session client → Authentication: authenticates
- Web UI → Document library: manages documents
- Document library → Document API: loads documents
- Document API → Authentication: requires auth
src/app/api/documents/route.ts - Document API → SQL database: queries metadata
src/app/api/documents/route.ts - Document API → Blob storage: deletes blobs
src/app/api/documents/route.ts - Document library → Document types: uses types
src/components/doclist/useDocumentListController.ts - Document API → Document types: uses types
src/app/api/documents/route.ts - Web UI → Format readers: opens document
- Format readers → Reader bootstrap: loads reader state
- Reader user → Plan controller: starts playback
- Plan controller → Playback API: requests seek layout
src/hooks/audio/useTtsPlanController.ts - Playback API → Playback sessions: requests playback
- Playback sessions → Compute client: dispatches work
- Compute client → Worker protocol: uses protocol
src/lib/server/compute-worker/client.ts - Compute client → Worker API: calls worker
- Worker API → Session controller: routes sessions
packages/compute-worker/src/api/routes.ts - Worker API → Worker jobs: routes jobs
- Session controller → Session read model: reads session
packages/compute-worker/src/api/playback/session-controller.ts - Session controller → Playback storage: updates session
packages/compute-worker/src/api/playback/session-controller.ts - Session controller → NATS adapters: hashes operation key
packages/compute-worker/src/api/playback/session-controller.ts - Worker jobs → Operation contracts: uses contracts
packages/compute-worker/src/operations/contracts.ts - Worker jobs → Document inference: processes documents
- Worker jobs → TTS engine: generates speech
- Audio player → Playback API: controls playback
- Playback storage → Worker object storage: stores artifacts
packages/compute-worker/src/playback/storage.ts - Playback storage → Artifact addressing: builds artifact keys
packages/compute-worker/src/playback/storage.ts - Worker object storage → Artifact addressing: uses artifact keys
packages/compute-worker/src/infrastructure/storage.ts - Worker API → Compute admission: admission policy
- Blob storage → S3-compatible storage: stores blobs
- Worker object storage → S3-compatible storage: stores artifacts
packages/compute-worker/src/infrastructure/storage.ts - NATS adapters → NATS JetStream: uses JetStream
- TTS engine → TTS providers: calls provider
- Worker API → Error responses: formats errors
- Error responses → Server logging: logs failures
src/lib/server/errors/next-response.ts