# richardr1126/openreader architecture

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

- Interactive diagram: https://gitdiagram.com/richardr1126/openreader
- Repository: https://github.com/richardr1126/openreader

## Overview

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: [`src/app/api/documents/route.ts`](https://github.com/richardr1126/openreader/blob/main/src/app/api/documents/route.ts) (Document API), [`packages/compute-worker/src/api/routes.ts`](https://github.com/richardr1126/openreader/blob/main/packages/compute-worker/src/api/routes.ts) (Worker API), [`src/app/(app)/app/page.tsx`](https://github.com/richardr1126/openreader/blob/main/src/app/(app)/app/page.tsx) (Web UI), [`packages/compute-worker/src/jobs/handlers.ts`](https://github.com/richardr1126/openreader/blob/main/packages/compute-worker/src/jobs/handlers.ts) (Worker jobs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webui["Web UI<br/>[page.tsx]"]
  node_authui["Session client<br/>[useAuthSession.ts]"]
end

subgraph group_documents["Documents and readers"]
  node_library["Document library"]
  node_documentapi["Document API<br/>[route.ts]"]
  node_documenttypes["Document types<br/>[documents.ts]"]
  node_formats["Format readers<br/>[EPUBViewer.tsx]"]
  node_bootstrap["Reader bootstrap<br/>[bootstrap.ts]"]
end

subgraph group_playback["Playback and TTS"]
  node_plancontroller["Plan controller"]
  node_playbackapi["Playback API<br/>[tts.ts]"]
  node_playbackserver["Playback sessions"]
  node_player["Audio player<br/>[TTSPlayer.tsx]"]
  node_tts["TTS engine<br/>[generate.ts]"]
end

subgraph group_compute["Compute worker"]
  node_workerapi["Worker API<br/>[routes.ts]"]
  node_operations["Operation contracts<br/>[contracts.ts]"]
  node_workerjobs["Worker jobs<br/>[handlers.ts]"]
  node_inference["Document inference<br/>[runtime.ts]"]
  node_sessioncontroller["Session controller"]
  node_sessionread["Session read model"]
  node_playbackstorage[("Playback storage<br/>[storage.ts]")]
  node_artifactaddress["Artifact addressing"]
  node_workerstorage[("Worker object storage<br/>[storage.ts]")]
  node_nats["NATS adapters<br/>[nats-adapters.ts]"]
end

subgraph group_platform["Platform services"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_webstorage[("Blob storage<br/>[s3.ts]")]
  node_workerclient["Compute client<br/>[client.ts]"]
  node_protocol["Worker protocol<br/>[protocol.ts]"]
  node_admission["Compute admission<br/>[admission.ts]"]
  node_database[("SQL database<br/>[schema.ts]")]
  node_errors["Error responses<br/>[next-response.ts]"]
  node_logging["Server logging<br/>[logger.ts]"]
end

node_reader(("Reader user"))
node_externaltts{{"TTS providers"}}
node_objectservice[("S3-compatible storage")]
node_natsservice["NATS JetStream"]

node_reader -->|"uses"| node_webui
node_webui -.->|"checks session"| node_authui
node_authui -.->|"authenticates"| node_auth
node_webui -.->|"manages documents"| node_library
node_library -.->|"loads documents"| node_documentapi
node_documentapi -->|"requires auth"| node_auth
node_documentapi -->|"queries metadata"| node_database
node_documentapi -->|"deletes blobs"| node_webstorage
node_library -->|"uses types"| node_documenttypes
node_documentapi -->|"uses types"| node_documenttypes
node_webui -.->|"opens document"| node_formats
node_formats -.->|"loads reader state"| node_bootstrap
node_reader -->|"starts playback"| node_plancontroller
node_plancontroller -->|"requests seek layout"| node_playbackapi
node_playbackapi -.->|"requests playback"| node_playbackserver
node_playbackserver -.->|"dispatches work"| node_workerclient
node_workerclient -->|"uses protocol"| node_protocol
node_workerclient -.->|"calls worker"| node_workerapi
node_workerapi -->|"routes sessions"| node_sessioncontroller
node_workerapi -.->|"routes jobs"| node_workerjobs
node_sessioncontroller -->|"reads session"| node_sessionread
node_sessioncontroller -->|"updates session"| node_playbackstorage
node_sessioncontroller -->|"hashes operation key"| node_nats
node_workerjobs -->|"uses contracts"| node_operations
node_workerjobs -.->|"processes documents"| node_inference
node_workerjobs -->|"generates speech"| node_tts
node_player -.->|"controls playback"| node_playbackapi
node_playbackstorage -->|"stores artifacts"| node_workerstorage
node_playbackstorage -->|"builds artifact keys"| node_artifactaddress
node_workerstorage -->|"uses artifact keys"| node_artifactaddress
node_workerapi -.->|"admission policy"| node_admission
node_webstorage -->|"stores blobs"| node_objectservice
node_workerstorage -->|"stores artifacts"| node_objectservice
node_nats -->|"uses JetStream"| node_natsservice
node_tts -->|"calls provider"| node_externaltts
node_workerapi -.->|"formats errors"| node_errors
node_errors -->|"logs failures"| node_logging

click node_webui "https://github.com/richardr1126/openreader/blob/main/src/app/(app)/app/page.tsx"
click node_authui "https://github.com/richardr1126/openreader/blob/main/src/hooks/useAuthSession.ts"
click node_auth "https://github.com/richardr1126/openreader/blob/main/src/lib/server/auth/auth.ts"
click node_library "https://github.com/richardr1126/openreader/blob/main/src/components/doclist/useDocumentListController.ts"
click node_documentapi "https://github.com/richardr1126/openreader/blob/main/src/app/api/documents/route.ts"
click node_documenttypes "https://github.com/richardr1126/openreader/blob/main/src/types/documents.ts"
click node_formats "https://github.com/richardr1126/openreader/blob/main/src/components/views/EPUBViewer.tsx"
click node_bootstrap "https://github.com/richardr1126/openreader/blob/main/src/lib/server/reader/bootstrap.ts"
click node_webstorage "https://github.com/richardr1126/openreader/blob/main/src/lib/server/storage/s3.ts"
click node_plancontroller "https://github.com/richardr1126/openreader/blob/main/src/hooks/audio/useTtsPlanController.ts"
click node_playbackapi "https://github.com/richardr1126/openreader/blob/main/src/lib/client/api/tts.ts"
click node_playbackserver "https://github.com/richardr1126/openreader/blob/main/src/lib/server/tts/playback-sessions.ts"
click node_player "https://github.com/richardr1126/openreader/blob/main/src/components/player/TTSPlayer.tsx"
click node_tts "https://github.com/richardr1126/openreader/blob/main/packages/tts/src/generate.ts"
click node_workerapi "https://github.com/richardr1126/openreader/blob/main/packages/compute-worker/src/api/routes.ts"
click node_operations "https://github.com/richardr1126/openreader/blob/main/packages/compute-worker/src/operations/contracts.ts"
click node_workerjobs "https://github.com/richardr1126/openreader/blob/main/packages/compute-worker/src/jobs/handlers.ts"
click node_inference "https://github.com/richardr1126/openreader/blob/main/packages/compute-worker/src/inference/runtime.ts"
click node_sessioncontroller "https://github.com/richardr1126/openreader/blob/main/packages/compute-worker/src/api/playback/session-controller.ts"
click node_sessionread "https://github.com/richardr1126/openreader/blob/main/packages/compute-worker/src/api/playback/session-read-model.ts"
click node_playbackstorage "https://github.com/richardr1126/openreader/blob/main/packages/compute-worker/src/playback/storage.ts"
click node_artifactaddress "https://github.com/richardr1126/openreader/blob/main/packages/compute-worker/src/storage/artifact-addressing.ts"
click node_workerstorage "https://github.com/richardr1126/openreader/blob/main/packages/compute-worker/src/infrastructure/storage.ts"
click node_nats "https://github.com/richardr1126/openreader/blob/main/packages/compute-worker/src/infrastructure/nats-adapters.ts"
click node_workerclient "https://github.com/richardr1126/openreader/blob/main/src/lib/server/compute-worker/client.ts"
click node_protocol "https://github.com/richardr1126/openreader/blob/main/src/lib/server/compute-worker/protocol.ts"
click node_admission "https://github.com/richardr1126/openreader/blob/main/src/lib/server/compute-limits/admission.ts"
click node_database "https://github.com/richardr1126/openreader/blob/main/packages/database/src/schema.ts"
click node_errors "https://github.com/richardr1126/openreader/blob/main/src/lib/server/errors/next-response.ts"
click node_logging "https://github.com/richardr1126/openreader/blob/main/src/lib/server/logger.ts"

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_webui,node_authui,node_reader toneBlue
class node_library,node_documentapi,node_documenttypes,node_formats,node_bootstrap,node_objectservice toneAmber
class node_plancontroller,node_playbackapi,node_playbackserver,node_player,node_tts toneMint
class node_workerapi,node_operations,node_workerjobs,node_inference,node_sessioncontroller,node_sessionread,node_playbackstorage,node_artifactaddress,node_workerstorage,node_nats toneRose
class node_auth,node_webstorage,node_workerclient,node_protocol,node_admission,node_database,node_errors,node_logging,node_externaltts,node_natsservice toneIndigo
```

## Components

### Web application

- [Web UI](https://github.com/richardr1126/openreader/blob/main/src/app/(app)/app/page.tsx): `src/app/(app)/app/page.tsx`
- [Session client](https://github.com/richardr1126/openreader/blob/main/src/hooks/useAuthSession.ts): `src/hooks/useAuthSession.ts`

### Documents and readers

- [Document library](https://github.com/richardr1126/openreader/blob/main/src/components/doclist/useDocumentListController.ts): `src/components/doclist/useDocumentListController.ts`
- [Document API](https://github.com/richardr1126/openreader/blob/main/src/app/api/documents/route.ts): `src/app/api/documents/route.ts`
- [Document types](https://github.com/richardr1126/openreader/blob/main/src/types/documents.ts): `src/types/documents.ts`
- [Format readers](https://github.com/richardr1126/openreader/blob/main/src/components/views/EPUBViewer.tsx): `src/components/views/EPUBViewer.tsx`
- [Reader bootstrap](https://github.com/richardr1126/openreader/blob/main/src/lib/server/reader/bootstrap.ts): `src/lib/server/reader/bootstrap.ts`

### Playback and TTS

- [Plan controller](https://github.com/richardr1126/openreader/blob/main/src/hooks/audio/useTtsPlanController.ts): `src/hooks/audio/useTtsPlanController.ts`
- [Playback API](https://github.com/richardr1126/openreader/blob/main/src/lib/client/api/tts.ts): `src/lib/client/api/tts.ts`
- [Playback sessions](https://github.com/richardr1126/openreader/blob/main/src/lib/server/tts/playback-sessions.ts): `src/lib/server/tts/playback-sessions.ts`
- [Audio player](https://github.com/richardr1126/openreader/blob/main/src/components/player/TTSPlayer.tsx): `src/components/player/TTSPlayer.tsx`
- [TTS engine](https://github.com/richardr1126/openreader/blob/main/packages/tts/src/generate.ts): `packages/tts/src/generate.ts`

### Compute worker

- [Worker API](https://github.com/richardr1126/openreader/blob/main/packages/compute-worker/src/api/routes.ts): `packages/compute-worker/src/api/routes.ts`
- [Operation contracts](https://github.com/richardr1126/openreader/blob/main/packages/compute-worker/src/operations/contracts.ts): `packages/compute-worker/src/operations/contracts.ts`
- [Worker jobs](https://github.com/richardr1126/openreader/blob/main/packages/compute-worker/src/jobs/handlers.ts): `packages/compute-worker/src/jobs/handlers.ts`
- [Document inference](https://github.com/richardr1126/openreader/blob/main/packages/compute-worker/src/inference/runtime.ts): `packages/compute-worker/src/inference/runtime.ts`
- [Session controller](https://github.com/richardr1126/openreader/blob/main/packages/compute-worker/src/api/playback/session-controller.ts): `packages/compute-worker/src/api/playback/session-controller.ts`
- [Session read model](https://github.com/richardr1126/openreader/blob/main/packages/compute-worker/src/api/playback/session-read-model.ts): `packages/compute-worker/src/api/playback/session-read-model.ts`
- [Playback storage](https://github.com/richardr1126/openreader/blob/main/packages/compute-worker/src/playback/storage.ts): `packages/compute-worker/src/playback/storage.ts`
- [Artifact addressing](https://github.com/richardr1126/openreader/blob/main/packages/compute-worker/src/storage/artifact-addressing.ts): `packages/compute-worker/src/storage/artifact-addressing.ts`
- [Worker object storage](https://github.com/richardr1126/openreader/blob/main/packages/compute-worker/src/infrastructure/storage.ts): `packages/compute-worker/src/infrastructure/storage.ts`
- [NATS adapters](https://github.com/richardr1126/openreader/blob/main/packages/compute-worker/src/infrastructure/nats-adapters.ts): `packages/compute-worker/src/infrastructure/nats-adapters.ts`

### Platform services

- [Authentication](https://github.com/richardr1126/openreader/blob/main/src/lib/server/auth/auth.ts): `src/lib/server/auth/auth.ts`
- [Blob storage](https://github.com/richardr1126/openreader/blob/main/src/lib/server/storage/s3.ts): `src/lib/server/storage/s3.ts`
- [Compute client](https://github.com/richardr1126/openreader/blob/main/src/lib/server/compute-worker/client.ts): `src/lib/server/compute-worker/client.ts`
- [Worker protocol](https://github.com/richardr1126/openreader/blob/main/src/lib/server/compute-worker/protocol.ts): `src/lib/server/compute-worker/protocol.ts`
- [Compute admission](https://github.com/richardr1126/openreader/blob/main/src/lib/server/compute-limits/admission.ts): `src/lib/server/compute-limits/admission.ts`
- [SQL database](https://github.com/richardr1126/openreader/blob/main/packages/database/src/schema.ts): `packages/database/src/schema.ts`
- [Error responses](https://github.com/richardr1126/openreader/blob/main/src/lib/server/errors/next-response.ts): `src/lib/server/errors/next-response.ts`
- [Server logging](https://github.com/richardr1126/openreader/blob/main/src/lib/server/logger.ts): `src/lib/server/logger.ts`

### Other components

- **Reader user**
- **TTS providers**
- **S3-compatible storage**
- **NATS JetStream**

## Connections

- 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 (evidence: `src/app/api/documents/route.ts`)
- Document API → SQL database: queries metadata (evidence: `src/app/api/documents/route.ts`)
- Document API → Blob storage: deletes blobs (evidence: `src/app/api/documents/route.ts`)
- Document library → Document types: uses types (evidence: `src/components/doclist/useDocumentListController.ts`)
- Document API → Document types: uses types (evidence: `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 (evidence: `src/hooks/audio/useTtsPlanController.ts`)
- Playback API → Playback sessions: requests playback
- Playback sessions → Compute client: dispatches work
- Compute client → Worker protocol: uses protocol (evidence: `src/lib/server/compute-worker/client.ts`)
- Compute client → Worker API: calls worker
- Worker API → Session controller: routes sessions (evidence: `packages/compute-worker/src/api/routes.ts`)
- Worker API → Worker jobs: routes jobs
- Session controller → Session read model: reads session (evidence: `packages/compute-worker/src/api/playback/session-controller.ts`)
- Session controller → Playback storage: updates session (evidence: `packages/compute-worker/src/api/playback/session-controller.ts`)
- Session controller → NATS adapters: hashes operation key (evidence: `packages/compute-worker/src/api/playback/session-controller.ts`)
- Worker jobs → Operation contracts: uses contracts (evidence: `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 (evidence: `packages/compute-worker/src/playback/storage.ts`)
- Playback storage → Artifact addressing: builds artifact keys (evidence: `packages/compute-worker/src/playback/storage.ts`)
- Worker object storage → Artifact addressing: uses artifact keys (evidence: `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 (evidence: `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 (evidence: `src/lib/server/errors/next-response.ts`)
