John O'Keefe
3feb608d26
- sync-guide matching ladder was missing rung 8: Title only at 0.3 confidence, last-resort after title+author+size (book_matching.go priorities 1-8, file-path priority handled at the API layer). - library-browsing said the sort dropdown had 'more' options than it does: exactly five (Title A-Z/Z-A, Author A-Z, Date Added, Page Count). Sweep results, all verified against source: themes.md 24+13=37 exact (web/src/theme.ts union), reader-guide claims (corner zones, selection copy, comics annotations disabled - bookmarks only) present in web/src/reader/reader.ts, android-app.md strings (local-network permission, login error table) in bookhoard-app source, calibre dc:title/calibre:series parsing in media_scanner_calibre fixtures.
5.6 KiB
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 has the details |
Kindle and reMarkable are under consideration; KOReader already covers several of those devices today.
Getting a device into the circle
- Connect the device to your server (each guide above walks its own path)
- Approve the pending registration on the Devices page — the Android app registers itself on first login; KOReader asks from its plugin
- 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:
- Bookhoard UUID — 100% confidence
- OPF UUID — 95%
- SHA-256 hash — 90%
- OPF identifier — 85%
- ISBN / ASIN — 80%
- Title + Author + file size — 50%
- Title only — 30% (last resort, only tried when nothing else matched)
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 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 · KOReader · Kobo · Calibre import · and the filter rules that power matching-adjacent shelves like smart collections.