Design hub

Long-lived design notes, ADRs (architecture decision records), and RFCs for SideshowDB live in the repository under docs/design/ .

Start at the design README for the index, folder conventions, and how to add a new ADR.

Why not only EARS specs?

docs/development/specs/ holds normative user-visible requirements (EARS) that map directly to tests and acceptance scenarios. The design hub holds rationale — options we rejected, vocabulary we chose, and how we expect the API to evolve — so contributors can see the thought behind the code without mixing that narrative into the contract documents.

Trace example

The browser TypeScript client uses hostCapabilities.store instead of a flat hostBridge option; see ADR Host capabilities and host store API .

On-site design narratives

The pages below render extended design narratives directly on the docs site so contributors can read them without bouncing to the repo:

• GitHub API RefStore — the primary remote-backed RefStore, REST-first against GitHub's Git Database API.
• Auth model — credential sources, scopes, rate-limit posture, token-handling guarantees.
• Caching — SHA-keyed immutable caches, ETag handling, IndexedDB-backed reuse.
• Configuration — every config field, CLI flags, TypeScript bindings.
• Operations — provisioning a repo, picking a PAT, verifying health, troubleshooting.