bookshelf/docs/SPEC.md

Bookshelf — authoritative spec

Two-person shared home library. Android app + self-hosted PocketBase. ALL workers must follow this exactly. Do not invent alternative names.

Non-negotiables

• Offline-first. The server is often slow or unreachable. Every read comes from Room. Every write lands in Room first, syncs later. No screen may block on network. (The original reason was residential NAT; the server currently runs on a sprite that suspends when idle and wakes on request, so the same rule holds for a different reason. The requirement does not depend on which.)
• Private. No public registration. Auth required for all data access. As of 2026-09-12 the server is INTERNET-EXPOSED, so these rules are the only thing protecting the library — not defence-in-depth behind a home NAT.
• Server URL is NOT hardcoded; user enters it on first run.

Repo layout

~/bookshelf/ server/ PocketBase binary(gitignored), pb_migrations/, setup-schema.sh, deploy/ app/ Android Gradle project docs/ this spec

Android

• applicationId/namespace: org.modg.bookshelf
• minSdk 26, compileSdk 37, targetSdk 37, JDK 21, Kotlin, Jetpack Compose, Material 3
• SDK at ~/toolchain/android-sdk ; JDK at ~/toolchain/jdk21
• DI: manual AppContainer held by Application. NO Hilt/kapt. Room uses KSP.
• Libs: Compose BOM, room(+ksp), retrofit2 + kotlinx-serialization converter, okhttp logging, coil3 compose, camerax(core/camera2/lifecycle/view), com.google.mlkit:barcode-scanning, androidx.work runtime-ktx, datastore-preferences, navigation-compose, lifecycle-viewmodel-compose, accompanist-permissions (or manual)

Package structure (org.modg.bookshelf.*)

data.local Room: entities, daos, BookshelfDatabase, Converters data.remote PocketBaseApi (retrofit), dtos, PbAuthInterceptor data.metadata OpenLibrary + GoogleBooks lookup data.repo BookRepository, LocationRepository, SyncEngine, AuthRepository data.prefs SettingsStore (DataStore) ui.theme Color/Type/Theme ui.library, ui.detail, ui.scan, ui.locations, ui.settings, ui.setup ui.nav BookshelfNavHost

Data model — Room mirrors PocketBase 1:1

IDs: 15-char lowercase alnum, GENERATED CLIENT-SIDE for new records (PocketBase accepts client-supplied ids on create). Never remap ids after push.

BookEntity(id PK, title, subtitle, authorsJson, isbn13, isbn10, publisher, publishedDate, pageCount:Int?, description, coverUrl, coverSourceUrl, shelfId:String?, notes, addedBy, deleted:Boolean, createdAt:Long, updatedAt:Long, syncState:SyncState, localCoverPath:String?) BookcaseEntity(id PK, name, note, position:Int, deleted, createdAt, updatedAt, syncState) ShelfEntity(id PK, bookcaseId, label, position:Int, deleted, createdAt, updatedAt, syncState)

enum SyncState { SYNCED, PENDING_CREATE, PENDING_UPDATE, PENDING_DELETE }

All queries filter deleted = 0. Deletion is ALWAYS soft (tombstone) so sync can propagate it and nothing is silently lost from a shared library.

PocketBase schema (collections)

bookcases: name(text,req), note(text), position(number), deleted(bool) shelves: bookcase(relation->bookcases,req,maxSelect 1), label(text,req), position(number), deleted(bool) books: title(text,req), subtitle(text), authors(json), isbn13(text), isbn10(text), publisher(text), published_date(text), page_count(number), description(text), cover(file,maxSelect 1,image mimes,thumbs 100x150+300x450), cover_source_url(text), shelf(relation->shelves,maxSelect 1), notes(text), added_by(relation->users,maxSelect 1), deleted(bool) All three get autodate created/updated. Indexes: books(isbn13), books(updated), shelves(updated), bookcases(updated).

API rules — all of list/view/create/update/delete on the three collections: "@request.auth.id != """ users collection: createRule = null (SUPERUSER ONLY — this is what keeps the world out), listRule/viewRule = "@request.auth.id != """, updateRule = "id = @request.auth.id", deleteRule = null. NOTE: rule "" means PUBLIC in PocketBase; null means superuser-only. Do not confuse.

Sync design (SyncEngine)

Pull: GET /api/collections/{c}/records?filter=(updated>'{cursor}')&sort=updated &perPage=200&page=N — paginate to exhaustion. Cursor per collection in DataStore, stored as PB UTC string. Include tombstones. Push: records where syncState != SYNCED. PENDING_CREATE -> POST (with our id), PENDING_UPDATE -> PATCH, PENDING_DELETE -> PATCH {deleted:true}. On 404 for update/delete: drop local record. On 409/duplicate id: switch to PATCH. Auth: EVERY sync starts with POST /api/collections/users/auth-refresh and stores the new token, BEFORE any push or pull. 401/403 (from refresh or any later call) -> clear the token only (keep URL + email), stop, report AuthExpired: the UI says "sign in again" and routes to setup, pre-filled. Offline -> ordinary failure, token kept. WHY: PocketBase does not reject an expired token, it treats the request as anonymous, and the rules then 404 on records that exist — so the 404 rule above is only safe on a freshly-proven token (2026-09-17: five books hard-deleted locally this way). User tokens last 180 days server-side (migration 1789608448). Sign-in clears all pull cursors, so every fresh session reconciles fully. Order: push THEN pull (so our writes come back canonical). Conflict: last-write-wins on updated. Document this in README; do not build anything cleverer. Covers: on save, app downloads cover from metadata source and multipart-uploads it to the book's cover file field, so covers survive upstream URL rot. If offline, store localCoverPath and upload on next sync. Trigger: app start, manual pull-to-refresh, WorkManager periodic (~6h, network-constrained). Never let sync failure surface as a crash or a blocking dialog — a quiet status line only.

Book metadata lookup

Primary Open Library: https://openlibrary.org/api/books?bibkeys=ISBN:{isbn}&format=json&jscmd=data Fallback Google Books: https://www.googleapis.com/books/v1/volumes?q=isbn:{isbn} (no key) Cover: https://covers.openlibrary.org/b/isbn/{isbn}-L.jpg else GB imageLinks (force https, zoom=2) Merge: prefer whichever has a title; fill blanks from the other. Cover URL comes from a source that REPORTS one. Never synthesize the by-ISBN cover URL as if it were evidence: for an edition with no art that endpoint returns 200 + a 43-byte 1x1 transparent GIF, which loads "successfully" and paints nothing. As a last resort it may be used only with ?default=false, which makes a miss a 404.

Lookup outcome is THREE-WAY, never a bare null. A source that could not be reached must never be reported to the user as a book that does not exist: Found(metadata) - at least one source returned a record NotFound - EVERY source answered authoritatively and none had it Unavailable - no source could be reached (non-2xx, timeout, transport error) and none of the reachable ones had it UI: Found -> the save sheet. NotFound -> manual entry pre-filled with the scanned ISBN. Unavailable -> a retry affordance, with manual entry as the escape hatch; it must NOT claim the book is unknown.

Barcode scanning

CameraX Preview + ImageAnalysis -> ML Kit BarcodeScanning (EAN_13, EAN_8, UPC_A). Validate ISBN-13 checksum before lookup; ignore non-book barcodes. Debounce repeats. A rejected barcode is NOT silent: the camera screen must say a code was read and was not a book ISBN, or the user cannot tell a non-book barcode from a dead camera. Throttle that message — a non-book barcode sits in frame emitting continuously. Continuous mode: after a save, stay on camera for the next book (shelving a box of books is the real use case). Show a running "added this session" count. Handle: camera permission denial, torch toggle, and a manual-ISBN-entry escape hatch.

Design language — "feels like books"

Warm paper, dark mahogany, gold + silver metallics. Restrained, not skeuomorphic. Light: paper #F5EDE0, paperAlt #EDE3D2, ink #2B211A, inkSoft #5A4A3D, mahogany #5C2E23, mahoganyDeep #3E1E17, gold #C0932F, goldSoft #D9B45B, silver #9CA3AF, silverSoft #C7CCD1 Dark: ground #1C1411, surface #241A15, paperText #E8DCC8, mahogany #7A3E2F, gold #D9B45B, silver #C7CCD1 Type: serif display (Literata, OFL, bundle the TTF) for titles/headers; system sans for body/UI. Generous line-height. Motifs: subtle spine/edge treatments, thin gold hairline rules, gentle paper-grain on large surfaces. Covers are the hero — let them carry the color. Both light and dark themes required. Dynamic color OFF (it would fight the palette).

Screens

setup First run: server URL (+ https scheme validation, trailing-slash strip, reachability probe), email, password. Clear errors for wrong URL vs bad creds. library Cover grid (2-3 col adaptive). Search title/author/ISBN. Filter by bookcase/shelf. Sort title/author/added. Empty state invites first scan. FAB -> scan. Sync status line. detail Big cover, title/subtitle/authors/publisher/year/pages/ISBN, description (collapsible), notes (editable), location picker, edit, soft-delete w/ undo. scan Camera + reticle; on hit -> bottom sheet w/ fetched book + shelf picker + Save / Skip. Duplicate-ISBN warning if already owned. locations Bookcases -> shelves tree. CRUD + reorder. Book counts per shelf. Tap a shelf -> library filtered to it. "Move books" bulk action. settings Server, account, sign out, manual sync + last-sync time, book/cover counts. Session expired -> "sign in again" + Sign in button instead of Sync now.

Quality bar

• No emulator on this box (no KVM). Verify via: ./gradlew assembleDebug, JVM unit tests, and Paparazzi screenshot rendering.
• Unit-test the real logic: ISBN checksum, metadata merge, sync conflict resolution, DAO queries (Robolectric). Do not write assertion-free tests.
• App must compile and run with NO server configured (setup screen) and must not crash when the server is unreachable.