docs(dev): developer portal rewritten; tier definition closed in the standard
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.
This commit is contained in:
John O'Keefe committed
1 parent
35b210951a
commit
ab5c52c709
2 files changed
+79
-81
No files matched your search
@@ -1,95 +1,90 @@
|
||||
# Developer Documentation
|
||||
|
||||
Welcome to the Bookhoard developer documentation. This section contains API references, protocol specifications, and technical documentation for integrating with Bookhoard.
|
||||
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`.
|
||||
|
||||
## 📚 API Documentation
|
||||
## Start here: architecture, setup, testing
|
||||
|
||||
### Complete API Reference
|
||||
**[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](api/api-reference.md)** - Complete REST API reference
|
||||
- Authentication
|
||||
- User management
|
||||
- Libraries
|
||||
- Media items
|
||||
- Reading progress
|
||||
- Notes & highlights
|
||||
- Analytics
|
||||
- Book matching
|
||||
- OPDS
|
||||
- Sync protocols (KOReader, Kobo)
|
||||
- WebSocket
|
||||
## API Reference
|
||||
|
||||
### Split Endpoint Documentation
|
||||
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):
|
||||
|
||||
Browse individual endpoint documentation:
|
||||
- **[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).
|
||||
|
||||
- **[API Documentation](api/api-reference.md)** - Split endpoint docs
|
||||
- [Authentication](api/authentication/login.md) - Register, login, tokens
|
||||
- [Users](api/users/get_profile.md) - Profile management
|
||||
- [Libraries](api/libraries/list_libraries.md) - Library operations
|
||||
- [Media Items](api/media-items/get_media_item.md) - Book/ebook management
|
||||
- [Progress](api/progress/get_media_progress.md) - Reading progress tracking
|
||||
- [Notes](api/notes/get_notes.md) - User notes
|
||||
- [Highlights](api/highlights/get_highlights.md) - Book highlights
|
||||
- [Ratings](api/ratings/get_ratings.md) - Book ratings
|
||||
- [Devices](api/devices/get_devices.md) - Device management
|
||||
- [Analytics](api/analytics/get_analytics.md) - Usage statistics
|
||||
- [Book Matching](api/book-matching/search_books.md) - Search and link books
|
||||
- [Collections](api/collections/list_collections.md) - Collection management
|
||||
- [OPDS](api/opds/feeds.md) - Open Publication Distribution
|
||||
- [Sync Protocols](api/sync/koreader-protocol.md) - KOReader and Kobo sync
|
||||
- [WebSocket](api/websocket/protocol.md) - Real-time events
|
||||
## Protocols
|
||||
|
||||
### Collections API
|
||||
- **[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
|
||||
|
||||
- **[Collections API](api/collections/list_collections.md)** - Complete collections API reference
|
||||
- Create and manage collections
|
||||
- Auto-assign rules
|
||||
- Test rules
|
||||
- Bulk operations
|
||||
- Device shelf mappings
|
||||
## Under the hood
|
||||
|
||||
## 🔌 Protocol Specifications
|
||||
- **[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
|
||||
|
||||
### Sync Protocols
|
||||
## Standards this docs tree enforces
|
||||
|
||||
- **[Kobo Sync Protocol](api/sync/kobo-protocol.md)** - Kobo device sync protocol
|
||||
- Kobo markup sync
|
||||
- Library fetch
|
||||
- Authentication
|
||||
- **[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
|
||||
|
||||
- **[KOReader Sync Protocol](api/sync/koreader-protocol.md)** - KOReader sync protocol
|
||||
- Progress sync
|
||||
- Metadata fetch
|
||||
- Conflict handling
|
||||
|
||||
### WebSocket Protocol
|
||||
|
||||
- **[WebSocket API](websocket-api.md)** - Real-time sync and events
|
||||
- Connection flow
|
||||
- Message format
|
||||
- Event types
|
||||
- Authentication
|
||||
|
||||
## 🛠 Implementation Guides
|
||||
|
||||
### Library Visibility
|
||||
|
||||
- **[Library Visibility](library-visibility.md)** - Per-user library
|
||||
visibility: the family-lens rule. New media endpoints MUST thread the
|
||||
visible-library set (helpers, SQL pattern, series per-library).
|
||||
|
||||
### Calibre Integration
|
||||
|
||||
- **[Calibre OPF Implementation](../development/calibre-opf-implementation.md)** - Technical implementation details
|
||||
- Architecture and design
|
||||
- Data structures and functions
|
||||
- Database schema mapping
|
||||
- Testing strategy
|
||||
- Error handling
|
||||
- Performance considerations
|
||||
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?** See the [Operations Portal](../operations/operations.md)
|
||||
**Looking for user documentation?** See the [User Portal](../user/user-guide.md).
|
||||
**Need to deploy or operate?** See the [Operations Portal](../operations/operations.md).
|
||||
@@ -86,9 +86,12 @@ make the page followable even if that label is renamed next week.
|
||||
No API-client detail: request and response schemas live in the developer
|
||||
docs. The calibration in one line: **user = what you see, admin = what
|
||||
it does, developer = how it works.**
|
||||
- **Developer section — tone is a separate discussion, not yet decided.**
|
||||
Write it plainly and hand-off-rich as well; do not import opinions about
|
||||
its voice until that pass happens.
|
||||
- **Developer section — source-pinned and wire-accurate.** The
|
||||
developer tier is *how it works*: wire formats, data access, pipeline
|
||||
mechanics, and enforced rules, every claim grounded in source the way
|
||||
admin docs ground behavior. External software (device installs,
|
||||
third-party tooling) is linked to its project's documentation, not
|
||||
paraphrased. (Decided 2026-11-02, closing the earlier open question.)
|
||||
|
||||
## Generate what has a registry
|
||||
|
||||
|
||||
Reference in new issue
Block a user