# 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 Registration](#device-registration)
5. [Sync Features](#sync-features)
6. [Troubleshooting](#troubleshooting)
7. [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. **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