bookhoard/docs/SYNC_USER_GUIDE.md

Bookhoard Universal Sync - User Guide

Table of Contents

1. What is Universal Sync?
2. Supported Devices
3. Getting Started
4. Device Registration
5. Sync Features
6. Troubleshooting
7. 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