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.
90 lines
2.7 KiB
Markdown
90 lines
2.7 KiB
Markdown
# 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](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
|
|
|
|
### Split Endpoint Documentation
|
|
|
|
Browse individual endpoint documentation with interactive API Explorer:
|
|
|
|
- **[API Documentation](api/api-reference.md)** - Split endpoint docs
|
|
- [Authentication](api/authentication/) - Register, login, tokens
|
|
- [Users](api/users/) - Profile management
|
|
- [Libraries](api/libraries/) - Library operations
|
|
- [Media Items](api/media-items/) - Book/ebook management
|
|
- [Progress](api/progress/) - Reading progress tracking
|
|
- [Notes](api/notes/) - User notes
|
|
- [Highlights](api/highlights/) - Book highlights
|
|
- [Ratings](api/ratings/) - Book ratings
|
|
- [Devices](api/devices/) - Device management
|
|
- [Analytics](api/analytics/) - Usage statistics
|
|
- [Book Matching](api/book-matching/) - Search and link books
|
|
- [Collections](api/collections/) - Collection management
|
|
- [OPDS](api/opds/) - Open Publication Distribution
|
|
- [Sync Protocols](api/sync/) - KOReader and Kobo sync
|
|
- [WebSocket](api/websocket/) - Real-time events
|
|
|
|
### Collections API
|
|
|
|
- **[Collections API](collections-api.md)** - 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](api/sync/kobo-protocol.md)** - Kobo device sync protocol
|
|
- Kobo markup sync
|
|
- Library fetch
|
|
- Authentication
|
|
|
|
- **[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
|
|
|
|
### 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)
|
|
**Need to deploy?** See the [Operations Portal](../operations/operations.md)
|