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, 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](#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](devices/kobo-setup.md)** - Kobo e-reader configuration
- **[KOReader Setup Guide](devices/koreader-setup.md)** - 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