bookhoard/docs/user/sync-guide.md

# 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 Setup](#device-setup)
5. [Using Sync Features](#using-sync-features)
6. [Book Matching](#book-matching)
7. [Managing Conflicts](#managing-conflicts)
8. [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 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](#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](devices/koreader-setup.md)** - KOReader configuration (Kindle, Kobo, and PocketBook hardware)
- **[Kobo Setup Guide](devices/kobo-setup.md)** - 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**: AGPL-3.0