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.
91 lines
4.0 KiB
Markdown
91 lines
4.0 KiB
Markdown
# 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).
|