Design decisions
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.
- 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.keythen 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
aientrypoint, every caller reaches them through oneAIbinding, and the host loads no model.
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