# 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](../contributing/development.md)** — 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](api/api-reference.md)** — every area, auth
  model, and conventions
- Entry points: [Authentication](api/authentication/login.md),
  [Users](api/users/get_profile.md),
  [Libraries](api/libraries/list_libraries.md),
  [Media Items](api/media-items/get_media_item.md),
  [Progress](api/progress/get_media_progress.md),
  [Notes](api/notes/get_notes.md) ·
  [Highlights](api/highlights/get_highlights.md) ·
  [Ratings](api/ratings/get_ratings.md),
  [Devices](api/devices/get_devices.md),
  [Collections](api/collections/list_collections.md),
  [Analytics](api/analytics/get_analytics.md),
  [Book Matching](api/book-matching/search_books.md),
  [OPDS](api/opds/feeds.md),
  [Scanner](api/scanner/overview.md),
  [Admin](api/admin/list_users.md)
- The machine-readable mirror lives at `docs/developer/openapi.yaml`
  (regenerated by the parity test, never hand-edited).

## Protocols

- **[KOReader Sync Protocol](api/sync/koreader-protocol.md)** — progress,
  metadata, conflicts; the plugin's server side
- **[Kobo Sync Protocol](api/sync/kobo-protocol.md)** — native Kobo
  sync (server-complete; device rollout pending — use
  [KOReader](api/sync/koreader-protocol.md) on Kobo hardware today)
- **[WebSocket wire format](websocket-api.md)** — real-time events:
  message catalog, keepalive, fan-out and backpressure contracts
- **[WebSocket endpoint](api/websocket/protocol.md)** — connection
  parameters and endpoint-level reference

## Under the hood

- **[Library Visibility](library-visibility.md)** — how per-user data
  isolation actually works: Postgres RLS, the `app.user_id` GUC,
  ScopedDB, and the rules new code must follow (the database enforces;
  the app declares identity)
- **[Scanner audio metadata](scanner/audio-metadata.md)** — the sidecar
  and tag extraction priority for audiobooks
- **[Calibre OPF Implementation](../development/calibre-opf-implementation.md)** —
  how Calibre sidecar metadata becomes catalog rows
- **[Frontend Integration Notes](../FRONTEND_INTEGRATION.md)** — the
  tag & contributor normalization contract (display fields vs. search
  fields, and why both exist)
- **[Android App — Design & Roadmap](android-app.md)** — the native
  client's design goals and platform posture

## Standards this docs tree enforces

- **[Writing UI documentation without screenshots](writing-ui-docs.md)** —
  the standard for every UI page in this repo
- **[UI control glossary](ui-controls.md)** — the canonical spelling of
  every control the docs cite (the label gate checks it against the
  templates)
- **[Contract Pins](../contract_pins.md)** — 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](../user/user-guide.md).
**Need to deploy or operate?** See the [Operations Portal](../operations/operations.md).