john-okeefe
ff96ffa92d
Documentation updates: - All docs/ files: Update project references - Bruno API collection: Update collection name and tests - Device setup guides: Update all examples - Implementation plan: Update database schema examples - README files: Update project references Part of project rename to Bookhoard.
534 lines
12 KiB
Markdown
534 lines
12 KiB
Markdown
# 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)
|
|
4. [Device Registration](#device-registration)
|
|
5. [Sync Features](#sync-features)
|
|
6. [Troubleshooting](#troubleshooting)
|
|
7. [Best Practices](#best-practices)
|
|
|
|
---
|
|
|
|
## What is Universal Sync?
|
|
|
|
**Universal Sync** is Bookhoard's cross-platform synchronization system that keeps your reading progress, highlights, and notes in sync across all your devices - automatically and in real-time.
|
|
|
|
### Key Features
|
|
|
|
🔄 **Automatic Sync** - Your reading progress syncs automatically when you turn pages
|
|
|
|
📱 **Multi-Platform** - Works with web browsers, KOReader, Kobo devices, and mobile apps
|
|
|
|
📍 **Precise Location Tracking** - Supports EPUB CFI, page numbers, percentages, and character offsets
|
|
|
|
⚡ **Real-Time Updates** - See your progress update across all devices instantly
|
|
|
|
🔒 **Secure** - No passwords on devices, web-based authentication only
|
|
|
|
📴 **Offline Support** - Queue changes when offline, sync when reconnected
|
|
|
|
---
|
|
|
|
## Supported Devices
|
|
|
|
### 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. |
|
|
|
|
### Coming Soon 🚧
|
|
|
|
| Platform | Expected Release |
|
|
|----------|------------------|
|
|
| **Mobile Apps** | Q2 2026 |
|
|
| **Kindle Devices** | Q3 2026 |
|
|
| **Remarkable Tablet** | Q4 2026 |
|
|
|
|
---
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
1. **Bookhoard Server** - Self-hosted instance running and accessible
|
|
2. **Network Connection** - Devices must be able to reach your Bookhoard server
|
|
3. **User Account** - Created and logged in to Bookhoard web interface
|
|
|
|
### Quick Start
|
|
|
|
1. **Start Reading** - Open any book in the web interface or on your device
|
|
2. **Turn Pages** - Progress syncs automatically
|
|
3. **Switch Devices** - Pick up any other device - your progress is there!
|
|
|
|
---
|
|
|
|
## Device Registration
|
|
|
|
### Step-by-Step Guide
|
|
|
|
#### Option 1: Web-Based Registration (Recommended)
|
|
|
|
1. **On Your Device**:
|
|
- Open your reading app (KOReader/Kobo)
|
|
- Navigate to sync settings
|
|
- Find "Bookhoard Sync" or "Calibre Sync"
|
|
- Copy your device identifier (hardware ID)
|
|
|
|
2. **In Your Browser**:
|
|
- Go to your Bookhoard server
|
|
- Log in with your account
|
|
- Navigate to **Settings → Devices**
|
|
- Click **Register New Device**
|
|
- Enter your device name and type
|
|
- Click **Generate Registration**
|
|
|
|
3. **Complete Registration**:
|
|
- Scan the QR code OR copy the registration URL
|
|
- Visit the approval URL in your browser
|
|
- Review device details and click **Approve**
|
|
- Device will receive authentication token
|
|
|
|
4. **Configure Sync**:
|
|
- Enter the sync URL provided (e.g., `https://bookhoard.example.com/api/sync/koreader`)
|
|
- Enable auto-sync
|
|
- Set sync frequency (recommended: Every page turn)
|
|
|
|
#### Option 2: Direct Device Registration
|
|
|
|
1. **From Your Device**:
|
|
- Navigate to sync settings
|
|
- Select "Bookhoard Sync"
|
|
- Enter server URL: `https://bookhoard.example.com`
|
|
- Click "Register Device"
|
|
- Device will display registration code
|
|
|
|
2. **In Your Browser**:
|
|
- Go to `https://bookhoard.example.com/devices/approve`
|
|
- Enter registration code
|
|
- Approve the device
|
|
|
|
### Device Management
|
|
|
|
**View Your Devices**:
|
|
```
|
|
Settings → Devices
|
|
```
|
|
|
|
**Manage Devices**:
|
|
- **Rename**: Click device name → Edit
|
|
- **Disable Sync**: Toggle "Sync Enabled"
|
|
- **Remove Device**: Click "Delete" (revokes access immediately)
|
|
|
|
---
|
|
|
|
## Sync Features
|
|
|
|
### Reading Progress
|
|
|
|
**What Syncs**:
|
|
- Current page number
|
|
- Reading percentage
|
|
- Chapter progress
|
|
- EPUB CFI (for EPUB files)
|
|
- Last read timestamp
|
|
- Reading position (viewport, zoom, scroll)
|
|
|
|
**How It Works**:
|
|
```
|
|
You turn page → Device sends progress → Server updates database
|
|
↓
|
|
Broadcasts to all your devices
|
|
↓
|
|
Other devices update their display
|
|
```
|
|
|
|
**Supported Progress Types**:
|
|
- **EPUB/MOBI**: Percentage + EPUB CFI + Chapter
|
|
- **PDF/DJVU**: Page number + Viewport position
|
|
- **CBZ/CBR**: Page number + Panel coordinates
|
|
|
|
### Highlights & Notes
|
|
|
|
**What Syncs**:
|
|
- Highlighted text
|
|
- Notes and annotations
|
|
- Bookmark locations
|
|
- Colors and formatting
|
|
- Chapter/paragraph references
|
|
|
|
**Universal Location References**:
|
|
All highlights are stored with multiple location types:
|
|
- Page:offset (traditional)
|
|
- EPUB CFI (EPUB files)
|
|
- Percentage (0-100%)
|
|
- Character offset (exact position)
|
|
- Chapter references
|
|
|
|
This ensures your highlights work across all devices, even with different page counts!
|
|
|
|
### Bookmarks
|
|
|
|
**What Syncs**:
|
|
- Bookmark locations
|
|
- Bookmark titles
|
|
- Date created
|
|
- Reading position context
|
|
|
|
---
|
|
|
|
## Sync Modes
|
|
|
|
### Immediate Mode (Default)
|
|
|
|
**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
|
|
|
|
### Checkpoint Mode
|
|
|
|
**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
|
|
|
|
---
|
|
|
|
## Offline Support
|
|
|
|
### How Offline Sync Works
|
|
|
|
1. **Offline Reading**:
|
|
- Read normally without connection
|
|
- All progress tracked locally
|
|
|
|
2. **Queue Changes**:
|
|
- Progress changes queued automatically
|
|
- Annotations saved locally
|
|
- Up to 100 items in offline queue
|
|
|
|
3. **Reconnection**:
|
|
- Connect to Wi-Fi
|
|
- Queue processes automatically
|
|
- Priority items first (book completion, notes)
|
|
- All devices updated
|
|
|
|
### 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
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Sync Not Working
|
|
|
|
**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
|
|
4. Ensure device has network connection
|
|
5. Try manual sync: Open book → Menu → Sync Now
|
|
|
|
### "Device Not Found" Error
|
|
|
|
**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
|
|
|
|
### "Rate Limit Exceeded" Error
|
|
|
|
**Cause**: Too many sync requests
|
|
|
|
**Solutions**:
|
|
1. Wait a few seconds
|
|
2. Switch to checkpoint mode
|
|
3. Contact admin to increase limits
|
|
|
|
### Conflicts Detected
|
|
|
|
**Symptoms**: "Sync conflict" notification
|
|
|
|
**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
|
|
4. Or choose "Merge" (keeps furthest progress)
|
|
|
|
### High Battery Usage
|
|
|
|
**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)
|
|
|
|
---
|
|
|
|
## Best Practices
|
|
|
|
### For Optimal Performance
|
|
|
|
✅ **DO**:
|
|
- Use checkpoint mode when on cellular data
|
|
- Keep device firmware updated
|
|
- Use Wi-Fi when available
|
|
- Approve only devices you own
|
|
- Regularly check conflict resolution
|
|
|
|
❌ **DON'T**:
|
|
- Read same book on multiple devices simultaneously
|
|
- Ignore conflict notifications
|
|
- Register public/shared devices
|
|
- Exceed device limits (max 10 per user)
|
|
|
|
### Organizing Your Library
|
|
|
|
**For Best Sync Experience**:
|
|
- Use consistent metadata (titles, authors)
|
|
- Avoid duplicate books in library
|
|
- Match files by ISBN when possible
|
|
- Use clean file structure
|
|
|
|
### 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
|
|
4. Resolve conflicts promptly
|
|
|
|
---
|
|
|
|
## Advanced Features
|
|
|
|
### 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)
|
|
- **Auto-Resolve Future**: Always prefer this device
|
|
|
|
### 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
|
|
|
|
### 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
|
|
|
|
---
|
|
|
|
## Security & Privacy
|
|
|
|
### Device Authentication
|
|
|
|
**Secure by Design**:
|
|
- ✅ No passwords stored on devices
|
|
- ✅ Web-based approval required
|
|
- ✅ Unique tokens per device
|
|
- ✅ Revocable at any time
|
|
- ✅ Token encryption in transit
|
|
|
|
### 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
|
|
- Location data (GPS)
|
|
|
|
### 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
|
|
|
|
---
|
|
|
|
## Performance Tips
|
|
|
|
### For Faster Sync
|
|
|
|
1. **Use 5GHz Wi-Fi** - Faster than 2.4GHz
|
|
2. **Keep server nearby** - Low latency = better sync
|
|
3. **Regular updates** - Keeps firmware current
|
|
4. **Checkpoint mode** - For batch processing
|
|
|
|
### For Better Battery Life
|
|
|
|
1. **Checkpoint mode** - Fewer sync requests
|
|
2. **Wi-Fi only** - Disable cellular
|
|
3. **Increase sync interval** - Fewer updates
|
|
4. **Close when not reading** - Reduces background activity
|
|
|
|
---
|
|
|
|
## FAQ
|
|
|
|
### General Questions
|
|
|
|
**Q: Does sync work with all book formats?**
|
|
A: Yes! EPUB, PDF, MOBI, CBZ, CBR and more.
|
|
|
|
**Q: Can multiple users share a device?**
|
|
A: No, devices are tied to individual accounts for security.
|
|
|
|
**Q: What happens if I delete a book?**
|
|
A: All sync data for that book is removed from the server.
|
|
|
|
**Q: Can I export my reading data?**
|
|
A: Yes! Settings → Export → Download sync data.
|
|
|
|
**Q: Does sync work over the internet?**
|
|
A: Yes, if your server is publicly accessible with HTTPS.
|
|
|
|
**Q: How much data does sync use?**
|
|
A: Approximately 1KB per page turn, 50KB per annotation.
|
|
|
|
### Technical Questions
|
|
|
|
**Q: How does sync handle different page counts?**
|
|
A: Uses percentage and EPUB CFI for universal positioning.
|
|
|
|
**Q: Can I sync with Calibre anymore?**
|
|
A: Yes! KOReader sync is Calibre-compatible.
|
|
|
|
**Q: What if I lose my device?**
|
|
A: Revoke it in settings and register a new one.
|
|
|
|
**Q: Is sync end-to-end encrypted?**
|
|
A: Yes, HTTPS/TLS 1.3 for all sync traffic.
|
|
|
|
---
|
|
|
|
## Getting Help
|
|
|
|
### Documentation
|
|
|
|
- **API Docs**: `/docs/api.md`
|
|
- **Device Guides**: `/docs/devices/`
|
|
- **Self-Hosting**: `/docs/install.md`
|
|
|
|
### Support
|
|
|
|
- **Issues**: Report bugs at GitHub Issues
|
|
- **Discussions**: Join GitHub Discussions
|
|
- **Email**: support@bookhoard.example.com
|
|
|
|
### Community
|
|
|
|
- **Forum**: community.bookhoard.example.com
|
|
- **Matrix**: #bookhoard:matrix.org
|
|
- **Discord**: discord.gg/bookhoard
|
|
|
|
---
|
|
|
|
## Changelog
|
|
|
|
### Version 1.0.0 (January 2026)
|
|
- ✅ Initial release
|
|
- ✅ KOReader sync support
|
|
- ✅ Kobo device support
|
|
- ✅ Web sync support
|
|
- ✅ Conflict resolution
|
|
- ✅ Offline queue
|
|
- ✅ Real-time WebSocket sync
|
|
|
|
---
|
|
|
|
**Last Updated**: January 31, 2026
|
|
**Version**: 1.0.0
|
|
**License**: MIT
|