# jahnzh/sonder architecture

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

- Interactive diagram: https://gitdiagram.com/jahnzh/sonder
- Repository: https://github.com/jahnzh/sonder

## Overview

Sonder is a self-hosted audiobook and ebook library PWA. Users browse or discover works, acquire media, then listen or read; reader positions can be synchronized with audiobook narration through CTC alignment. The server also manages library metadata, Hardcover integration, background work, and backups. The graph preserves documented alignment and backup capabilities despite limited excerpts; those branches use supported directory paths where implementation details were not sampled. Edges are limited to explicit imports, calls, README statements, or directly shown frontend data access; unsampled subsystem wiring is omitted.

Main entry points: [`server/app.ts`](https://github.com/jahnzh/sonder/blob/main/server/app.ts) (HTTP application), [`src/App.tsx`](https://github.com/jahnzh/sonder/blob/main/src/App.tsx) (Application shell), [`server/acquisitions.ts`](https://github.com/jahnzh/sonder/blob/main/server/acquisitions.ts) (Media acquisition), [`src/lib.ts`](https://github.com/jahnzh/sonder/blob/main/src/lib.ts) (Client API and storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["PWA experience"]
  node_reader["Reader<br/>[Reader.tsx]"]
  node_player["Audiobook player<br/>[player.tsx]"]
  node_client_data[("Client API and storage<br/>[lib.ts]")]
  node_navigation["Navigation<br/>[navigation.ts]"]
  node_frontend["Application shell<br/>[App.tsx]"]
end

subgraph group_catalog["Library and acquisition"]
  node_acquisition["Media acquisition<br/>[acquisitions.ts]"]
  node_catalog_ui["Library and discovery"]
  node_hardcover["Hardcover sync<br/>[hardcover.ts]"]
  node_series_acq["Series acquisition"]
end

subgraph group_sync["Reading synchronization"]
  node_alignment["Alignment orchestration<br/>[alignment.ts]"]
  node_ctc["CTC alignment pipeline<br/>[ctc_pipeline.py]"]
  node_alignment_pool["Remote worker pool<br/>[alignment-pool.ts]"]
  node_reading_sync["Reading sync UI"]
end

subgraph group_server["Server platform"]
  node_api["HTTP application<br/>[app.ts]"]
  node_database[("SQLite database<br/>[db.ts]")]
  node_schema["Data schema<br/>[schema.ts]"]
  node_background["Background jobs"]
  node_backups["Database backups<br/>[backups.ts]"]
  node_media_storage[("Media storage<br/>[storage.ts]")]
  node_users["Accounts and access<br/>[users.ts]"]
end

subgraph group_external["External services"]
  node_hardcover_service{{"Hardcover API"}}
  node_torbox{{"TorBox"}}
  node_transmission{{"Transmission"}}
end

node_reader_user(("Reader"))

node_reader_user -->|"uses"| node_frontend
node_frontend -->|"routes through"| node_navigation
node_frontend -->|"calls API"| node_client_data
node_reader -->|"saves position"| node_client_data
node_player -->|"loads media"| node_client_data
node_frontend -->|"renders"| node_reader
node_frontend -->|"renders"| node_player
node_client_data -.->|"requests"| node_api
node_api -.->|"routes acquisition"| node_acquisition
node_api -->|"routes sync"| node_hardcover
node_hardcover -.->|"syncs metadata"| node_hardcover_service
node_api -.->|"routes series"| node_series_acq
node_api -.->|"routes alignment"| node_alignment
node_alignment -.->|"dispatches jobs"| node_alignment_pool
node_alignment_pool -.->|"runs alignment"| node_ctc
node_reading_sync -.->|"loads sync state"| node_client_data
node_acquisition -->|"checks cached media"| node_torbox
node_acquisition -->|"queues torrents"| node_transmission
node_acquisition -->|"resolves files"| node_media_storage
node_api -->|"authenticates"| node_users
node_api -->|"uses database"| node_database
node_api -->|"uses schema"| node_schema
node_hardcover -->|"reads and writes"| node_database
node_acquisition -.->|"updates status"| node_database
node_backups -.->|"backs up"| node_database
node_background -.->|"schedules"| node_backups

click node_reader "https://github.com/jahnzh/sonder/blob/main/src/components/Reader.tsx"
click node_player "https://github.com/jahnzh/sonder/blob/main/src/player.tsx"
click node_client_data "https://github.com/jahnzh/sonder/blob/main/src/lib.ts"
click node_navigation "https://github.com/jahnzh/sonder/blob/main/src/navigation.ts"
click node_frontend "https://github.com/jahnzh/sonder/blob/main/src/App.tsx"
click node_acquisition "https://github.com/jahnzh/sonder/blob/main/server/acquisitions.ts"
click node_catalog_ui "https://github.com/jahnzh/sonder/tree/main/src/pages"
click node_hardcover "https://github.com/jahnzh/sonder/blob/main/server/hardcover.ts"
click node_series_acq "https://github.com/jahnzh/sonder/blob/main/server/series-acquisition.ts"
click node_alignment "https://github.com/jahnzh/sonder/blob/main/server/alignment.ts"
click node_ctc "https://github.com/jahnzh/sonder/blob/main/worker/ctc_pipeline.py"
click node_alignment_pool "https://github.com/jahnzh/sonder/blob/main/server/alignment-pool.ts"
click node_reading_sync "https://github.com/jahnzh/sonder/blob/main/src/pages/reading-sync-model.ts"
click node_api "https://github.com/jahnzh/sonder/blob/main/server/app.ts"
click node_database "https://github.com/jahnzh/sonder/blob/main/server/db.ts"
click node_schema "https://github.com/jahnzh/sonder/blob/main/server/schema.ts"
click node_background "https://github.com/jahnzh/sonder/blob/main/server/background-runner.ts"
click node_backups "https://github.com/jahnzh/sonder/blob/main/server/backups.ts"
click node_media_storage "https://github.com/jahnzh/sonder/blob/main/server/storage.ts"
click node_users "https://github.com/jahnzh/sonder/blob/main/server/users.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_reader,node_player,node_client_data,node_navigation,node_frontend toneBlue
class node_acquisition,node_catalog_ui,node_hardcover,node_series_acq toneAmber
class node_alignment,node_ctc,node_alignment_pool,node_reading_sync toneMint
class node_api,node_database,node_schema,node_background,node_backups,node_media_storage,node_users toneRose
class node_hardcover_service,node_torbox,node_transmission,node_reader_user toneIndigo
```

## Components

### PWA experience

- [Reader](https://github.com/jahnzh/sonder/blob/main/src/components/Reader.tsx): `src/components/Reader.tsx`
- [Audiobook player](https://github.com/jahnzh/sonder/blob/main/src/player.tsx): `src/player.tsx`
- [Client API and storage](https://github.com/jahnzh/sonder/blob/main/src/lib.ts): `src/lib.ts`
- [Navigation](https://github.com/jahnzh/sonder/blob/main/src/navigation.ts): `src/navigation.ts`
- [Application shell](https://github.com/jahnzh/sonder/blob/main/src/App.tsx): `src/App.tsx`

### Library and acquisition

- [Media acquisition](https://github.com/jahnzh/sonder/blob/main/server/acquisitions.ts): `server/acquisitions.ts`
- [Library and discovery](https://github.com/jahnzh/sonder/tree/main/src/pages): `src/pages`
- [Hardcover sync](https://github.com/jahnzh/sonder/blob/main/server/hardcover.ts): `server/hardcover.ts`
- [Series acquisition](https://github.com/jahnzh/sonder/blob/main/server/series-acquisition.ts): `server/series-acquisition.ts`

### Reading synchronization

- [Alignment orchestration](https://github.com/jahnzh/sonder/blob/main/server/alignment.ts): `server/alignment.ts`
- [CTC alignment pipeline](https://github.com/jahnzh/sonder/blob/main/worker/ctc_pipeline.py): `worker/ctc_pipeline.py`
- [Remote worker pool](https://github.com/jahnzh/sonder/blob/main/server/alignment-pool.ts): `server/alignment-pool.ts`
- [Reading sync UI](https://github.com/jahnzh/sonder/blob/main/src/pages/reading-sync-model.ts): `src/pages/reading-sync-model.ts`

### Server platform

- [HTTP application](https://github.com/jahnzh/sonder/blob/main/server/app.ts): `server/app.ts`
- [SQLite database](https://github.com/jahnzh/sonder/blob/main/server/db.ts): `server/db.ts`
- [Data schema](https://github.com/jahnzh/sonder/blob/main/server/schema.ts): `server/schema.ts`
- [Background jobs](https://github.com/jahnzh/sonder/blob/main/server/background-runner.ts): `server/background-runner.ts`
- [Database backups](https://github.com/jahnzh/sonder/blob/main/server/backups.ts): `server/backups.ts`
- [Media storage](https://github.com/jahnzh/sonder/blob/main/server/storage.ts): `server/storage.ts`
- [Accounts and access](https://github.com/jahnzh/sonder/blob/main/server/users.ts): `server/users.ts`

### External services

- **Hardcover API**
- **TorBox**
- **Transmission**

### Other components

- **Reader**

## Connections

- Reader → Application shell: uses (evidence: `README.md`)
- Application shell → Navigation: routes through (evidence: `src/App.tsx`)
- Application shell → Client API and storage: calls API (evidence: `src/App.tsx`)
- Reader → Client API and storage: saves position (evidence: `src/components/Reader.tsx`)
- Audiobook player → Client API and storage: loads media (evidence: `src/player.tsx`)
- Application shell → Reader: renders (evidence: `src/App.tsx`)
- Application shell → Audiobook player: renders (evidence: `src/App.tsx`)
- Client API and storage → HTTP application: requests
- HTTP application → Media acquisition: routes acquisition (evidence: `server/app.ts`)
- HTTP application → Hardcover sync: routes sync (evidence: `server/app.ts`)
- Hardcover sync → Hardcover API: syncs metadata
- HTTP application → Series acquisition: routes series (evidence: `server/app.ts`)
- HTTP application → Alignment orchestration: routes alignment (evidence: `server/app.ts`)
- Alignment orchestration → Remote worker pool: dispatches jobs
- Remote worker pool → CTC alignment pipeline: runs alignment
- Reading sync UI → Client API and storage: loads sync state
- Media acquisition → TorBox: checks cached media (evidence: `server/acquisitions.ts`)
- Media acquisition → Transmission: queues torrents (evidence: `server/acquisitions.ts`)
- Media acquisition → Media storage: resolves files (evidence: `server/acquisitions.ts`)
- HTTP application → Accounts and access: authenticates (evidence: `server/app.ts`)
- HTTP application → SQLite database: uses database (evidence: `server/app.ts`)
- HTTP application → Data schema: uses schema (evidence: `server/app.ts`)
- Hardcover sync → SQLite database: reads and writes (evidence: `server/hardcover.ts`)
- Media acquisition → SQLite database: updates status (evidence: `server/acquisitions.ts`)
- Database backups → SQLite database: backs up (evidence: `README.md`)
- Background jobs → Database backups: schedules (evidence: `README.md`)
