Bookclerk documentation

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

Bookclerk gathers the audiobooks you bought from several stores into one library that you control: it syncs what you own, downloads your copies, saves them where you choose, and connects to library servers such as Audiobookshelf.

The docs are grouped by what you want to do. Start with the first group; the others go deeper.

Use Bookclerk

Run a server

Build plugins

How it works

Contribute

Build and agent conventions for this repository live in AGENTS.md.

Design decisions

  • Design decisions: the decision log
  • Plugin capabilities v3: entrypoints, triggers, typed Cap'n Proto and env.EVENTS
  • Workers RPC and workerd: jail, isolation and the workerd pin (partly superseded by v3)
  • First-party identity: Owner, Administrator and Member, passkeys and OIDC
  • Plugin-provided OIDC clients: players declare identity-provider clients
  • SQL database contract: host-resolved canonical SQL, adapter-owned lowering
  • Schema versioning: frozen schema numbers, checksums and backups
  • Control plane: the bootstrap boundary, host identity and library coordination
  • Untrusted-input fuzzing: every untrusted boundary ships a fuzz target
  • Security advisory automation: draft advisories for shipped code
  • Logging and tracing: trace everything, keep TRACE for diagnostics, show each output its own level
  • Library data model: FRBR works, expressions and editions, holdings and edition files
  • Web API contract checks: the document is checked against examples in tests and against real responses in CI
  • Project licensing: AGPL for the project, MIT OR Apache-2.0 for the plugin SDKs, a CLA and a trademark policy
  • Event delivery model: events fan out to every subscriber, jobs have one handler, subscriptions follow deployments
  • Library catalog network: a branch of several libraries, what each library owns, and how libraries list and lend books
  • Metadata claims and file sync: every value is a claim with its source, one resolver, evidence-based works, and two-way sync with tags and sidecar files
  • Edition chapters: chapters belong to the edition, each source's list is a claim, and Bookclerk's aligned result wins unless an Administrator edits or pins
  • Patron scopes and linked sign-in: which part of the library a Member sees, and how a linked server's permissions follow one authority
  • Desktop window identity: the window is the person signed in to the computer, named by a per-account profile
  • Playback: playback is a host feature with one core that the web player, the desktop window and app-compatible clients share
  • Player API: the host serves apps made for Audiobookshelf servers at /player, with player cards and no account password
  • Storage destinations: every storage plugin instance is a destination with its own template and filter, opportunistic change feeds and host-held webhooks
  • Master key store: the library key can live in the OS keychain, with master.key as a pointer and recovery copies
  • Uploads and ingest batches: one batch per upload, patron holdings for uploaded books, strong identifiers only, archives expanded under caps
  • What needs the operator: the rule for which actions need elevation, and the switches an Owner sets on each Administrator
  • Ingress plugins: one action gives an install a stable public address, through relay or dynamic DNS plugins
  • Notifications: the host routes events into send jobs, notifier plugins send them, and account mail carries reset and recovery
  • Drop folders: a storage instance can be a watched drop folder instead of a destination, settled by the host and added by the ingest job
  • Model plugins and the AI binding: models run in jailed plugins behind an ai entrypoint, and every caller reaches them through one AI binding

Source: docs/README.md at main · View as Markdown