- TypeScript 63.6%
- Kotlin 33.1%
- HTML 2.2%
- JavaScript 0.7%
- Dockerfile 0.1%
- Other 0.2%
The web's four sizes, by its names and slugs (Small, Medium, Large, Extra-large; sm/md/lg/xl), on the grid only and remembered per screen per device: a control in the library's Sort sheet and one on the shelf screen's top bar. The size is a minimum tile width given to an adaptive grid, so the column count falls out of the room and the foldable keeps its wider tiles: 4, 3, 2, 1 across on a phone and 7, 5, 4, 3 on an open foldable. Medium is the default and is exactly what the grid was before, so nothing moves until someone picks. (The web's default is Large, but its scale starts from a desktop tile.) The width asked of the server for each size lives with the size and stays on the thumbnail ladder; the old library constants are gone. The shelf grid now widens its tiles on the open foldable the way the library's does, where it used to take the phone's floor. Also documents the theme generator and light/dark in docs/. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> |
||
|---|---|---|
| .claude | ||
| android | ||
| api | ||
| docs | ||
| scripts | ||
| web | ||
| .env.example | ||
| .gitignore | ||
| dedup-library.sql | ||
| docker-compose.dev.yml | ||
| docker-compose.yml | ||
| PLAN.md | ||
| README.md | ||
MyReading
A self-hosted reading tracker: a web app, an Android app with a built-in EPUB reader and audiobook player, and an API that keeps them in step. It watches folders of ebooks and audiobooks, records what you read and when, and works out what that adds up to.
Built for one reader on one home server. Everything stays on the network — there is no account to make, no service to sign into, and the only outbound requests are to look up a cover or a page count.
Contents
- What it does
- How it fits together
- Getting it running
- Working on it
- Repository layout
- Configuration
- Database changes
- Notifications
- Testing
- Conventions
What it does
Your library, both halves. Two folders are watched — ebooks and audiobooks — and scanned into a browsable library with covers, series, genres and narrators. A book owned in both formats is matched up, so its page knows about the recording and the recording knows about the file. Changes on disk are picked up automatically; there is no "rescan" button to remember.
Reading. The Android app has an EPUB reader with themes, fonts, scroll or paged flow, and text you can highlight in colour. Kindle-format books — MOBI, AZW3 — are converted to EPUB by the server the first time you open one, which takes a few tens of seconds once per book and nothing thereafter; that needs calibre in the API image, and without it those books simply have no Read button. Position syncs to the server, so the phone and the web agree on where you are. Audiobooks stream to a Media3 player with chapters and a resumable position.
Tracking. Sittings are recorded while you read rather than only when you close the book, and every date boundary follows your timezone rather than the server's. Progress, reading speed in words a minute, pages an hour, time left at your current pace, and a calendar of what you read on which day.
Checking in. Close a book and it asks three things about what you just read: what it is worth so far, how it felt — eight moods — and anything you want to note about that stretch. All optional, all one tap to skip.
What that buys is a record of a book as it actually went rather than one verdict at the end. The book's page charts the ratings each sitting earned and the running average they add up to, with your notes anchored to the pages they were about; and when you finally rate the finished book, it says how far that landed from where the book had been reading. Finishing something a star above how it was going is a real and quite common thing, and it is invisible if the only number you keep is the last one.
Planning. A monthly to-be-read pile and a long-term one. When a month turns over, anything you planned and didn't get to is offered back — carry it into this month, or let it go — and a recap lands in the notification centre saying how the month went.
Gamification. XP, levels, streaks that follow your daily goal, and around a hundred and forty achievements. Tap one and it tells you when you earned it and which book earned it — recovered from the order your reads finished in, not guessed at.
Soundtracks. Optional, Android only: with notification access granted, the app records what music was playing while you read, so a book remembers what you read it to.
How it fits together
| Service | What it is | Port |
|---|---|---|
api |
Fastify + Prisma + TypeScript | 3022 |
web |
React + Vite, served by nginx | 88 |
postgres |
PostgreSQL 16 | — |
redis |
Redis 7 — job queue | — |
ntfy |
Self-hosted push | 2586 |
The Android app talks to the API directly over the LAN. The web app is served
by nginx, which also proxies /api to the API container — so the browser only
ever needs port 88.
PLAN.md has the original architecture and data model in more detail, and
docs/ is the wiki — one page per subsystem, with the rules
each one holds to and why.
Getting it running
The server
The project is deployed with Docker Compose. From the repository root:
cp .env.example .env # then set POSTGRES_USER and POSTGRES_PASSWORD
chmod 600 .env
docker compose up -d --build
The Postgres login lives in .env, which is gitignored; compose refuses to
start without it. Pick a password with openssl rand -hex 32 — it is embedded
in the API's database URL, so it should need no escaping. Changing it later on
an existing database is more than an edit to .env: see
Deployment § the Postgres password.
The web app is then at http://<your-server>:88. Create your account there on
first visit.
Registration closes behind you. A server with no accounts always allows the first one, and after that nobody else can register unless you turn it on under Settings → Server → Access. It is enforced by the API, not merely hidden on the sign-in page.
Migrations run automatically when the API container starts — the production
image's command is prisma migrate deploy && node dist/index.js — so a deploy
that includes a schema change needs nothing extra.
Your library folders
docker-compose.yml mounts two host paths into the API container. Change these
to wherever your books actually live:
volumes:
- /mnt/content/Books:/app/library
- /mnt/content/AudioBooks:/app/audiobooks:ro
Audiobooks are mounted read-only on purpose — the scanner only ever reads them, and a bug should not be able to write to hundreds of gigabytes of audio.
Extracted covers go to a Docker volume rather than back into the library. Writing them beside the books put an image in every folder, and Android galleries build an album per folder containing images — so a library organised by series turned into an album per series on your phone.
The Android app
There is no Play Store build; it is sideloaded.
./android/build-apk.sh
That builds the profile variant — release performance with debug signing —
and installs it over ADB if a device is attached. --no-install builds only,
and --debug gives you a debuggable build when you need a stack trace that
hasn't been through R8.
On first launch the app asks for your server's address (http://192.168.1.x:3022)
and your login. Both are kept on the device.
Working on it
The API
cd api
npm install
npm run dev # tsx watch on src/index.ts
npm test # vitest
npx tsc --noEmit # typecheck
It needs Postgres and Redis. The simplest approach is to leave the compose
stack running and point DATABASE_URL and REDIS_URL at the published ports.
The web app
cd web
npm install
npm run dev # vite, proxies /api to localhost:3022
npm test
npm run build
API_PROXY_TARGET overrides where the dev server proxies to, if your API is
somewhere other than localhost:3022.
Android
cd android
./gradlew assembleProfile # build
./gradlew testProfileUnitTest # unit tests
./gradlew compileProfileKotlin # typecheck, roughly
local.properties needs an sdk.dir; it is machine-specific and untracked.
Prisma on NixOS
Prisma cannot fetch its engines on NixOS — binaries.prisma.sh publishes no
linux-nixos build, so prisma generate 404s. Without a generated client,
tsc reports dozens of phantom errors that look like real bugs and are not.
api/shell.nix pins the right engines by hash:
cd api
nix-shell # then: prisma generate, npm run dev
nix-shell --run 'npx tsc --noEmit' # or one-shot
It relies on programs.nix-ld.enable = true to run the stock glibc binaries.
If you bump prisma or @prisma/client, the engine commit and both hashes
in shell.nix have to change with it — the client verifies the engine's build
hash and refuses a mismatch. api/README.md has the detail.
Repository layout
api/
prisma/
schema.prisma the data model, heavily commented
migrations/ numbered, applied on container start
src/
routes/ one file per resource; HTTP shape only
services/ the rules, as pure functions where possible
gamification/ XP, streaks, achievements and their evidence
jobs/ BullMQ workers and periodic sweeps
plugins/ Fastify plugins: auth, prisma, redis, rate limiting
web/
src/
pages/ one per route
components/ shared UI; BookView is the big one
lib/ API client, keyboard bindings, formatting, types
android/
app/src/main/kotlin/com/myreading/app/
data/ Retrofit API, Room, repositories, preferences
ui/screens/ one package per screen, ViewModel beside it
service/ audio playback, the media watcher
navigation/ routes and the nav graph
build-apk.sh build and install in one step
PLAN.md the original architecture and data model
Configuration
Almost everything is configured in the app rather than by environment variable — the reader's timezone, daily goals, reminders, accent colour, keyboard shortcuts. What is left:
| Variable | Purpose |
|---|---|
POSTGRES_USER, POSTGRES_PASSWORD |
The Postgres login, in .env. Required by docker-compose.yml, which builds DATABASE_URL from them. |
DATABASE_URL |
Postgres connection string. Required. |
REDIS_URL |
Redis connection string. Required. |
PORT |
API port. Defaults to 3022. |
JWT_SECRET |
Generated on first boot if unset. Set it and the in-app "rotate key" button steps aside, since the variable wins. |
CORS_ORIGINS |
Other browser origins allowed to call the API, comma-separated. Unset means none; the web app is same-origin and Android doesn't use CORS. |
TRUST_PROXY |
Which hops may set X-Forwarded-For. Defaults to loopback and the container network — only change it if your proxy is elsewhere. |
LIBRARY_PATH |
Ebooks, inside the container. Defaults /app/library. |
AUDIOBOOKS_PATH |
Audiobooks. Defaults /app/audiobooks. |
COVERS_PATH |
Extracted covers. Defaults /app/covers. |
LIBRARY_WATCH |
Set to off to disable folder watching. |
.env.example is the starting point.
A note on TRUST_PROXY. docker-compose.yml publishes the API's port so
the Android app can reach it directly, which means a request can arrive at the
API from the network rather than from nginx. X-Forwarded-For is just a header,
so trusting it from anyone would let a caller claim any address — and the
login rate limit counts per address. The default trusts the container network
nginx speaks from and nobody else; TRUST_PROXY=true restores the old
trust-everyone behaviour, which is only safe if nothing but your proxy can
reach the port.
Everything stored in the database is edited under Settings → Server, including whether anyone may register — see Getting it running.
Database changes
Migrations are numbered directories under api/prisma/migrations and are
applied with prisma migrate deploy when the API starts.
The number is four digits, and it has to be. Prisma applies pending
migrations in lexicographic order of directory name, not numeric order. They
were once named 0_init, 1_…, 24_…, under which "10" sorts before
"1_" and "24" before "5" — so a database with no history ran
24_tbr_entries at position 17 and 5_tbr_month, which adds the columns 24
reads, at position 38. A fresh docker compose up died at migration 24, and had
since the day migration 10 was added. Existing servers never noticed, because
each migration was applied when it was the newest and so ran in the order it
was written.
To add one:
cd api
nix-shell # on NixOS
npx prisma migrate dev --name what_it_does
Prisma names the new directory with a timestamp. Rename it to the next
four-digit number — 0042_what_it_does — before committing, which is the
convention the rest of the history follows.
Write the schema comment as you go. The schema is the most-read file in the
project and its /// comments explain why a column exists, which is the part
that cannot be recovered later.
prisma/renumber-migrations.sql runs ahead of migrate deploy on every boot
and brought already-deployed databases over to the padded names. It is a no-op
now and can be deleted once nothing is running the old history — see the file
for what it did and why renaming the directories needed it.
Notifications
Reminders and alerts are delivered by ntfy, self-hosted in the compose stack so nothing leaves the network. The API publishes with a plain HTTP POST — no SDK, no account.
Subscribe the ntfy app on your phone to http://<your-server>:2586/<topic>,
then set the same topic in Settings. Access is left open because it only
listens on the LAN and the topic name is what keeps it private — treat it like
a password. api/README.md covers locking it down properly.
The in-app notification centre is separate and needs no setup: finished-book prompts, achievements and monthly recaps land there, and settling one anywhere settles it everywhere.
Testing
cd api && npm test # ~1,660 tests
cd web && npm test # ~410
cd android && ./gradlew testProfileUnitTest
The API tests are the substantial ones. They avoid a database by keeping the rules in pure functions over plain data — the achievement rules take a snapshot of a reader, the streak takes a list of days, the cover URL takes two records — so a rule can be handed a reader who has done the thing and asked.
Nothing boots Fastify in tests, which is a real gap: route wiring is verified by reading rather than by running, and that is where a 502 once got through.
Conventions
A few things this codebase is opinionated about, learned mostly the hard way:
One rule, one place. A rule implemented twice will be wrong in one of them.
rereading, isAudiobook and the TBR piles are computed server-side rather
than by each client; the streak is computed by one function shared between the
writer and the dashboard. Where two languages make sharing impossible — date
formatting between Kotlin and TypeScript — the same boundary cases are asserted
on both sides, and the tests say so.
Comments explain why, not what. The signature says what it does. The comment is for the constraint that isn't visible: the bug it closes, the alternative that was tried, the reason the obvious version is wrong.
Never say something you cannot support. Achievement evidence returns nothing rather than a plausible guess. A cover lookup rejects a match it cannot verify. A missing figure shows an em dash, not a zero.
Never make a person wait on a third party. Covers are fetched once and served locally; a page that needs an outside host fetches in the background and falls back immediately. A save is never held up by something out of our control.
Note: I use Claude extensively with this project to control git, handle code I do not know, and organize features. My main contribution is the design elements, the actual functionality is, as the haters would say, vibe coded. If that offends you, don't use this project