From 801b4843cf54998c7820a553dae81acd325d0fde Mon Sep 17 00:00:00 2001 From: Sarah Wolff Date: Thu, 9 Jul 2026 14:24:01 -0400 Subject: [PATCH] docs(icloud): define sync architecture --- docs/adr/0002-cloudkit-sync-implementation.md | 223 ++++++++++++++++++ 1 file changed, 223 insertions(+) create mode 100644 docs/adr/0002-cloudkit-sync-implementation.md diff --git a/docs/adr/0002-cloudkit-sync-implementation.md b/docs/adr/0002-cloudkit-sync-implementation.md new file mode 100644 index 0000000..3e0e593 --- /dev/null +++ b/docs/adr/0002-cloudkit-sync-implementation.md @@ -0,0 +1,223 @@ +# CloudKit sync implementation + +Status: accepted + +## Context + +ADR 0001 chooses private iCloud sync for the Shared Library and per-profile +Reading State. Piperly currently keeps EPUB files and covers in local Documents +folders and encodes model arrays in `UserDefaults`. The app must stay fully +usable offline and must not require a Piperly account or expose child-adjacent +data outside the family's private iCloud database. + +The deployment target is iPadOS 17, so Piperly can use `CKSyncEngine`. Apple +recommends it when an app needs control over an existing local model while the +system schedules private-database fetches and sends. `CKAsset` is intended for +external files attached to records and fits EPUB and cover transfer. + +SwiftData with CloudKit is not selected because adopting a new persistent +object graph would make this change much larger, while still leaving book-file +lifecycle work outside the model store. iCloud Documents is not selected +because Piperly also needs structured records, explicit conflict behavior, and +parent-facing sync state. Direct `CKDatabase` operations are not selected +because Piperly would have to own change tokens, scheduling, notifications, +and retry behavior that `CKSyncEngine` already provides. + +## Decision + +Piperly will use one custom record zone in the user's private CloudKit database, +managed by `CKSyncEngine`. The on-device store remains the source used by the UI +and reader. CloudKit is a replicated transport, not a live network dependency. +Every local change is saved locally first and added to a durable pending-change +queue. Sync can stop, retry, or be unavailable without blocking reading. + +Sync is off by default until a parent enables it. The active profile selection +is device-local; profiles and their Reading State sync, but which profile is +currently selected does not. + +### Container and zone + +- Container: `iCloud.com.piperly.app`. +- Database: private database only. +- Zone: `PiperlyLibrary`. +- The app needs the iCloud/CloudKit and remote-notification capabilities. +- The engine state and pending changes are encoded in the local application + support directory, separately from user-visible model data. +- Account changes invalidate engine state, stop sends, and require a fresh + fetch after the parent confirms the currently signed-in account. + +The container identifier must be created for team `7CNK4YPCQX`, attached to the +app identifier, tested in the development environment, and promoted to +production before TestFlight or App Store builds. + +### Record schema + +Record names are deterministic and never contain a nickname, title, saved word, +or other user content. + +| Record type | Record name | Important fields | +| --- | --- | --- | +| `Book` | lowercase EPUB SHA-256 | local UUID, title, author, original extension, cover availability, modified date, EPUB asset, optional cover asset | +| `ReaderProfile` | profile UUID | nickname, avatar symbol, color, created date, modified date | +| `ReaderPreferences` | `preferences-` | profile UUID, voice identifier, speech rate, font size, reader theme, voice-setup completion, modified date | +| `ReadingState` | `reading--` | profile UUID, book hash, progression, locator JSON, modified date | +| `Bookmark` | bookmark UUID | profile UUID, book hash, locator JSON, title, progression, sticker, created date, modified date | +| `SavedWord` | saved-word UUID | profile UUID, book hash, canonical word, display word, book title snapshot, tap count, saved date, last-tapped date, modified date | + +Book-linked cloud records use the EPUB hash, not the local Book UUID. The Book +record may carry the local UUID so a downloaded replica can preserve it, but +the hash is the cross-device join key and deduplication key. + +Record fields are additive after production deployment. Renaming or deleting a +record type or field requires a new field and a compatibility period. + +### Local sync boundary + +`BookStore` will not call CloudKit directly. It will send typed local changes to +a `LibrarySyncing` interface and apply typed remote changes returned by that +interface. Production uses `CloudKitLibrarySync`; tests use an in-memory fake. + +The sync layer owns: + +- encoding models to and from `CKRecord`; +- durable `CKSyncEngine.State.Serialization` data; +- durable pending record saves and deletions; +- account and engine status; +- asset staging and local availability; +- mapping CloudKit errors to small user-facing states. + +The local persistence layer owns model arrays and file URLs. A remote batch is +applied atomically from the UI's point of view, then published on the main actor. +Remote application must not enqueue the same records as new local changes. + +### Send and fetch lifecycle + +1. A local mutation is written to disk. +2. Its deterministic record ID is added to the pending-save queue, or to the + pending-delete queue for deletion. +3. The sync engine is told that pending work exists. +4. When the engine requests changes, the sync layer supplies current records + and staged assets for those IDs. +5. Successful sends remove pending entries. Retryable failures remain queued + with backoff. Permanent validation failures become a visible blocked state. +6. Fetched changes and deletions are decoded, validated, and applied locally. +7. Engine state is persisted after every state update. + +Partial failures are handled per record. `networkUnavailable`, `networkFailure`, +`serviceUnavailable`, `requestRateLimited`, and `zoneBusy` remain retryable. +Account absence, restricted accounts, quota exhaustion, asset-file loss, and +schema/permission errors are surfaced distinctly. + +### Conflict rules + +- **Book metadata:** one Book per content hash. Non-empty title and author from + the record with the newest modified date win. Assets are immutable for a + given hash; differing bytes are treated as corruption, not a normal conflict. +- **Reader Profile:** newest modified date wins for nickname, avatar, and color. + Deletion wins over an older edit. +- **Reader Preferences:** field set from the newest modified date wins. +- **Reading State:** highest `modifiedAt` wins. A locator and progression are + written together so they cannot come from different versions. +- **Bookmark:** records are independent. Same UUID uses newest modified date. +- **Saved Word:** same UUID uses newest display metadata, maximum tap count, the + earliest saved date, and the latest last-tapped date. + +All records retain the CloudKit system fields needed for optimistic saves. +Server-record-changed errors are merged by these rules and retried once through +the normal pending queue. + +### Deletion and tombstones + +Local deletion immediately hides the item, removes or quarantines local files, +and enqueues the record deletion. CloudKit deletion is the durable tombstone. +Remote deletions cascade locally: + +- deleting a Book deletes its local EPUB, cover, Reading States, Bookmarks, and + Saved Words for that book; +- deleting a Reader Profile deletes its Preferences and profile-scoped Reading + States, Bookmarks, and Saved Words; +- the final Reader Profile cannot be deleted locally. + +If a delete cannot be sent, its tombstone remains queued so a later fetch does +not resurrect locally deleted data. A newer explicit re-import of the same EPUB +can recreate the Book record after the deletion has reached the server. + +### EPUB and cover assets + +EPUBs and covers are `CKAsset` fields on the Book record. Uploads use immutable +staging copies so the file cannot change while CloudKit reads it. Downloaded +assets arrive in a temporary staging location and are verified before an atomic +move into Piperly's managed library. + +Asset state is device-local: + +- `local`: verified file is ready; +- `uploading` or `downloading`: progress may be shown when available; +- `remoteOnly`: metadata exists but no verified local file exists; +- `retryableFailure`: parent can retry and the engine can back off; +- `unavailable`: account, quota, permission, or corrupt-file problem. + +The SHA-256 of every downloaded EPUB must equal the Book record name before it +becomes readable. Covers are derived data and may be downloaded or regenerated. +Eviction removes only the local asset and keeps metadata. Deleting removes both +the record and local assets. + +### Privacy and parent controls + +Only the private database is used. No CloudKit user discovery or sharing API is +used. The app stores no birthdate, full name, photo, email address, or Apple ID. +Parent-facing Settings explains that book titles, EPUB files, saved words, and +Reading State use the family's private iCloud storage and count against their +iCloud quota. + +The parent gate protects enable, disable, retry/reset, and destructive sync +actions. Normal reading and profile switching remain child-accessible. Turning +sync off stops network work but does not delete local data. Cloud deletion is a +separate confirmed action. + +### Test strategy + +CloudKit-dependent code is behind interfaces for the container/database, +engine events, state store, clock, and asset staging. Unit tests cover record +round trips, deterministic IDs, pending queue persistence, retry classification, +conflict merges, deletion cascades, hash verification, account changes, and the +rule that applying remote changes does not re-enqueue them. + +Simulator tests use fakes and do not claim end-to-end CloudKit coverage. Before +release, test two physical iPads on the same iCloud account for import, offline +read/edit, convergence, duplicate import, profile isolation, conflict, delete, +evict/redownload, account sign-out/in, quota/account errors, and app relaunch +during upload/download. Observe CloudKit and app logs; push notifications are an +optimization and must not be the only way changes are fetched. + +## Delivery stack + +Each PR is based on the branch immediately before it. + +1. `docs(icloud): define sync architecture` — this ADR and setup contract. +2. `feat(profiles): scope reader preferences` — profile-level voice, theme, + font, rate, setup state, validation, and tests. +3. `feat(library): add stable book identity` — SHA-256 identity, deterministic + storage, duplicate prevention, and tests. +4. `feat(icloud): add private sync engine` — capabilities, zone, engine state, + pending queues, record codecs, account/error states, fakes, and tests. +5. `feat(icloud): sync book assets` — EPUB/cover asset lifecycle, verification, + availability, progress, retry, eviction, deletion, conflicts, and tests. +6. `feat(settings): add iCloud controls` — parent controls and status, recovery + UI, privacy documentation, schema promotion, and two-device checklist. + +## Consequences + +The app keeps working when iCloud is slow or unavailable, and CloudKit-specific +code stays outside reading UI and core models. The cost is an explicit local +change queue, merge rules, and a physical-device test matrix. Development builds +can compile and test with fakes before the Apple container is configured, but +real sync cannot be declared complete until the container, production schema, +entitlements, and two-device tests are verified. + +## References + +- [Deciding whether CloudKit is right for your app](https://developer.apple.com/documentation/cloudkit/deciding-whether-cloudkit-is-right-for-your-app) +- [CloudKit](https://developer.apple.com/documentation/cloudkit/) +- [CKAsset](https://developer.apple.com/documentation/cloudkit/ckasset) +- [Designing and Creating a CloudKit Database](https://developer.apple.com/documentation/cloudkit/designing-and-creating-a-cloudkit-database)