bookhoard/docs/user/sync-guide.md

Bookhoard Universal Sync - User Guide

Table of Contents

1. What is Universal Sync?
2. Supported Devices
3. Getting Started
4. Device Setup
5. Using Sync Features
6. Book Matching
7. Managing Conflicts
8. 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. Set up your first device - See Device Setup below
2. Start reading - Open any book in the web interface or on your device
3. Turn pages - Progress syncs automatically
4. Switch devices - Pick up any other device - your progress is there!

---

Device Setup

For detailed device configuration instructions, see the appropriate setup guide:

• Kobo Setup Guide - Kobo e-reader configuration
• KOReader Setup Guide - KOReader configuration

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
• View unlinked books that need matching
• Manage file aliases

---

Book Matching

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
• Title + Author (fallback) - Last resort matching

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

Viewing Unlinked Books

Settings → Devices → Select Device → View Unlinked Books

Resolving Unlinked Books

1. Auto-Link - Automatically link books with 80%+ confidence
2. Get Suggestions - Review potential matches before linking
3. Manual Link - Choose the correct match yourself

Book Matching Priority

1. Bookhoard UUID - 100% confidence
2. OPF UUID - 95% confidence
3. SHA-256 hash - 90% confidence
4. OPF identifier - 85% confidence
5. ISBN/ASIN - 80% confidence
6. Title + Author + File Size - 50% confidence

---

Managing Conflicts

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