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. Home server is often unreachable (residential NAT). Every read
  comes from Room. Every write lands in Room first, syncs later. No screen may
  block on network.
- Private. No public registration. Auth required for all data access.
- 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.
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.

## 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.