Feature: Sync Mutations (Bookmarks, Collections, Collection Bookmarks, Notes)

[AhmedNMahran]

Related to Issue #87

Summary

This PR improves the synchronization engine by making it fully authentication-aware and refactoring the pipeline architecture for better maintainability. The core synchronization lifecycle is now tightly coupled with the user's authentication state via a reactive observer. Additionally, a new factory-based initialization system has been introduced to simplify the integration of synchronization features across Android and iOS platforms, eliminating manual object wiring in the UI layer.

Key Changes

1. Auth-Aware Synchronization Engine

• Safety Guards: The SynchronizationClient now verifies authentication status via AuthenticationDataFetcher.isLoggedIn() before any sync operation begins. Triggers received while logged out are safely ignored.
• Lifecycle Integration: Added triggerSyncImmediately() and cancelSyncing() to the sync client. These are automatically invoked by the service layer when authentication states change (Success vs Idle/Error).
• Immediate Sync: Sync operations now launch with zero delay upon login, followed by the standard periodic intervals.

2. Enhanced Scheduler Logic

• Cancellable Sessions: Implemented Scheduler.cancel() which halts pending jobs and resets the state to Idle. This allows the scheduler to be cleanly resumed when a user re-authenticates without stopping the underlying CoroutineScope.
• Buffer Management: Buffered triggers are cleared on failure or cancellation to prevent stale synchronization attempts.

3. Factory-Based Initialization

• SyncPipelineFactory: Introduced a centralized factory in the sync-pipelines module to encapsulate the complex setup of databases, repositories, and synchronization engines.
• Boilerplate Removal: Significantly reduced the code required in platform activities and managers. The manual manual instantiation of 5+ repositories and the sync pipeline is now replaced by a single factory call.
• Platform Support: Optimized for usage in both Kotlin (Android) and Swift (iOS), including specific convenience overloads for Swift interoperability.

4. Bookmark, Collection, Collection Bookmark, and Notes Actions Integration

• Sync operations are now fully integrated into the authentication-aware pipeline.
• Mutations are queued and processed only when the user is authenticated.
• The factory pattern extends repository initialization for cleaner code organization.

Technical Details

• Module: syncengine
  • Updated SynchronizationClient and Scheduler.
• Module: sync-pipelines
  • New File: SyncPipelineFactory.kt (Central entry point for feature initialization).
  • Added SyncService and SyncViewModel.
• Demo Apps:
  • Android: Updated MainActivity.kt to use SyncPipelineFactory.
  • iOS: Updated DatabaseManager.swift to utilize the factory and reflect class renames.

Testing

• Integration Tests: Updated SynchronizationClientIntegrationTest.kt to verify that sync operations are blocked when logged out.

[ahmedre]

ran this through a code-review from Codex, and it said:

  - [P0] Fix sync-pipelines JVM target depending on :auth without JVM variant — /Users/
    ahmedre/Developer/kmp/pr-sync/sync-pipelines/build.gradle.kts:16-36
    sync-pipelines/build.gradle.kts declares jvm() but commonMain.dependencies adds
    api(projects.auth), and :auth does not publish a jvm variant (only androidJvm +
    native). This makes :sync-pipelines:compileKotlinJvm (and any build that includes the
    JVM target) fail with a “No matching variant of project :auth was found” resolution
    error.
  - [P0] Implement LocalDataFetcher.fetchLocalModel in BookmarksSyncAdapterTest — /Users/
    ahmedre/Developer/kmp/pr-sync/syncengine/src/commonTest/kotlin/com/quran/shared/
    syncengine/BookmarksSyncAdapterTest.kt:31-37
    LocalDataFetcher gained the new abstract method fetchLocalModel(remoteID: String), but
    the anonymous LocalDataFetcher<SyncBookmark> in BookmarksSyncAdapterTest.kt does not
    implement it. This causes test compilation to fail
    (e.g., :syncengine:compileTestKotlinJvm).
  - [P0] Implement LocalDataFetcher.fetchLocalModel in
    SynchronizationClientIntegrationTest — /Users/ahmedre/Developer/kmp/pr-sync/
    syncengine/src/commonTest/kotlin/com/quran/shared/syncengine/
    SynchronizationClientIntegrationTest.kt:65-75
    The LocalDataFetcher<SyncBookmark> test double returned by createLocalMutationsFetcher
    doesn’t implement the new fetchLocalModel(remoteID: String) method, so syncengine/src/
    commonTest/.../SynchronizationClientIntegrationTest.kt no longer compiles for test
    targets.
  - [P3] Avoid detached Tasks in iOS SyncViewModel.observeData to prevent leaks — /Users/
    ahmedre/Developer/kmp/pr-sync/demo/apple/QuranSyncDemo/QuranSyncDemo/
    SyncViewModel.swift:25-46
    demo/apple/.../SyncViewModel.swift’s observeData() spawns two independent Task { ... }
    loops and then returns; these tasks are not tied to the caller’s SwiftUI .task
    cancellation and can keep running after the view disappears (also authTask/
    bookmarksTask are unused locals). This can lead to background work continuing
    unexpectedly and keeping self alive longer than intended.

[ahmedre]

side note - just merged #107 to fix tests on main so might want to rebase on that one

[mohamede1945]

Approving swift changes. Jazak Allah khyrn Ahmed

[ahmedre]

excellent work masha'Allah - some nits but please feel free to merge afterwards - jazakumAllah khairan!

[AhmedNMahran]

@ahmedre @mohamede1945 Jazakum Allah Khayran for the valuable comments. all nits are now resolved alhamdulillah, for the DI, will create an issue to track insha'Allah