Design decisions

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

Last updated View as Markdown

This shelf is the decision log: one architecture decision record (ADR) for each choice that shapes Bookclerk. Each record keeps the usual form, a Status line, then Context, Decision and Consequences. When a later change supersedes one, its Status says so.

Records

  • 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, and 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 decides, works are grouped by evidence, and tags and sidecar files sync both ways.
  • 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 and suspensions follow one authority.
  • Uploads and ingest batches: one batch per upload, patron holdings for uploaded books, identification by strong identifiers only, and archives expanded under caps in the media worker.
  • Storage destinations: every storage plugin instance is a destination with its own template and filter, opportunistic change feeds and host-held webhooks.
  • Desktop window identity: the desktop window is the person signed in to the computer's OS account, whose session its branch keeps sealed, and elevates like anyone else.
  • What needs the operator: the rule for which actions need elevation, and the switches an Owner sets on each Administrator.
  • Playback: playback is a host feature with one core (progress, sessions, one rights check, one stream route) that the web player, the desktop window and app-compatible clients share.
  • Master key store: the library key can live in the OS keychain, master.key then only points at it, and recovery copies replace copying the file.
  • 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 by administrator rules and patron preferences, 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.
  • Player API: the host serves apps made for Audiobookshelf servers at /player, with player cards and no account password.
  • Model plugins and the AI binding: models run in jailed plugins behind an ai entrypoint, every caller reaches them through one AI binding, and the host loads no model.

Adding a record

A new architecture decision gets a new file here, listed above and in the site navigation. Writing docs has the format.

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