John O'Keefe
12aab156f6
sync-guide.md was 591 lines with good implementation-derived bones (matching confidence table, universal locations, conflict flow) wrapped around a stale device story: Android 'coming later' (the app exists and self-registers), a deleted queue UI, invented UI (color status badges, Auto-Resolve Future, Priority Sync buttons), placeholder support links, an HTTPS-1.3 overclaim on LAN setups that are plain HTTP by design, and a changelog promising the future. Rebuilt to ~140 lines, every claim grounded: device table matches reality (web/Android/KOReader supported, Kobo native server-complete with rollout pending), resolution strategies as the API actually defines them (device / server / highest_progress), offline queuing honestly scoped (Android queues; server holds per-device queue; no dedicated queue UI today), reading history on Progress page, RLS-era privacy wording, device limit 10 default admin-settable. Reader Sync Progress button verified. calibre-integration.md: mostly current (sidecar-first model, Dublin Core tables, Write-to-file section all kept); fixed the user-hostile 'POST /api/scanner/scan' instructions to point at the admin scan controls, and dropped the yourusername placeholder repo links.
135 lines
5.5 KiB
Markdown
135 lines
5.5 KiB
Markdown
# Universal Sync — how your devices stay in step
|
|
|
|
Sync is the promise that makes Bookhoard more than a web page: read on
|
|
whatever is in your hands, and every other device catches up. One server
|
|
holds the truth for each book — your position, bookmarks, highlights, and
|
|
notes — and every registered device pushes and pulls against it.
|
|
|
|
## Supported devices today
|
|
|
|
| Platform | Status | How it syncs |
|
|
| --- | --- | --- |
|
|
| **Web browser** | ✅ Fully supported | Live, as you read — the reader saves position and annotations continuously |
|
|
| **Android app** | ✅ Fully supported | The native client: progress, highlights, bookmarks, notes; reads offline and queues changes until you are back online |
|
|
| **KOReader** (Kindle, Kobo, PocketBook) | ✅ Fully supported | The Bookhoard KOReader plugin, over Wi-Fi |
|
|
| **Kobo, stock firmware** | 🚧 Server support complete | The native Kobo protocol is implemented and documented server-side; device-side enablement is the remaining piece — [Kobo Setup](devices/kobo-setup.md) has the details |
|
|
|
|
Kindle and reMarkable are under consideration; KOReader already covers
|
|
several of those devices today.
|
|
|
|
## Getting a device into the circle
|
|
|
|
1. Connect the device to your server (each guide above walks its own path)
|
|
2. Approve the pending registration on the **Devices** page — the Android
|
|
app registers itself on first login; KOReader asks from its plugin
|
|
3. Done. Sync starts as soon as a device is approved
|
|
|
|
The **Devices** page is mission control: see every registered device and
|
|
when it was last seen, remove a device (revoking its access instantly), and
|
|
work through **unlinked books** — device files that could not be matched to
|
|
a library book yet.
|
|
|
|
## Book matching
|
|
|
|
When a device reports a book, Bookhoard tries to match it to your library
|
|
by fingerprint, strongest first:
|
|
|
|
1. **Bookhoard UUID** — 100% confidence
|
|
2. **OPF UUID** — 95%
|
|
3. **SHA-256 hash** — 90%
|
|
4. **OPF identifier** — 85%
|
|
5. **ISBN / ASIN** — 80%
|
|
6. **Title + Author + file size** — 50%
|
|
|
|
Books that match automatically never bother you. The ones that can't
|
|
(side-loaded files, converted formats like EPUB → KEPUB, mismatched
|
|
metadata) land in the device's **unlinked books** list, where you can:
|
|
|
|
- **Auto-link** everything above a confidence threshold
|
|
- Review **suggestions** first, then link
|
|
- **Link by hand** — pick the right library book yourself
|
|
|
|
## What syncs
|
|
|
|
**Reading progress** — page, percentage, chapter position, EPUB CFI, last
|
|
read time. EPUBs sync by percentage and CFI, PDFs and comics by page, so
|
|
the same book lines up on devices with different page counts.
|
|
|
|
**Highlights and notes** — the highlighted text, your note, its color, and
|
|
where it sits. Locations are stored in several forms at once (page, EPUB
|
|
CFI, percentage, character offset), which is why a highlight made on your
|
|
phone lands in the right place on an e-reader with different pagination.
|
|
|
|
**Bookmarks** — location, title, and when you made them.
|
|
|
|
Everything above is per-user and private: your devices see your data
|
|
because you approved them, other users see theirs, and revoking a device
|
|
ends its access on the spot.
|
|
|
|
## Conflicts
|
|
|
|
If the same book is read on two devices close together, Bookhoard does not
|
|
silently pick a winner — it records a **sync conflict** and shows it to
|
|
you:
|
|
|
|
- The book's detail page grows a **Sync Progress** button (with a
|
|
"Progress conflict detected" notice)
|
|
- The **Conflicts** page (`/conflicts`) lists everything unresolved
|
|
|
|
Resolving means choosing a strategy: keep one side's progress, keep the
|
|
server's current value, or let the **furthest progress win**. Until you
|
|
resolve, the conflict stays listed — nothing is lost, it just waits for
|
|
your call.
|
|
|
|
## Offline reading
|
|
|
|
Devices keep working without the server. The Android app reads fully
|
|
offline and queues your changes, draining the queue when you reconnect.
|
|
E-readers push their progress on the next connection. The server holds a
|
|
per-device queue for inbound work and retries failures automatically; if
|
|
items pile up (a device offline for weeks), an admin can retry or clear a
|
|
device's queue from the server side.
|
|
|
|
## Reading history
|
|
|
|
Every reading session is logged — when, how long, on which device — and
|
|
feeds your [dashboard](dashboard.md) and stats. Your history is visible on
|
|
the **Progress** page and on each book's detail page, and it is yours
|
|
alone.
|
|
|
|
## Troubleshooting
|
|
|
|
**Progress not updating**
|
|
Check the device is still on the **Devices** page and was approved; check
|
|
the server URL in the device's settings; confirm the device can reach the
|
|
server (open the server URL in the device's browser as a test).
|
|
|
|
**"Device not found"**
|
|
The device was removed or its token revoked — register it again and
|
|
approve it.
|
|
|
|
**A conflict keeps coming back**
|
|
Two devices are genuinely fighting over the same book. Decide which device
|
|
is the reader for that book, resolve with a strategy above, and avoid
|
|
simultaneous reading of the same title.
|
|
|
|
**High battery or data use**
|
|
That is the cost of continuous sync on a chatty device; e-reader plugins
|
|
let you space out their sync checks from the plugin's own settings.
|
|
|
|
## Device limits
|
|
|
|
Each account has a device limit — **10 by default**, and administrators can
|
|
raise or lower it per user. Removing a device you no longer use frees a
|
|
slot.
|
|
|
|
---
|
|
|
|
More detail on any device lives in its guide:
|
|
[Android](devices/android-app.md) ·
|
|
[KOReader](devices/koreader-setup.md) ·
|
|
[Kobo](devices/kobo-setup.md) ·
|
|
[Calibre import](calibre-integration.md) ·
|
|
and the [filter rules](filters/index.md) that power matching-adjacent
|
|
shelves like [smart collections](collections.md).
|