john-okeefe
b927ed9988
Document the planned native Android client (bookhoard-app): product vision, tech stack and rationale (Kotlin + Compose + Readium over hybrid/Flutter/KMP alternatives), module architecture, offline-first sync flow over the existing REST/WebSocket API, reader and comics/manga UX, iOS posture, distribution and licensing, and a five-milestone roadmap. The client is a thin, offline-first consumer of the server's existing device registration, universal progress, annotation, and conflict-resolution APIs — no server changes required.
141 lines
7.0 KiB
Markdown
141 lines
7.0 KiB
Markdown
# Android App — Design & Roadmap
|
|
|
|
This document describes the planned native Android client for Bookhoard: a thin, offline-first reading app that treats the Bookhoard server as its backend. The relationship is the same as the audiobookshelf app to an audiobookshelf server, or the Kindle app to Kindle cloud — the server owns the library, sync, and conflict resolution; the app is a dedicated, mobile-first reading frontend with its own UI, designed independently of the web interface.
|
|
|
|
**Status**: Planning / pre-development
|
|
**Companion repo**: `bookhoard-app` (separate repository, AGPL-3.0)
|
|
|
|
---
|
|
|
|
## 🎯 Product Vision
|
|
|
|
- An **amazing ereader** first and foremost — rendering polish, latency, and reading UX are the product
|
|
- **Mobile-first UI** designed from scratch for phones; not a wrapper around the web app
|
|
- **Thin client**: the server remains authoritative for all sync, book matching, and conflict resolution
|
|
- **v1 formats**: EPUB (ebooks) and CBZ (comics/manga); PDF comes nearly free via the reader toolkit
|
|
- **Android first**. iOS is a real roadmap item but unscheduled — likely contributor-driven
|
|
|
|
---
|
|
|
|
## 🛠 Tech Stack
|
|
|
|
| Concern | Choice |
|
|
| -------------- | ------------------------------------------------- |
|
|
| Language | Kotlin |
|
|
| UI | Jetpack Compose + Material 3 |
|
|
| Reader engine | [Readium Kotlin toolkit](https://github.com/readium/kotlin-toolkit) |
|
|
| Local database | Room |
|
|
| Networking | OkHttp / Retrofit + WebSocket |
|
|
| Background | WorkManager |
|
|
| Images | Coil |
|
|
| Settings | DataStore |
|
|
|
|
### Why native Android
|
|
|
|
- The quality bar is the Kindle app. Page-turn latency, text layout fidelity, PDF rendering (`PdfRenderer`), and comic/manga image pipelines are platform-level strengths — and they are the *hard* parts in a WebView, not the easy parts.
|
|
- Android-first removes the "share one codebase across two platforms simultaneously" constraint that motivates hybrid stacks.
|
|
- Solo, AI-assisted development compresses the cost of native (code volume), while native's failure modes (well-documented platform APIs) are far easier to debug — alone or with AI — than cross-framework bridge/plugin bugs.
|
|
- The target audience is the self-hosted community, best reached via GitHub Releases and F-Droid rather than app-store optimization.
|
|
|
|
### Alternatives considered
|
|
|
|
- **Capacitor / WebView shell** (the audiobookshelf-app model): excellent when a self-contained SPA already exists; a poor fit here. Bookhoard's web UI is server-rendered HTMX and cannot be packaged, comics rendering in a WebView caps the polish target, and deep offline support fights the shell.
|
|
- **Flutter**: strong middle ground, but no Readium port and a weaker EPUB/PDF plugin ecosystem than the native toolkits.
|
|
- **Kotlin Multiplatform**: only pays off with a committed near-term iOS effort. Revisit if iOS becomes active; until then it would constrain v1 for a hypothetical.
|
|
|
|
---
|
|
|
|
## 🏗 Architecture
|
|
|
|
Thin, offline-first client. The server API is the contract (see [API Reference](api/api-reference.md) and [WebSocket API](websocket-api.md)).
|
|
|
|
### Module layout
|
|
|
|
```
|
|
:app Compose UI, navigation, dependency injection
|
|
:core:domain Pure Kotlin — models, sync logic, use cases (no Android deps)
|
|
:core:data Room, Retrofit/OkHttp, downloads and file storage
|
|
:feature:reader Readium navigator integration and reading UI
|
|
```
|
|
|
|
Keeping `:core:domain` free of Android dependencies preserves optionality: a future iOS client, a KMP extraction, or a desktop client can reuse or port the domain logic without touching the UI.
|
|
|
|
### Offline-first sync flow
|
|
|
|
1. UI writes go to the local Room mirror **first** (never blocked on network)
|
|
2. A WorkManager queue replays changes to the existing REST endpoints (`/api/progress`, `/api/media-items/:id/notes`, `/highlights`, etc.)
|
|
3. Conflicts are resolved by the server's existing mechanisms — the client never invents its own merge logic
|
|
4. While online, a WebSocket connection receives realtime updates pushed by other devices (web reader, KOReader)
|
|
5. Books are downloaded to app storage for fully offline reading, with storage management UI
|
|
|
|
### Device registration & auth
|
|
|
|
- The app registers as a Bookhoard **device** using the existing QR-approval flow (`POST /api/devices/register` + web-based approval) — no passwords stored on the device
|
|
- JWT access/refresh handled by the existing auth endpoints
|
|
|
|
---
|
|
|
|
## 📖 Reader Engine
|
|
|
|
[Readium](https://github.com/readium/kotlin-toolkit) provides EPUB, PDF, and CBZ through one publication model and navigator — production-hardened by real reading apps. This avoids building and maintaining three renderers.
|
|
|
|
Planned reading features:
|
|
|
|
- Custom fonts (including user-loaded), adjustable margins and line height
|
|
- Themes including OLED true-black for battery
|
|
- Paginated and scroll modes; gesture and volume-key page turns
|
|
- Keep-screen-awake while reading
|
|
- Highlights, notes, and bookmarks synced via existing APIs (including deleted-annotation restore)
|
|
- Resume to exact position using EPUB CFI, consistent with universal sync
|
|
|
|
### Comics & manga UX
|
|
|
|
- RTL reading direction and double-page spreads with correct cover/single-page handling
|
|
- Per-book reading-mode overrides (a manga library can default to RTL)
|
|
- Zoom and pan; aggressive preloading of adjacent pages
|
|
- Webtoon / continuous vertical mode: post-v1
|
|
|
|
---
|
|
|
|
## 🍎 iOS Posture
|
|
|
|
iOS is a real roadmap item but not near-term. The strategy is **not** to pre-pay for it with KMP or a cross-platform framework. Instead:
|
|
|
|
- The documented REST/WebSocket API is the sharing mechanism — a future iOS client is a *new client over the same contract*, never a rewrite of shared logic
|
|
- A contributor-driven Swift/SwiftUI client is welcome; the server needs no changes to support it
|
|
|
|
---
|
|
|
|
## 📦 Distribution & Licensing
|
|
|
|
- **License**: AGPL-3.0, matching the Bookhoard server
|
|
- **Channels**: GitHub Releases and F-Droid; Play Store optional later
|
|
|
|
---
|
|
|
|
## 🚧 Milestones
|
|
|
|
1. **Scaffold** — app shell, auth + QR device pairing, library browsing, book downloads
|
|
2. **EPUB reading** — Readium integration, CFI progress sync, offline-first reading
|
|
3. **Annotations** — highlights/notes/bookmarks sync with offline queue
|
|
4. **Comics** — CBZ navigator with manga modes (RTL, spreads, zoom)
|
|
5. **Polish** — OLED themes, gestures, background sync, storage management
|
|
|
|
---
|
|
|
|
## 🔭 Post-v1 Ideas
|
|
|
|
- Webtoon / continuous vertical reading mode
|
|
- Home-screen widgets and app shortcuts ("continue reading")
|
|
- Text-to-speech
|
|
- OPDS feed consumption from other servers
|
|
|
|
---
|
|
|
|
## Related Documentation
|
|
|
|
- **[API Reference](api/api-reference.md)** - Complete REST API
|
|
- **[WebSocket API](websocket-api.md)** - Real-time sync events
|
|
- **[Sync Guide](../user/sync-guide.md)** - How universal sync works
|
|
- **[Devices API](api/devices/)** - Device registration and approval
|