Bookhoard/bookhoard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity

docs: update comprehensive API documentation and project guides

Browse Source 
This commit updates all documentation files throughout the project:

- Updated IMPLEMENTATION_PLAN.md with new implementation details
- Updated PROJECT_GUIDELINES.md with coding standards and practices
- Updated README.md with current project information
- Updated SCREENSHOT_AUTOMATION.md with new automation details
- Added TEST_DATA.md with test fixtures data
- Updated cover_image_serving_plan.md with static URL patterns

Documentation API updates:
- Updated API reference documentation for all endpoints including:
  - Authentication (login, logout, register, refresh_token)
  - Book matching (auto_link, bulk_link, link_book, search)
  - Collections (CRUD operations, shelf mappings, auto-assign rules)
  - Conflicts (bulk operations, resolve/dismiss)
  - Devices (registration, approval, shelf management)
  - Highlights (create, update, delete, get)
  - Kobo sync (bookmark, markup, initialization, sync)
  - KOReader sync (library, metadata, bookmarks, progress)
  - Libraries (CRUD, folders, media items, stats)
  - Media items (bulk operations, CRUD)
  - Notes (CRUD operations)
  - OPDS (acquisition, feeds, publication)
  - Progress (reading progress tracking)
  - Queue (device queue management)
  - Ratings (star ratings)
  - Scanner (watch mode, scan operations)
  - Sync protocols (Kobo, KOReader)
  - Users (profile, password, admin operations)
  - WebSocket protocols

- Updated user guides (admin, dashboard, settings, sync)
- Updated device setup guides (Kobo, KOReader)
- Updated developer guides (testing, contributing, operations)
- Updated scripts/README.md
This commit is contained in:
john-okeefe
2026-02-27 17:06:22 -05:00
parent 6562b20ee5
commit 4d321528b2
154 changed files with 2817 additions and 2152 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/sync-guide.md
+53 -10
View File
@@ -1,6 +1,7 @@
# Bookhoard Universal Sync - User Guide
## Table of Contents
1. [What is Universal Sync?](#what-is-universal-sync)
2. [Supported Devices](#supported-devices)
3. [Getting Started](#getting-started)
@@ -36,19 +37,19 @@
### Currently Supported ✅
| Platform | Status | Sync Method | Notes |
|----------|--------|-------------|-------|
| **Web Browser** | ✅ Fully Supported | Real-time WebSocket | Any modern browser |
| **KOReader** | ✅ Fully Supported | Wi-Fi (Calibre-compatible) | Kindle, Kobo, PocketBook, etc. |
| **Kobo Devices** | ✅ Fully Supported | Wi-Fi (Kobo API-compatible) | Clara, Libra, Sage, etc. |
| Platform | Status | Sync Method | Notes |
| ---------------- | ------------------ | --------------------------- | ------------------------------ |
| **Web Browser** | ✅ Fully Supported | Real-time WebSocket | Any modern browser |
| **KOReader** | ✅ Fully Supported | Wi-Fi (Calibre-compatible) | Kindle, Kobo, PocketBook, etc. |
| **Kobo Devices** | ✅ Fully Supported | Wi-Fi (Kobo API-compatible) | Clara, Libra, Sage, etc. |
### Coming Soon 🚧
| Platform | Expected Release |
|----------|------------------|
| **Mobile Apps** | Q2 2026 |
| **Kindle Devices** | Q3 2026 |
| **Remarkable Tablet** | Q4 2026 |
| Platform | Expected Release |
| --------------------- | ---------------- |
| **Mobile Apps** | Q2 2026 |
| **Kindle Devices** | Q3 2026 |
| **Remarkable Tablet** | Q4 2026 |
---
@@ -79,17 +80,20 @@ For detailed device configuration instructions, see the appropriate setup guide:
### Quick Overview
**Registration Process**:
1. Register device in Bookhoard web interface (Settings → Devices)
2. Approve device via QR code or approval URL
3. Configure sync settings on your device
4. Start reading - progress syncs automatically!
**Device Management**:
```
Settings → Devices
```
You can:
- View all your registered devices
- See last sync time and status
- Disable or remove devices
@@ -103,6 +107,7 @@ You can:
### What is Book Matching?
When devices sync books, Bookhoard tries to automatically match them using:
- **SHA-256 hash** (most reliable) - Content-based fingerprint
- **ISBN** - Standard book identifier
- **UUID** - Unique identifier from EPUB metadata
@@ -111,6 +116,7 @@ When devices sync books, Bookhoard tries to automatically match them using:
### Unlinked Books
Sometimes a book on your device can't be automatically matched to your library. This happens when:
- The book was side-loaded (not downloaded via Bookhoard)
- The file format was converted (EPUB → KEPUB)
- The metadata doesn't match exactly
@@ -143,6 +149,7 @@ Settings → Devices → Select Device → View Unlinked Books
### Reading Progress
**What Syncs**:
- Current page number
- Reading percentage
- Chapter progress
@@ -151,6 +158,7 @@ Settings → Devices → Select Device → View Unlinked Books
- Reading position (viewport, zoom, scroll)
**How It Works**:
```
You turn page → Device sends progress → Server updates database
↓
@@ -160,6 +168,7 @@ You turn page → Device sends progress → Server updates database
```
**Supported Progress Types**:
- **EPUB/MOBI**: Percentage + EPUB CFI + Chapter
- **PDF/DJVU**: Page number + Viewport position
- **CBZ/CBR**: Page number + Panel coordinates
@@ -167,6 +176,7 @@ You turn page → Device sends progress → Server updates database
### Highlights & Notes
**What Syncs**:
- Highlighted text
- Notes and annotations
- Bookmark locations
@@ -175,6 +185,7 @@ You turn page → Device sends progress → Server updates database
**Universal Location References**:
All highlights are stored with multiple location types:
- Page:offset (traditional)
- EPUB CFI (EPUB files)
- Percentage (0-100%)
@@ -186,6 +197,7 @@ This ensures your highlights work across all devices, even with different page c
### Bookmarks
**What Syncs**:
- Bookmark locations
- Bookmark titles
- Date created
@@ -200,12 +212,14 @@ This ensures your highlights work across all devices, even with different page c
**Best For**: Normal reading, page turns
**Behavior**:
- Syncs every page turn
- Real-time updates
- Low latency
- Higher bandwidth usage
**Recommended Settings**:
- Auto-sync: ON
- Sync frequency: Every page turn
@@ -214,12 +228,14 @@ This ensures your highlights work across all devices, even with different page c
**Best For**: Slow connections, battery saving
**Behavior**:
- Batches changes
- Syncs every 5 minutes or when connection allows
- Lower bandwidth
- Better for offline reading
**Recommended Settings**:
- Auto-sync: ON
- Sync frequency: Checkpoint mode
@@ -247,11 +263,13 @@ This ensures your highlights work across all devices, even with different page c
### Offline Indicators
**In Web Interface**:
- Yellow status icon: Device offline
- Last seen timestamp
- "Pending sync" badge on books
**On Devices**:
- Sync icon: Gray = offline
- Sync icon: Blue = syncing
- Sync icon: Green = synced
@@ -265,6 +283,7 @@ This ensures your highlights work across all devices, even with different page c
**Symptoms**: Progress not updating across devices
**Solutions**:
1. Check device is online: `Settings → Devices`
2. Verify sync is enabled for the device
3. Check sync URL is correct
@@ -276,6 +295,7 @@ This ensures your highlights work across all devices, even with different page c
**Cause**: Device not registered or authorization revoked
**Solutions**:
1. Re-register the device
2. Check device hasn't been removed
3. Verify correct device type selected
@@ -285,6 +305,7 @@ This ensures your highlights work across all devices, even with different page c
**Cause**: Too many sync requests
**Solutions**:
1. Wait a few seconds
2. Switch to checkpoint mode
3. Contact admin to increase limits
@@ -296,6 +317,7 @@ This ensures your highlights work across all devices, even with different page c
**Cause**: Same book being read on multiple devices simultaneously
**Solutions**:
1. Go to `Settings → Conflicts`
2. Review both device progress
3. Choose which device's progress to keep
@@ -306,6 +328,7 @@ This ensures your highlights work across all devices, even with different page c
**Cause**: Immediate sync mode with frequent page turns
**Solutions**:
1. Switch to checkpoint mode
2. Increase sync interval
3. Use Wi-Fi instead of cellular (for mobile)
@@ -317,6 +340,7 @@ This ensures your highlights work across all devices, even with different page c
### For Optimal Performance
✅ **DO**:
- Use checkpoint mode when on cellular data
- Keep device firmware updated
- Use Wi-Fi when available
@@ -324,6 +348,7 @@ This ensures your highlights work across all devices, even with different page c
- Regularly check conflict resolution
❌ **DON'T**:
- Read same book on multiple devices simultaneously
- Ignore conflict notifications
- Register public/shared devices
@@ -332,6 +357,7 @@ This ensures your highlights work across all devices, even with different page c
### Organizing Your Library
**For Best Sync Experience**:
- Use consistent metadata (titles, authors)
- Avoid duplicate books in library
- Match files by ISBN when possible
@@ -340,11 +366,13 @@ This ensures your highlights work across all devices, even with different page c
### Managing Multiple Devices
**Recommended Setup**:
- **Primary Device**: KOReader on e-reader
- **Secondary Device**: Web browser (work/home)
- **Mobile Device**: Phone app (commute)
**Sync Strategy**:
1. Read mainly on primary device
2. Check progress on web/secondary devices
3. Let auto-sync handle updates
@@ -357,16 +385,19 @@ This ensures your highlights work across all devices, even with different page c
### Conflict Resolution
**Automatic Resolution**:
- Most recent progress wins
- Timestamp-based comparison
- 5-minute window for conflict detection
**Manual Resolution**:
```
Settings → Conflicts → Select conflict → Choose winner
```
**Options**:
- **Keep Device A**: Use this device's progress
- **Keep Device B**: Use other device's progress
- **Merge**: Keep furthest progress (combination)
@@ -375,17 +406,20 @@ Settings → Conflicts → Select conflict → Choose winner
### Sync Queue Management
**View Queue Status**:
```
Settings → Devices → Select Device → View Queue
```
**Queue Stats**:
- Pending: Waiting to sync
- Processing: Currently syncing
- Failed: Retry scheduled
- Completed: Successfully synced
**Manual Actions**:
- **Retry All**: Retry all failed items
- **Clear Queue**: Remove all pending items
- **Priority Sync**: Sync specific book immediately
@@ -393,17 +427,20 @@ Settings → Devices → Select Device → View Queue
### Reading History
**Automatic Tracking**:
- Every sync session logged
- Time spent reading calculated
- Pages read tracked
- Device used recorded
**View History**:
```
Book → Reading History
```
**Privacy**:
- Only you can see your history
- History kept for 365 days
- Exportable for backup
@@ -415,6 +452,7 @@ Book → Reading History
### Device Authentication
**Secure by Design**:
- ✅ No passwords stored on devices
- ✅ Web-based approval required
- ✅ Unique tokens per device
@@ -424,12 +462,14 @@ Book → Reading History
### Data Protection
**What We Store**:
- Reading progress (page, percentage)
- Highlights and notes
- Device identifiers
- Sync timestamps
**What We DON'T Store**:
- Passwords on devices
- Reading content (your books)
- Unencrypted personal data
@@ -438,11 +478,13 @@ Book → Reading History
### Access Control
**Your Data**:
- Only you can see your progress
- Admins cannot read your annotations
- Shared only with devices you approve
**Device Access**:
- Each device sees only your libraries
- Devices cannot access other users
- Revoking removes all access
@@ -530,6 +572,7 @@ A: Yes, HTTPS/TLS 1.3 for all sync traffic.
## Changelog
### Version 1.0.0 (January 2026)
- ✅ Initial release
- ✅ KOReader sync support
- ✅ Kobo device support