john-okeefe
22fd28c7db
This commit adds complete documentation for the planned Calibre metadata.opf sidecar file support feature. ## New Documentation ### Implementation Planning - CALIBRE_OPF_IMPLEMENTATION.md: Detailed implementation plan with requirements, architecture, database mapping, and step-by-step implementation guide for adding Calibre metadata.opf support ### Technical Documentation - docs/development/calibre-opf-implementation.md: Technical implementation details including: - Scanner pipeline architecture with sidecar-first approach - Data structures (CalibreOPFMetadata, MediaMetadata) - Function signatures and logic for parseCalibreMetadataOPF() - Database schema mapping (no changes required) - Testing strategy (unit and integration tests) - Error handling and performance considerations - Code examples and benchmarking approach ### User Documentation - docs/user/calibre-integration.md: Comprehensive user guide covering: - What is Calibre and how Bookhoard integrates with it - Automatic metadata import from metadata.opf sidecar files - Supported metadata fields (Dublin Core + Calibre-specific) - Setup instructions for Calibre libraries - Workflow examples (fresh library, mixed library, updating metadata) - Troubleshooting common issues - Best practices for Calibre + Bookhoard workflow - FAQ and resources ## Updated Documentation - README.md: Added Calibre integration feature to media management section - docs/user/user-guide.md: Added link to Calibre integration guide - docs/developer/development.md: Added link to Calibre implementation guide ## Feature Summary The Calibre integration feature will allow Bookhoard to automatically import curated metadata from Calibre's metadata.opf sidecar files, including titles, authors, series, tags, descriptions, publishers, identifiers (ISBN/ASIN), and contributors. Uses sidecar-first approach: metadata.opf → embedded metadata → folder structure → filename. All database fields already exist; no schema changes required.
2.7 KiB
2.7 KiB
Developer Documentation
Welcome to the Bookhoard developer documentation. This section contains API references, protocol specifications, and technical documentation for integrating with Bookhoard.
📚 API Documentation
Complete API Reference
- API Reference - Complete REST API reference
- Authentication
- User management
- Libraries
- Media items
- Reading progress
- Notes & highlights
- Analytics
- Book matching
- OPDS
- Sync protocols (KOReader, Kobo)
- WebSocket
Split Endpoint Documentation
Browse individual endpoint documentation with interactive API Explorer:
- API Documentation - Split endpoint docs
- Authentication - Register, login, tokens
- Users - Profile management
- Libraries - Library operations
- Media Items - Book/ebook management
- Progress - Reading progress tracking
- Notes - User notes
- Highlights - Book highlights
- Ratings - Book ratings
- Devices - Device management
- Analytics - Usage statistics
- Book Matching - Search and link books
- Collections - Collection management
- OPDS - Open Publication Distribution
- Sync Protocols - KOReader and Kobo sync
- WebSocket - Real-time events
Collections API
- Collections API - Complete collections API reference
- Create and manage collections
- Auto-assign rules
- Test rules
- Bulk operations
- Device shelf mappings
🔌 Protocol Specifications
Sync Protocols
-
Kobo Sync Protocol - Kobo device sync protocol
- Kobo markup sync
- Library fetch
- Authentication
-
KOReader Sync Protocol - KOReader sync protocol
- Progress sync
- Metadata fetch
- Conflict handling
WebSocket Protocol
- WebSocket API - Real-time sync and events
- Connection flow
- Message format
- Event types
- Authentication
🛠 Implementation Guides
Calibre Integration
- Calibre OPF Implementation - 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 Need to deploy? See the Operations Portal