Readstreak

Your e-reader syncs to a small server you own, and you see everything on the web and in iPhone widgets. One server can serve a whole household, with a separate account for each reader.

What it does

• Today: time read today, this week, month and year, your streak, the last 30 days and a 26-week calendar, what you're reading now, and a highlight of the day.
• Books: covers (from Open Library), progress, time spent and days read per book.
• Send to e-reader: upload books on the Books tab, from a computer or a phone, and they land in an Inbox folder on the e-reader the next time it's online, like Send to Kindle. Books waiting to go out can be taken back; delivered ones are deleted from the server. On the e-reader, Tools → Get books sent from the web fetches them right away.
• Highlights: every highlight and note from KOReader, plus the stock Kindle reader's My Clippings.txt, grouped by book and chapter or by month, searchable by text, note, chapter, book or author (matches are marked), and narrowed with one Filter panel: type, source, book, date and grouping, shown as removable chips. One-word dictionary lookups are kept apart as Words. Export exactly what's shown, filters and search included, as an Excel spreadsheet.
• iPhone: an app that shows the site, and widgets for the Home Screen (today, current book, reading calendar) and the Lock Screen. Install it from TestFlight and enter your server's address. Exports open in the share sheet, to save to Files or send to another app.
• No manual syncing: highlights upload seconds after you make them, stats sync whenever Wi-Fi connects and every 30 minutes. Offline changes wait and go out later.
• Several readers: each person has their own account and sees only their own books, stats and highlights. Admins add people; everyone manages their own password, devices and sessions.

How it works

1. You read. KOReader's built-in statistics sync uploads statistics.sqlite3 whenever Wi-Fi connects and every 30 minutes; the highlight sync plugin uploads each highlight seconds after you make it. Offline changes wait and go out later.
2. Your server keeps it. server.py is a WebDAV folder per account plus the web app and API, all from the same files. Nothing else stores your data.
3. You look. The web app, the iPhone app and the widgets all read from your server. Books you send from the web wait in inbox/ until the e-reader downloads them into its Inbox folder.

Each part signs in its own way, so a lost e-reader never exposes your account password:

Who	Signs in with
🌐 Browser / iPhone app	username and account password, at /login (a session cookie)
📖 KOReader	username and a device password made on the account page
📱 iPhone widgets	a widget token the app gets for its phone when you sign in to it

What's in the repo:

Path	What it is
server.py	the server: WebDAV, web app and API. Python standard library only
auth.py	accounts, sessions and device passwords, in DATA_DIR/auth.sqlite3
index.html, account.html, admin.html	the web app, the account page and the admin page
koreader/highlightsync.koplugin	the KOReader plugin: uploads highlights, keeps stats syncing, fetches books sent from the web
ios/	the SwiftUI iPhone app and its WidgetKit widgets
scripts/	configure_koreader.py sets up an e-reader; demo_data.py makes the demo library

Install

Give INSTALL.md to a coding agent (or follow it yourself). It covers getting KOReader onto the device, deploying the server to Railway, adding people, configuring each device with scripts/configure_koreader.py, tidying books, and building the iPhone app.

Run it locally

scripts/demo_data.py ./demo-data
AUTH_PASSWORD=demo-password-123 DATA_DIR=./demo-data PORT=8080 python3 server.py
# open http://localhost:8080 and sign in as reader / demo-password-123

The first start turns AUTH_PASSWORD into the admin account reader. Add people from Account → Admin.

Configuration

Variable	Purpose
DATA_DIR	Where data lives, default /data; mount a persistent volume there
TZ_NAME	Default IANA time zone for "today" and streaks, default UTC; each account can override it
PORT	Listen port, default 8080
AUTH_PASSWORD	First start only: becomes the first admin's password (12+ characters)
AUTH_USER	First start only: the first admin's username, default reader

The AUTH_* variables are read only while the accounts table is empty. After that, accounts live in DATA_DIR/auth.sqlite3 and the variables can be removed.

Accounts

Admins manage people on the admin page (Account → Admin):

• Add a person: pick a username and time zone. They get a temporary password and must choose their own at first sign-in; until then they see only the account page.
• Reset password, disable (signs them out and stops their devices), enable, delete (keeps their reading data in DATA_DIR/deleted/), make admin / remove admin. There is always at least one admin, and nobody can disable or delete themselves.
• New e-reader password for someone, to set up their Kindle for them.

Everyone has an account page:

• Password: changing it signs out their other browsers and phones. E-readers and widgets keep working, since they use their own secrets.
• E-readers: device passwords for KOReader. Make one per device, revoke one if it's lost.
• iPhone widgets: one entry per phone, added when the Readstreak app signs in.
• Signed in: every browser and phone with a session; sign out any of them.

Where data lives:

What	Where
Accounts, sessions, devices	DATA_DIR/auth.sqlite3
The first account's reading data	DATA_DIR/dav
Everyone else's reading data	DATA_DIR/users/<name>/dav
Cover cache (shared)	DATA_DIR/covers
Deleted accounts' data	DATA_DIR/deleted/<name>-<time>

Security

• Account passwords are hashed with PBKDF2-SHA256 (600,000 iterations). Session cookies, device passwords and widget tokens are random and stored only as SHA-256 hashes, so a copy of auth.sqlite3 doesn't reveal any of them.
• The browser signs in at /login; sessions are HttpOnly, Secure, SameSite=Lax cookies kept for 180 days, listed on the account page and revocable one by one.
• Changing data needs a JSON request from the site itself: cross-site requests are refused.
• WebDAV uses Basic auth (KOReader's only option) with a device password; keep the server behind HTTPS. A device password can sync and read, but can't manage the account.
• Failed sign-ins are rate-limited per client, and slowed down for everyone when many fail at once. Sign-in takes the same time whether or not the username exists.
• Accounts can't see each other's data: WebDAV, the web app and widgets are scoped to the signed-in account, and WebDAV paths can't escape its folder.

Privacy

The server and the iPhone app have no analytics, ads or tracking, and the app talks only to the server you point it at. The server looks up book covers on Open Library by title and author. See PRIVACY.md.

License

MIT, see LICENSE.