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 and KOReader, with native Kobo sync and mobile apps on the roadmap

📍 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 (Bookhoard plugin)	Kindle, Kobo, PocketBook hardware

Coming Soon 🚧

Platform	Status
Kobo Devices	Native sync coming soon — use KOReader on Kobo hardware today
Mobile Apps	Android/iOS apps coming later

On the Roadmap 🔭

Platform	Status
Kindle Devices	Under consideration (no date yet)
Remarkable Tablet	Under consideration (no date yet)

---

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:

• KOReader Setup Guide - KOReader configuration (Kindle, Kobo, and PocketBook hardware)
• Kobo Setup Guide - Native Kobo sync (coming soon; use KOReader today)

Quick Overview

Registration Process (KOReader):

1. Install the Bookhoard plugin and enter your server URL in KOReader
2. Approve the pending registration on the Bookhoard Devices page (sidebar navigation)
3. That's it — sync starts automatically once approved

Device Management:

Devices page (sidebar navigation)

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

Devices page → select device → 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: Devices page (sidebar navigation)
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. Open the book's detail page and click Sync Progress, or go to the Conflicts page (/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. Sync less frequently

---

Best Practices

For Optimal Performance

✅ DO:

• Use checkpoint mode when on slow connections
• 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)
• On the go: Web browser on a phone (dedicated mobile apps coming later)

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:

Book detail → Sync Progress → 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:

Devices page → sync queue section

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:

Progress page (sidebar navigation), or the book's detail page

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. Increase sync interval - Fewer updates
3. 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: Reading data isn't exportable from the UI yet — it's accessible via the API.

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: Bookhoard's KOReader sync uses a dedicated plugin (server-side approval, device tokens) — no Calibre involvement required.

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.x (2026)

• ✅ Web sync support
• ✅ KOReader sync (progress, bookmarks, highlights, notes)
• ✅ Conflict resolution
• ✅ Offline queue
• ✅ Real-time WebSocket sync
• 🚧 Native Kobo sync (coming soon)
• 🚧 Mobile apps (coming later)

---

Last Updated: August 2026
Version: 1.0
License: GPL-3.0