John O'Keefe
ab5c52c709
development.md was a bare link list whose 'implementation guides' blurb still taught the pre-RLS visibility pattern. Now it's the developer-tier portal: contributing/development.md as the start-here (architecture/setup/testing — fresh and maintained), the gated API reference with its per-area entry points and the openapi.yaml mirror, the four protocol docs, the under-the-hood guides (RLS visibility, scanner sidecars, calibre OPF, tag-normalization contract, Android design), the standards (writing-ui-docs, glossary, contract pins), and the gates enumerated — routes<->docs, Bruno parity, links, labels, RLS invariant. writing-ui-docs.md's Developer-tier line closes the open tone question: how-it-works, source-pinned, external software linked not paraphrased.
4.0 KiB
Developer Documentation
The developer tier of Bookhoard's docs: how it works — wire formats,
data access, pipelines, and the rules the codebase enforces on you.
(User docs tell you what things do; admin docs what the controls do;
this section is the machinery itself.) Everything here is written
against the source and kept honest by gates — if a doc and the code
disagree, one of them fails make test.
Start here: architecture, setup, testing
Development Guide — the working developer's page: directory structure, backend components, database schema, tech stack, local setup, code generation (sqlc / templ / vite), build targets, and the full testing doctrine with its rules.
API Reference
Two hundred endpoint documents, one per route, generated-adjacent and gate-checked against the router (a route without a doc fails the build, and so does a doc whose request examples drift from the Bruno collection):
- API Reference overview — every area, auth model, and conventions
- Entry points: Authentication, Users, Libraries, Media Items, Progress, Notes · Highlights · Ratings, Devices, Collections, Analytics, Book Matching, OPDS, Scanner, Admin
- The machine-readable mirror lives at
docs/developer/openapi.yaml(regenerated by the parity test, never hand-edited).
Protocols
- KOReader Sync Protocol — progress, metadata, conflicts; the plugin's server side
- Kobo Sync Protocol — native Kobo sync (server-complete; device rollout pending — use KOReader on Kobo hardware today)
- WebSocket wire format — real-time events: message catalog, keepalive, fan-out and backpressure contracts
- WebSocket endpoint — connection parameters and endpoint-level reference
Under the hood
- Library Visibility — how per-user data
isolation actually works: Postgres RLS, the
app.user_idGUC, ScopedDB, and the rules new code must follow (the database enforces; the app declares identity) - Scanner audio metadata — the sidecar and tag extraction priority for audiobooks
- Calibre OPF Implementation — how Calibre sidecar metadata becomes catalog rows
- Frontend Integration Notes — the tag & contributor normalization contract (display fields vs. search fields, and why both exist)
- Android App — Design & Roadmap — the native client's design goals and platform posture
Standards this docs tree enforces
- Writing UI documentation without screenshots — the standard for every UI page in this repo
- UI control glossary — the canonical spelling of every control the docs cite (the label gate checks it against the templates)
- Contract Pins — the API contract changelog; loosening a pinned assertion requires an entry there
The gates behind all of it: routes ↔ docs coverage, docs ↔ Bruno parity, relative-link resolution, UI-label existence, and the RLS invariant test. Adding a route without a doc — or renaming a button the docs quote — fails the suite, by design.
Looking for user documentation? See the User Portal. Need to deploy or operate? See the Operations Portal.