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
|
# 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
|
## API Reference
|
||||||
- Authentication
|
|
||||||
- User management
|
|
||||||
- Libraries
|
|
||||||
- Media items
|
|
||||||
- Reading progress
|
|
||||||
- Notes & highlights
|
|
||||||
- Analytics
|
|
||||||
- Book matching
|
|
||||||
- OPDS
|
|
||||||
- Sync protocols (KOReader, Kobo)
|
|
||||||
- WebSocket
|
|
||||||
|
|
||||||
### 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
|
## Protocols
|
||||||
- [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
|
|
||||||
|
|
||||||
### 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
|
## Under the hood
|
||||||
- Create and manage collections
|
|
||||||
- Auto-assign rules
|
|
||||||
- Test rules
|
|
||||||
- Bulk operations
|
|
||||||
- Device shelf mappings
|
|
||||||
|
|
||||||
## 🔌 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
|
- **[Writing UI documentation without screenshots](writing-ui-docs.md)** —
|
||||||
- Kobo markup sync
|
the standard for every UI page in this repo
|
||||||
- Library fetch
|
- **[UI control glossary](ui-controls.md)** — the canonical spelling of
|
||||||
- Authentication
|
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
|
The gates behind all of it: routes ↔ docs coverage, docs ↔ Bruno
|
||||||
- Progress sync
|
parity, relative-link resolution, UI-label existence, and the RLS
|
||||||
- Metadata fetch
|
invariant test. Adding a route without a doc — or renaming a button the
|
||||||
- Conflict handling
|
docs quote — fails the suite, by design.
|
||||||
|
|
||||||
### 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
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**Looking for user documentation?** See the [User Portal](../user/user-guide.md)
|
**Looking for user documentation?** See the [User Portal](../user/user-guide.md).
|
||||||
**Need to deploy?** See the [Operations Portal](../operations/operations.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
|
No API-client detail: request and response schemas live in the developer
|
||||||
docs. The calibration in one line: **user = what you see, admin = what
|
docs. The calibration in one line: **user = what you see, admin = what
|
||||||
it does, developer = how it works.**
|
it does, developer = how it works.**
|
||||||
- **Developer section — tone is a separate discussion, not yet decided.**
|
- **Developer section — source-pinned and wire-accurate.** The
|
||||||
Write it plainly and hand-off-rich as well; do not import opinions about
|
developer tier is *how it works*: wire formats, data access, pipeline
|
||||||
its voice until that pass happens.
|
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
|
## Generate what has a registry
|
||||||
|
|
||||||
|
|||||||
Reference in new issue
Block a user