[BW-IOS-00] Establish staged iOS foundation and selective KMP boundary #30

Open
opened 2026-09-18 08:47:07 +02:00 by alexander · 0 comments
Owner

Migrated from GitHub issue #121. Forgejo issue: #30. GitHub source content synchronized on 2026-09-19. Migrated issue references below use Forgejo numbers where an equivalent issue exists; historical references without a Forgejo counterpart remain explicit GitHub links.

Classification

Long-horizon planning/foundation issue. Not implementation-ready until Android playback correctness is stable.

Product intent

Create BookWave for iPhone slowly and safely, reusing portable correctness policy where it helps while keeping Apple UI, playback and system integrations native.

CarPlay and Live Activities are explicit target surfaces, not optional afterthoughts.

Selective Kotlin Multiplatform portable core/domain + native SwiftUI + native Apple media/system integrations.

Likely portable:

  • core IDs/value models;
  • result/error semantics;
  • completion rules;
  • resume-freshness policy;
  • local remembered-book policy;
  • progress/session reconciliation policy;
  • smart-download decision policy;
  • profile/authorization rules;
  • search/sorting;
  • clocks/time abstractions;
  • privacy/redaction policy models where practical.

Remain native on Apple:

  • SwiftUI/navigation;
  • AVFoundation/audio session;
  • Now Playing/remote commands;
  • CarPlay;
  • WidgetKit;
  • App Intents/Shortcuts;
  • ActivityKit/Live Activities;
  • background transfer/storage adapters;
  • Keychain;
  • Apple-specific lifecycle/background execution.

Stages

Stage 0 — KMP portability spike

Move/compile only a tiny pure-policy slice for JVM + iOS simulator and validate Swift interop. Android behavior must remain unchanged. If the shared boundary makes the architecture worse, fully native Swift remains acceptable.

Stage 1 — iOS shell/auth

Native SwiftUI app, Audiobookshelf sign-in, secure credentials, profile/account switching. No playback.

Stage 2 — read-only library

Books/authors/series/shelves/search/details/art/cached data.

Stage 3 — native Apple playback

Streaming, one-book timeline, chapters, seek, speed, background audio, lock-screen/Control Center, interruptions, Bluetooth controls and Now Playing. No clever cross-device reconciliation until the baseline player is stable.

Stage 4 — progress/session correctness

Apply the same behavioral contracts as Android: session ownership, acknowledged progress, realtime/REST evidence, intentional rewinds, local remembered identity, resume freshness and offline journal semantics.

Stage 5 — downloads/offline

Native Apple background/storage implementation. Preserve authorization/profile ownership and safe physical-copy semantics where applicable.

Stage 6 — Apple system integrations

App Intents, Shortcuts/Siri-facing actions, widgets and any justified Live Activity.

Stage 7 — CarPlay

Native CarPlay audio surface after playback is stable and entitlement has been obtained.

Stage 8 — parity/polish

Value-based parity rather than checklist parity.

Dependencies

Begin Stage 0 only after the Android contracts that are candidates for sharing are stable, especially GitHub PR #93 and #24 BW-PLAY-01.

Explicitly out of scope

  • No shared Compose UI requirement.
  • No wholesale conversion of Android modules to KMP.
  • No delaying Android features until iOS exists.
  • No mechanical port of Media3/WorkManager/Android Auto architecture to Apple frameworks.

Acceptance gate for Stage 0

  • same pure policy tests run on JVM and iOS target;
  • Swift can consume APIs without unreasonable wrapper churn;
  • Android module boundaries improve or remain unchanged;
  • the shared code represents domain meaning, not platform adapters.

Effort

Large overall, intentionally split into stages.

Risk

High if treated as a rewrite; Medium if each stage is independently shippable and selective.

  • CarPlay gets its own issue and depends on Stage 3+4 maturity and entitlement.
  • Live Activities get a separate candidate issue and should solve a distinct glanceable task rather than duplicate system Now Playing.
> Migrated from [GitHub issue #121](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/121). Forgejo issue: #30. GitHub source content synchronized on 2026-09-19. Migrated issue references below use Forgejo numbers where an equivalent issue exists; historical references without a Forgejo counterpart remain explicit GitHub links. ## Classification Long-horizon planning/foundation issue. Not implementation-ready until Android playback correctness is stable. ## Product intent Create BookWave for iPhone slowly and safely, reusing portable correctness policy where it helps while keeping Apple UI, playback and system integrations native. CarPlay and Live Activities are explicit target surfaces, not optional afterthoughts. ## Recommended architecture **Selective Kotlin Multiplatform portable core/domain + native SwiftUI + native Apple media/system integrations.** Likely portable: - core IDs/value models; - result/error semantics; - completion rules; - resume-freshness policy; - local remembered-book policy; - progress/session reconciliation policy; - smart-download decision policy; - profile/authorization rules; - search/sorting; - clocks/time abstractions; - privacy/redaction policy models where practical. Remain native on Apple: - SwiftUI/navigation; - AVFoundation/audio session; - Now Playing/remote commands; - CarPlay; - WidgetKit; - App Intents/Shortcuts; - ActivityKit/Live Activities; - background transfer/storage adapters; - Keychain; - Apple-specific lifecycle/background execution. ## Stages ### Stage 0 — KMP portability spike Move/compile only a tiny pure-policy slice for JVM + iOS simulator and validate Swift interop. Android behavior must remain unchanged. If the shared boundary makes the architecture worse, fully native Swift remains acceptable. ### Stage 1 — iOS shell/auth Native SwiftUI app, Audiobookshelf sign-in, secure credentials, profile/account switching. No playback. ### Stage 2 — read-only library Books/authors/series/shelves/search/details/art/cached data. ### Stage 3 — native Apple playback Streaming, one-book timeline, chapters, seek, speed, background audio, lock-screen/Control Center, interruptions, Bluetooth controls and Now Playing. No clever cross-device reconciliation until the baseline player is stable. ### Stage 4 — progress/session correctness Apply the same behavioral contracts as Android: session ownership, acknowledged progress, realtime/REST evidence, intentional rewinds, local remembered identity, resume freshness and offline journal semantics. ### Stage 5 — downloads/offline Native Apple background/storage implementation. Preserve authorization/profile ownership and safe physical-copy semantics where applicable. ### Stage 6 — Apple system integrations App Intents, Shortcuts/Siri-facing actions, widgets and any justified Live Activity. ### Stage 7 — CarPlay Native CarPlay audio surface after playback is stable and entitlement has been obtained. ### Stage 8 — parity/polish Value-based parity rather than checklist parity. ## Dependencies Begin Stage 0 only after the Android contracts that are candidates for sharing are stable, especially [GitHub PR #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/93) and #24 BW-PLAY-01. ## Explicitly out of scope - No shared Compose UI requirement. - No wholesale conversion of Android modules to KMP. - No delaying Android features until iOS exists. - No mechanical port of Media3/WorkManager/Android Auto architecture to Apple frameworks. ## Acceptance gate for Stage 0 - same pure policy tests run on JVM and iOS target; - Swift can consume APIs without unreasonable wrapper churn; - Android module boundaries improve or remain unchanged; - the shared code represents domain meaning, not platform adapters. ## Effort Large overall, intentionally split into stages. ## Risk High if treated as a rewrite; Medium if each stage is independently shippable and selective. ## Links / future children - CarPlay gets its own issue and depends on Stage 3+4 maturity and entitlement. - Live Activities get a separate candidate issue and should solve a distinct glanceable task rather than duplicate system Now Playing.
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
alexander/Audiobookshelf-Manager-Claude#30
No description provided.