Authentication

.github/workflows/build.yml

@@ -0,0 +1,36 @@
+name: Gradle CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: macos-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v5
+        with:
+          java-version: "17"
+          distribution: "temurin"
+          cache: gradle
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v5
+
+      - name: Clean project
+        run: ./gradlew clean
+
+      - name: Run tests
+        run: ./gradlew allTests --stacktrace --continue
+
+      - name: Test Summary
+        uses: test-summary/action@v2
+        with:
+          paths: "**/build/test-results/**/TEST-*.xml"
+        if: always()

.github/workflows/release.yml

@@ -0,0 +1,101 @@
+name: Publish Shared XCFramework
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "Git ref (branch or tag) to build from"
+        required: true
+        default: main
+
+permissions:
+  contents: write
+
+env:
+  XCF_NAME: Shared
+  XCF_GRADLE_TASK: umbrella:assembleSharedXCFramework
+  XCF_OUTPUT_DIR: umbrella/build/XCFrameworks/release
+
+jobs:
+  build-and-release:
+    runs-on: macos-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.ref || github.ref }}
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v5
+        with:
+          java-version: "17"
+          distribution: "temurin"
+          cache: gradle
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v5
+
+      - name: Build XCFramework
+        run: ./gradlew $XCF_GRADLE_TASK --stacktrace
+
+      - name: Package XCFramework
+        id: package
+        shell: bash
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+        run: |
+          set -euo pipefail
+
+          read_property_version() {
+            local prop
+            if [[ ! -f gradle.properties ]]; then
+              echo "gradle.properties not found" >&2
+              return 1
+            fi
+            prop=$(awk -F'=' '/^version[[:space:]]*=/ {gsub(/^[[:space:]]+|[[:space:]]+$/, "", $2); gsub(/^"|"$/, "", $2); print $2; exit}' gradle.properties)
+            if [[ -z "$prop" ]]; then
+              echo "version property missing in gradle.properties" >&2
+              return 1
+            fi
+            printf '%s' "$prop"
+          }
+
+          property_version=$(read_property_version)
+
+          if [[ "$EVENT_NAME" == "workflow_dispatch" ]]; then
+            version="$property_version"
+            tag_name="v${version}"
+          else
+            tag_name="${GITHUB_REF_NAME}"
+            version="$property_version"
+            if [[ "$tag_name" != "v${version}" ]]; then
+              echo "Tag ${tag_name} does not match gradle.properties version ${version}" >&2
+              exit 1
+            fi
+          fi
+
+          archive_name="${XCF_NAME}-${version}.xcframework.zip"
+          output_dir="$XCF_OUTPUT_DIR"
+          cd "$output_dir"
+          rm -f "${XCF_NAME}.xcframework.zip" "$archive_name"
+          zip -r "$archive_name" "${XCF_NAME}.xcframework"
+
+          echo "archive-path=$output_dir/$archive_name" >> "$GITHUB_OUTPUT"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "tag-name=$tag_name" >> "$GITHUB_OUTPUT"
+
+      - name: Publish Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.package.outputs.tag-name }}
+          name: Shared XCFramework ${{ steps.package.outputs.version }}
+          draft: false
+          prerelease: ${{ contains(steps.package.outputs.version, '-') }}
+          make_latest: ${{ !contains(steps.package.outputs.version, '-') }}
+          files: ${{ steps.package.outputs.archive-path }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -20,3 +20,35 @@ build
 
 # Android
 local.properties
+
+# Xcode
+#
+# gitignore contributors: remember to update Global/Xcode.gitignore, Objective-C.gitignore & Swift.gitignore
+
+## User settings
+xcuserdata/
+
+## Obj-C/Swift specific
+*.hmap
+
+## App packaging
+*.ipa
+*.dSYM.zip
+*.dSYM
+
+# Swift Package Manager
+#
+# Add this line if you want to avoid checking in source code from Swift Package Manager dependencies.
+# Packages/
+# Package.pins
+# Package.resolved
+# *.xcodeproj
+#
+# Xcode automatically generates this directory with a .xcworkspacedata file and xcuserdata
+# hence it is not needed unless you have added a package configuration file to your project
+# .swiftpm
+
+.build/
+
+# macOS
+.DS_Store

CLAUDE.md

@@ -0,0 +1,149 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+The mobile-sync project (internally named "quransync") is a Kotlin Multiplatform Mobile (KMM) library for synchronizing Quran.com user data across Android and iOS. It implements bidirectional synchronization with conflict resolution for page bookmarks.
+
+## Development Commands
+
+### Building and Testing
+```bash
+# Clean and build entire project
+./gradlew clean build
+
+# Run all tests across all modules  
+./gradlew allTests
+
+# Run tests for specific module
+./gradlew :syncengine:test
+./gradlew :persistence:test
+
+# Build iOS framework
+./gradlew :umbrella:assembleXCFramework
+
+# Run Android demo
+./gradlew :demo:android:installDebug
+```
+
+### Module-Specific Commands
+```bash
+# Test individual components
+./gradlew :syncengine:testDebugUnitTest
+./gradlew :syncengine:testReleaseUnitTest
+
+# Check for dependency updates
+./gradlew dependencyUpdates
+```
+
+## Architecture Overview
+
+The project follows a layered architecture with clear separation of concerns:
+
+### Module Dependencies
+```
+mutations-definitions (foundational)
+         ↑
+    ┌────┴────┬────────────┐
+    │         │            │
+persistence  syncengine    │
+    └────┬────┴────────┐   │
+         │             │   │
+    sync-pipelines     │   │
+         ↑             │   │
+         │             │   │
+      umbrella    demo:android
+```
+
+### Core Modules
+
+**mutations-definitions**: Foundation module defining `Mutation`, `LocalModelMutation<Model>`, and `RemoteModelMutation<Model>` types used across the entire sync system.
+
+**persistence**: SQLDelight-based data layer with `PageBookmarksRepository` and change tracking. Handles cross-platform database operations and mutation state persistence.
+
+**syncengine**: Pure business logic module containing `SynchronizationClient`, `PageBookmarksSynchronizationExecutor`, conflict resolution system, network layer (Ktor), and scheduling system. Contains no external dependencies in core executor logic.
+
+**sync-pipelines**: Integration layer with `SyncEnginePipeline` that bridges syncengine and persistence. Provides the main high-level API via `RepositoryDataFetcher` and `ResultReceiver`.
+
+**umbrella**: iOS framework packaging module that exports all public APIs as "Shared" framework.
+
+**demo:android**: Sample Android app demonstrating library usage.
+
+### Key Architectural Patterns
+
+- **Dependency Inversion**: syncengine defines interfaces implemented by persistence
+- **Adapter Pattern**: sync-pipelines acts as adapter between layers  
+- **Pure Business Logic**: Core sync logic has no external dependencies
+- **Conflict Resolution Pipeline**: Sophisticated preprocessing and conflict handling
+
+## Technology Stack
+
+- **Language**: Kotlin Multiplatform (targeting iOS and Android)
+- **Database**: SQLDelight for cross-platform SQL operations
+- **Networking**: Ktor HTTP client with platform-specific implementations
+- **Serialization**: kotlinx.serialization
+- **Async**: kotlinx.coroutines 
+- **Testing**: kotlin.test with kotlinx.coroutines.test
+- **Build**: Gradle with Kotlin DSL
+- **iOS Distribution**: XCFramework via umbrella module
+
+## Development Guidelines
+
+### Module Boundaries
+- Keep syncengine pure (no external persistence dependencies)
+- Use sync-pipelines for integration between layers
+- Maintain clear interfaces between modules
+
+### Testing Strategy  
+- syncengine has comprehensive unit tests with timing-sensitive scheduling tests
+- Use `kotlinx.coroutines.test` for coroutine testing
+- Test timing with tolerance values (typically 100ms tolerance)
+
+### Synchronization Architecture
+The sync system implements a sophisticated bidirectional flow:
+
+1. **Local Changes**: `PageBookmarksRepository` tracks mutations
+2. **Sync Trigger**: Events fire through `SynchronizationClient` 
+3. **Pipeline Execution**: `PageBookmarksSynchronizationExecutor` orchestrates:
+   - Fetch local/remote mutations
+   - Conflict detection and resolution
+   - Push/pull data exchange
+4. **Result Persistence**: Coordinated by sync-pipelines
+
+### Scheduling System
+The recently added `Scheduler` in syncengine manages sync timing with:
+- `APP_START` trigger (30s delay)
+- `LOCAL_DATA_MODIFIED` trigger (5s delay)  
+- `IMMEDIATE` trigger (0ms delay)
+- Exponential backoff retry logic (200ms base, 2.5x multiplier, max 5 retries)
+- State machine tracking scheduler lifecycle
+
+**Error Handling**: The Scheduler uses exception-based error handling:
+- Task functions should throw exceptions to indicate failure
+- Scheduler catches exceptions and applies retry logic automatically
+- After maximum retries, the final exception is reported to the failure callback
+- Success is indicated by task function completing without throwing
+
+### Platform-Specific Considerations
+- HTTP clients: OkHttp (Android), Darwin (iOS)
+- Database drivers: Android SQLite, iOS native
+- Framework packaging: XCFramework for iOS consumption
+
+## Common Development Tasks
+
+### Adding New Mutation Types
+1. Define in mutations-definitions module
+2. Update persistence layer with SQL schema changes
+3. Add syncengine business logic
+4. Wire through sync-pipelines
+
+### Extending Sync Logic
+- Add new preprocessing steps to `LocalMutationsPreprocessor`/`RemoteMutationsPreprocessor`
+- Extend conflict resolution in `ConflictDetector`/`ConflictResolver`  
+- Update `PageBookmarksSynchronizationExecutor` pipeline
+
+### Testing Sync Behavior
+- Use test timings in `SchedulerTest.kt` as reference
+- Mock network layer for integration tests
+- Test conflict scenarios with controlled data states