Sync and data stack for Quran apps: OIDC authentication, SQL-backed local persistence, orchestration of sync engine via DI, unified SyncService API, mutation/observe primitives and demos.
Kotlin Multiplatform sync/data stack for Quran mobile apps.
This repository contains shared modules used by Android and iOS apps for:
QuranDataService)auth + persistence + syncengine are composed in sync-pipelines, exposed through a managed DI graph (AppGraph / SharedDependencyGraph), and exported to iOS through umbrella.
flowchart LR
UI[Android/iOS UI] --> G[AppGraph]
G --> S[QuranDataService]
G --> F[SyncAuthService]
F --> A[Auth Module]
S --> A
S --> P[Persistence Module]
S --> E[SyncEngine Module]
U[Umbrella XCFramework] --> UI
Optional but recommended:
local.properties with the OAuth client ID for the Android demo app:OAUTH_CLIENT_ID=your_client_id
Published library artifacts do not embed credentials. Android apps are OAuth public clients using PKCE and must not embed OAuth client secrets.
git clone https://github.com/quran/mobile-sync.git
cd mobile-sync
./gradlew help
./gradlew allTests --stacktrace --continue
Choose one integration mode per database.
Persistence-only mode uses the public :persistence repositories directly. Repositories preserve
local integrity and mutation tracking, but consumers must not mutate SQL tables directly. Use this
mode only when the database is not managed by :sync-pipelines.
Managed sync-capable mode uses :sync-pipelines through AppGraph. In this mode, all
user-visible data reads and writes go through QuranDataService, and authentication goes through
SyncAuthService. Do not mix direct persistence writes with the managed sync graph. If sync may be
enabled later for the same app data, use managed mode from day one, even while logged out.
Logged-out managed-service writes are local-first; sync triggers no-op until the user is
authenticated.
AppGraph exposes only managed facades: quranDataService: QuranDataService and
authService: SyncAuthService. Raw write-capable persistence repositories are no longer exposed
from ; they remain public in for persistence-only
consumers. The raw is hidden from and wrapped by
.
This repository is still in active development. Schema changes are made directly in .sq files;
.sqm migrations are not currently maintained.
Configure the Android app manifest placeholders for the login and post-logout redirect URIs. The
:auth artifact contributes com.quran.shared.auth.android.SafeOidcRedirectActivity as the
exported browser callback entry point and keeps the upstream OIDC HandleRedirectActivity
non-exported.
android {
defaultConfig {
manifestPlaceholders["oidcRedirectScheme"] = "com.quran.oauth"
manifestPlaceholders["oidcRedirectHost"] = "callback"
manifestPlaceholders["oidcPostLogoutRedirectScheme"] = "com.quran.oauth"
manifestPlaceholders["oidcPostLogoutRedirectHost"] = "callback"
}
}
Do not declare or export
org.publicvalue.multiplatform.oidc.appsupport.HandleRedirectActivity in the app manifest.
If you override AuthConfig.redirectUri or AuthConfig.postLogoutRedirectUri on Android, keep
the corresponding manifest placeholders aligned with those URIs.
Graph construction does not require an Android Activity. Build the graph from application
context and runtime configuration:
import com.quran.shared.persistence.DriverFactory
import com.quran.shared.pipeline.AppEnvironment
import com.quran.shared.pipeline.di.SharedDependencyGraph
import com.quran.shared.pipeline.storage.createMobileSyncStorage
val graph = SharedDependencyGraph.init(
driverFactory = DriverFactory(context = applicationContext),
storage = createMobileSyncStorage(applicationContext),
appEnvironment = AppEnvironment.PRELIVE,
clientId = appClientId
)
val authService = graph.authService
val quranDataService = graph.quranDataService
If clientId is blank, the same initializer creates a managed local-only graph. QuranDataService
continues to read and write local data, while SyncAuthService.isAuthenticationConfigured is
false and sign-in fails with an authentication-not-configured error. This lets open-source builds
run without bundled OAuth credentials.
Register the Android browser auth flow only before interactive sign-in. The registered Activity
handles browser launch and redirect delivery; it is not needed for graph construction or local data
operations.
import com.quran.shared.auth.di.AuthFlowFactoryProvider
import org.publicvalue.multiplatform.oidc.appsupport.AndroidCodeAuthFlowFactory
if (graph.authService.isAuthenticationConfigured) {
val authFactory = AndroidCodeAuthFlowFactory(useWebView = false)
authFactory.registerActivity(activity)
AuthFlowFactoryProvider.initialize(authFactory)
}
// Later, from the login UI:
graph.authService.login()
Advanced override for custom endpoints remains available:
import com.quran.shared.auth.model.AuthEnvironment
import com.quran.shared.auth.model.AuthConfig
import com.quran.shared.syncengine.SynchronizationEnvironment
val graph = SharedDependencyGraph.init(
driverFactory = DriverFactory(context = applicationContext),
storage = createMobileSyncStorage(applicationContext),
environment = SynchronizationEnvironment(
endPointURL = "https://custom-sync.example.com/auth"
),
authConfig = AuthConfig(
environment = AuthEnvironment.PRELIVE,
clientId = appClientId
)
)
Sync and session lifecycle metadata is stored in the shared quran.db database next to the data it
describes. Auth metadata and OAuth tokens stay outside the database, so a lost or recreated database
does not sign the user out. Both use stable DataStore file names so apps can exclude them from backup
or device transfer:
<exclude domain="file" path="datastore/quran_mobile_sync_auth.preferences_pb"/>
<exclude domain="file" path="datastore/org.publicvalue.multiplatform.oidc.tokenstore.preferences_pb"/>
Add those entries to both full-backup-content and Android 12+ data-extraction-rules when app
backup is enabled.
Core API examples:
Import local data through . Each must name an in the same batch. Names match exactly, except that any case or surrounding-whitespace variant of Favorites resolves to the default collection; entries sharing a name describe one destination. Use with or , each specifying a (, , or ), , and an optional . Each slot may appear once; page numbers must be in . An imported slot replaces its location, name (including clearing it when null), and modification time. Merge imports leave omitted slots unchanged; clears their locations while preserving slot identities and names for sync. Imports are atomic, track local sync mutations, and report the number of supplied reading bookmarks in .
Lifecycle note:
QuranDataService is app-scoped. Initialize once via SharedDependencyGraph.init(...).SyncAuthService.logout() for managed apps. QuranDataService.logout() remains available for callers that route auth and data lifecycle through one facade.The published artifact can target either environment at runtime:
AppEnvironment.PRELIVE / AppEnvironment.preliveAppEnvironment.PRODUCTION / AppEnvironment.productionAppEnvironment keeps auth and sync aligned by default:
PRELIVE -> https://prelive-oauth2.quran.foundation and https://apis-prelive.quran.foundation/authPRODUCTION -> https://oauth2.quran.foundation and https://apis.quran.foundation/authbuildkonfig.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
demo/android app module.CLI build example:
./gradlew :demo:android:assembleDebug
demo/apple/QuranSyncDemo/QuranSyncDemo.xcodeprojQuranSyncDemo scheme.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
| Module | Purpose |
|---|
:auth | OIDC login/logout, auth state, token handling |
:persistence | SQLDelight DB, repositories for bookmarks/collections/notes/reading sessions |
:syncengine | Core sync engine and scheduling |
:sync-pipelines | DI graph and QuranDataService managed data API |
:umbrella | iOS XCFramework export (Shared.xcframework) |
:demo:android | Android sample app (Compose) |
:demo:common | Shared demo helpers/models |
:mutations-definitions | Shared mutation/domain definitions |
:sync-pipelinesAppGraph:persistence:authAuthServiceAppGraphSyncAuthServiceimport 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()
let storage = AppleMobileSyncStorageFactory.shared.create()
graph = SharedDependencyGraph.shared.doInit(
driverFactory: driverFactory,
storage: storage,
appEnvironment: AppEnvironment.prelive,
clientId: appClientId,
clientSecret: appClientSecret
)
}
}
authState, bookmarks, collectionsWithBookmarks, notesaddBookmark, deleteBookmark, addCollection, deleteCollection, addNote, deleteNotetriggerSync()SyncAuthService.login(), loginWithReauthentication(), logout(), and clearError()QuranDataService.importData(PersistenceImportData(...))ImportCollectionAyahBookmark.collectionNameImportCollectionreadingBookmarksImportReadingBookmark.Ayah.PageReadingBookmarkSlotTEALORANGEREDlastUpdatedname1..604deleteExisting = truePersistenceImportResult.readingBookmarksImportedSurfaced from shared tags and platforms — no rankings paid for.