Kotlin Multiplatform sync/data stack for Quran mobile apps.

This repository contains shared modules used by Android and iOS apps for:

• Authentication (OIDC)
• Local persistence (SQLDelight)
• Sync engine orchestration
• A unified app-level service API (SyncService)

• Architecture
• Modules
• Requirements
• Quick Start
• Usage
• Run the Demos
• Build, Test, and Release Commands
• Related Repositories

auth + persistence + syncengine are composed in sync-pipelines, exposed through a DI graph (AppGraph / SharedDependencyGraph), and exported to iOS through umbrella.

flowchart LR
  UI[Android/iOS UI] --> S[SyncService]
  S --> A[Auth Module]
  S --> P[Persistence Module]
  S --> E[SyncEngine Module]
  U[Umbrella XCFramework] --> UI

• JDK 17
• Android Studio (for Android demo)
• Xcode (for iOS demo)
• Cocoa toolchain for iOS simulator/device builds

Optional but recommended:

• local.properties with OAuth credentials:

OAUTH_CLIENT_ID=your_client_id
OAUTH_CLIENT_SECRET=your_client_secret

1. Clone and enter the repo:

git clone https://github.com/quran/mobile-sync.git
cd mobile-sync

2. Ensure Gradle can resolve dependencies:

./gradlew help

3. Run tests:

./gradlew allTests --stacktrace --continue

import com.quran.shared.auth.di.AuthFlowFactoryProvider
import com.quran.shared.persistence.DriverFactory
import com.quran.shared.pipeline.AppEnvironment
import com.quran.shared.pipeline.di.SharedDependencyGraph
import org.publicvalue.multiplatform.oidc.appsupport.AndroidCodeAuthFlowFactory

val authFactory = AndroidCodeAuthFlowFactory(useWebView = false)
authFactory.registerActivity(activity)
AuthFlowFactoryProvider.initialize(authFactory)

val graph = SharedDependencyGraph.init(
    driverFactory = DriverFactory(context = applicationContext),
    appEnvironment = AppEnvironment.PRELIVE
)

val authService = graph.authService
val syncService = graph.syncService

import Shared

final class AppContainer {
    static let shared = AppContainer()
    static var graph: AppGraph { shared.graph }

    let graph: AppGraph

    private init() {
        Shared.AuthFlowFactoryProvider.shared.doInitialize()
        let driverFactory = DriverFactory()
        graph = SharedDependencyGraph.shared.doInit(
            driverFactory: driverFactory,
            appEnvironment: AppEnvironment.prelive
        )
    }
}

Advanced override for custom endpoints remains available:

import com.quran.shared.auth.model.AuthEnvironment
import com.quran.shared.syncengine.SynchronizationEnvironment

val graph = SharedDependencyGraph.init(
    driverFactory = DriverFactory(context = applicationContext),
    environment = SynchronizationEnvironment(
        endPointURL = "https://custom-sync.example.com/auth"
    ),
    authEnvironment = AuthEnvironment.PRELIVE
)

Core API examples:

• Observe: authState, bookmarks, collectionsWithBookmarks, notes
• Mutations: addBookmark, deleteBookmark, addCollection, deleteCollection, addNote, deleteNote
• Trigger sync: triggerSync()

Lifecycle note:

• SyncService is app-scoped. Initialize once via SharedDependencyGraph.init(...).
• Do not clear app-scoped services from UI/view-model teardown.

The published artifact can target either environment at runtime:

• AppEnvironment.PRELIVE / AppEnvironment.prelive
• AppEnvironment.PRODUCTION / AppEnvironment.production

AppEnvironment keeps auth and sync aligned by default:

• PRELIVE -> https://prelive-oauth2.quran.foundation and https://apis-prelive.quran.foundation/auth
• PRODUCTION -> https://oauth2.quran.foundation and https://apis.quran.foundation/auth

buildkonfig.flavor now only controls the default fallback used when the app does not pass an explicit app environment.

Default fallback (gradle.properties):

buildkonfig.flavor=debug

Override for release-like builds:

./gradlew :auth:build -Pbuildkonfig.flavor=release

1. Open project in Android Studio.
2. Run demo/android app module.

CLI build example:

./gradlew :demo:android:assembleDebug

1. Open: demo/apple/QuranSyncDemo/QuranSyncDemo.xcodeproj
2. Select QuranSyncDemo scheme.
3. Run on an iOS Simulator.

The Xcode project includes a Run Script phase that calls:

./gradlew :umbrella:embedAndSignAppleFrameworkForXcode

CLI build example:

xcodebuild -project demo/apple/QuranSyncDemo/QuranSyncDemo.xcodeproj \
  -scheme QuranSyncDemo \
  -configuration Debug \
  -destination 'generic/platform=iOS Simulator' \
  build CODE_SIGNING_ALLOWED=NO

Build all:

./gradlew build

Run all tests:

./gradlew allTests --stacktrace --continue

Build iOS XCFramework:

./gradlew :umbrella:assembleSharedXCFramework

Build Android demo compile target:

./gradlew :demo:android:compileDebugKotlin

Build iOS KMP target:

./gradlew :sync-pipelines:compileKotlinIosSimulatorArm64

• mobile-sync-spm
• quran_android
• quran-ios