# 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.

## Records

- [Plugin capabilities v3](/docs/adr/plugin-capabilities-v3/index.md): entrypoints,
  triggers, typed Cap'n Proto and `env.EVENTS`.
- [Workers RPC and workerd](/docs/adr/plugin-workers-rpc-workerd/index.md): jail,
  isolation and the workerd pin (partly superseded by v3).
- [First-party identity](/docs/adr/first-party-identity/index.md): Owner, Administrator
  and Member, passkeys and OIDC.
- [Plugin-provided OIDC clients](/docs/adr/plugin-oidc-clients/index.md): players declare
  identity-provider clients.
- [SQL database contract](/docs/adr/sql-database-contract/index.md): host-resolved
  canonical SQL, adapter-owned lowering.
- [Schema versioning](/docs/adr/schema-versioning/index.md): frozen schema numbers,
  checksums and backups.
- [Control plane](/docs/adr/control-plane/index.md): the bootstrap boundary, host
  identity and library coordination.
- [Untrusted-input fuzzing](/docs/adr/untrusted-input-fuzzing/index.md): every untrusted
  boundary ships a fuzz target.
- [Security advisory automation](/docs/adr/security-advisory-automation/index.md): draft
  advisories for shipped code.
- [Logging and tracing](/docs/adr/observability/index.md): trace everything, keep TRACE
  for diagnostics, show each output its own level.
- [Library data model](/docs/adr/library-data-model/index.md): FRBR works, expressions
  and editions, holdings and edition files.
- [Web API contract checks](/docs/adr/web-api-contract-checks/index.md): the document is
  checked against examples in tests and against real responses in CI.
- [Project licensing](/docs/adr/licensing/index.md): AGPL for the project, MIT OR
  Apache-2.0 for the plugin SDKs, a CLA and a trademark policy.
- [Event delivery model](/docs/adr/event-delivery-model/index.md): events fan out to
  every subscriber, jobs have one handler, and subscriptions follow
  deployments.
- [Library catalog network](/docs/adr/library-catalog-network/index.md): a branch of
  several libraries, what each library owns, and how libraries list and
  lend books.
- [Metadata claims and file sync](/docs/adr/metadata-claims-and-file-sync/index.md): 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](/docs/adr/edition-chapters/index.md): 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](/docs/adr/patron-scopes/index.md): which part of the
  library a Member sees, and how a linked server's permissions and
  suspensions follow one authority.
- [Uploads and ingest batches](/docs/adr/uploads-and-ingest/index.md): 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](/docs/adr/storage-destinations/index.md): every storage plugin
  instance is a destination with its own template and filter,
  opportunistic change feeds and host-held webhooks.
- [Desktop window identity](/docs/adr/desktop-window-identity/index.md): 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](/docs/adr/owner-and-operator/index.md): the rule for which
  actions need elevation, and the switches an Owner sets on each
  Administrator.
- [Playback](/docs/adr/playback/index.md): 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](/docs/adr/master-key-store/index.md): 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](/docs/adr/ingress-plugins/index.md): one action gives an install a
  stable public address, through relay or dynamic DNS plugins.
- [Notifications](/docs/adr/notifications/index.md): 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](/docs/adr/drop-folders/index.md): 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](/docs/adr/player-api/index.md): the host serves apps made for
  Audiobookshelf servers at `/player`, with player cards and no account
  password.
- [Model plugins and the AI binding](/docs/adr/ai-models/index.md): 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](/docs/contributing/writing-docs/index.md) has
the format.
