feat(core/store): complete Phase B seam — Theme + Koin + DB v2 + RoomSubmitOutbox

Phase B chunks 1-4 complete. Builds on the scaffold from prior commit:

  Chunk 1 — Theme wiring (core/designsystem/.../Theme.kt)
    + import com.mifos.core.store.appScreenStateDefaults
    + import template.core.base.ui.screen.LocalScreenStateDefaults
    + KptMaterialTheme now wraps content in
      CompositionLocalProvider(LocalScreenStateDefaults provides ...) — every
      screen under MifosTheme inherits branded ScreenState defaults.
    + core/designsystem/build.gradle.kts: + implementation(projects.core.store)

  Chunk 2 — Koin DI wiring
    + cmp-navigation/.../di/KoinModules.kt registers appStoreModule in
      'allModules' list. Feature waves (Phase C) bind their Store<K,V>
      factories qualifier-bound via AppStoreRegistry.
    + cmp-navigation/build.gradle.kts: + implementation(projects.core.store)

  Chunk 3 — Database v1 -> v2 migration (Store5 submit-draft outbox)
    + core/database/src/commonMain/.../entities/framework/DraftEntity.kt —
      @entity(tableName = 'framework_submit_drafts'); 7 columns matching
      template's reference impl.
    + core/database/src/commonMain/.../dao/DraftDao.kt — @dao interface with
      insert / getById / getPendingByFormKey / observePendingByFormKey /
      getAllPending / markRetrying / markSubmitted / markFailed /
      updatePayload / deleteByFormKey / deleteAll / deleteOlderThan.
    + commonMain MifosDatabase + 3 platform actuals (android, desktop,
      native): import DraftEntity / DraftDao, add to entities[], add
      'abstract val draftDao: DraftDao', bump VERSION 1 -> 2 with KDoc.
    + DatabaseModule.android.kt / desktop.kt / PlatformSpecificModule.kt:
      add MIGRATION_1_2 (raw SQL CREATE TABLE) and chain .addMigrations()
      onto the AppDatabaseFactory builder. SQL is platform-portable
      (androidx.room3.migration.Migration + androidx.sqlite.execSQL).
    + DaoModule.kt: + single { get<MifosDatabase>().draftDao }
    + core/data/.../infra/impl/RoomSubmitOutbox.kt — Room-backed
      SubmitOutbox<P>. Serializes payload via kotlinx.serialization,
      stores in framework_submit_drafts. Idempotent save (upserts on
      formKey collision). Wires markRetrying / markSubmitted /
      markFailed to DraftDao status transitions.
    + core/data/build.gradle.kts: + api(projects.coreBase.store)

  Chunk 4 — OfflineSubmitSyncer pattern documented in core/store/README.md
    Syncer is parameterized by payload type P, so it is instantiated per-form
    in feature DI modules (not globally in MainActivity). Pattern documented
    with full Koin DI example under 'Phase C syncer pattern' heading.

This makes core/store / core/database / core/data ready for Phase C feature
waves to start migrating to Store5 with offline-resilient mutations.

Author: Rajan Maurya

cmp-navigation/build.gradle.kts

@@ -29,6 +29,7 @@ kotlin {
             implementation(projects.core.datastore)
             implementation(projects.core.database)
             implementation(projects.core.network)
+            implementation(projects.core.store)
             implementation(projects.coreBase.common)
 
             implementation(projects.feature.about)

cmp-navigation/src/commonMain/kotlin/cmp/navigation/di/KoinModules.kt

@@ -18,6 +18,7 @@ import com.mifos.core.datastore.di.PreferencesModule
 import com.mifos.core.domain.di.UseCaseModule
 import com.mifos.core.network.di.DataManagerModule
 import com.mifos.core.network.di.NetworkModule
+import com.mifos.core.store.di.appStoreModule
 import com.mifos.feature.activate.di.ActivateModule
 import com.mifos.feature.auth.di.AuthModule
 import com.mifos.feature.center.di.CenterModule
@@ -107,5 +108,6 @@ object KoinModules {
         networkModules,
         coreDataStoreModules,
         coreBaseCommonModules,
+        appStoreModule,
     )
 }

core/data/build.gradle.kts

@@ -40,6 +40,7 @@ kotlin {
             api(projects.core.network)
             api(projects.core.database)
             api(projects.coreBase.common)
+            api(projects.coreBase.store)
 
 
             implementation(libs.mifos.authenticator.passcode)

core/data/src/commonMain/kotlin/com/mifos/core/data/infra/impl/RoomSubmitOutbox.kt

@@ -0,0 +1,102 @@
+/*
+ * Copyright 2025 Mifos Initiative
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ *
+ * See https://github.com/openMF/mifos-x-field-officer-app/blob/master/LICENSE.md
+ */
+package com.mifos.core.data.infra.impl
+
+import com.mifos.room.dao.DraftDao
+import com.mifos.room.entities.framework.DraftEntity
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.map
+import kotlinx.serialization.KSerializer
+import kotlinx.serialization.json.Json
+import template.core.base.store.submit.SubmitOutbox
+import template.core.base.store.submit.SubmitOutboxEntry
+import template.core.base.store.submit.SubmitOutboxStatus
+
+/**
+ * Room-backed [SubmitOutbox] that persists form payloads across process death.
+ *
+ * Serializes payloads to JSON via [kotlinx.serialization] and stores them in the
+ * `framework_submit_drafts` table inside [com.mifos.room.MifosDatabase].
+ *
+ * Wire one instance per form type in your DI module:
+ * ```kotlin
+ * single<SubmitOutbox<LoanApplicationPayload>> {
+ *     RoomSubmitOutbox(
+ *         dao = get<MifosDatabase>().draftDao,
+ *         serializer = LoanApplicationPayload.serializer(),
+ *     )
+ * }
+ * ```
+ *
+ * @param P Payload type. Must be annotated with `@Serializable`.
+ * @param dao The Room DAO for the `framework_submit_drafts` table.
+ * @param serializer Kotlinx serializer for [P]. Obtain via `P.serializer()`.
+ */
+class RoomSubmitOutbox<P>(
+    private val dao: DraftDao,
+    private val serializer: KSerializer<P>,
+) : SubmitOutbox<P> {
+
+    private val json = Json { ignoreUnknownKeys = true }
+
+    override suspend fun save(formKey: String, payload: P): Long {
+        val nowMs = currentTimeMillis()
+        val existing = dao.getPendingByFormKey(formKey)
+        if (existing != null) {
+            dao.updatePayload(existing.id, json.encodeToString(serializer, payload), nowMs)
+            return existing.id
+        }
+        val entity = DraftEntity(
+            formKey = formKey,
+            payloadJson = json.encodeToString(serializer, payload),
+            status = SubmitOutboxStatus.PENDING.name,
+            createdAtMs = nowMs,
+            updatedAtMs = nowMs,
+        )
+        return dao.insert(entity)
+    }
+
+    override suspend fun getPending(formKey: String): SubmitOutboxEntry<P>? =
+        dao.getPendingByFormKey(formKey)?.toEntry()
+
+    override fun observePending(formKey: String): Flow<SubmitOutboxEntry<P>?> =
+        dao.observePendingByFormKey(formKey).map { it?.toEntry() }
+
+    override suspend fun getAllPending(): List<SubmitOutboxEntry<P>> =
+        dao.getAllPending().mapNotNull { it.toEntry() }
+
+    override suspend fun markRetrying(id: Long) =
+        dao.markRetrying(id, currentTimeMillis())
+
+    override suspend fun markSubmitted(id: Long) =
+        dao.markSubmitted(id, currentTimeMillis())
+
+    override suspend fun markFailed(id: Long, error: String?) =
+        dao.markFailed(id, currentTimeMillis(), error)
+
+    override suspend fun deleteByFormKey(formKey: String) =
+        dao.deleteByFormKey(formKey)
+
+    override suspend fun deleteAll() =
+        dao.deleteAll()
+
+    private fun DraftEntity.toEntry(): SubmitOutboxEntry<P>? = runCatching {
+        SubmitOutboxEntry(
+            id = id,
+            formKey = formKey,
+            payload = json.decodeFromString(serializer, payloadJson),
+            status = SubmitOutboxStatus.valueOf(status),
+            createdAtMs = createdAtMs,
+            errorMessage = errorMessage,
+        )
+    }.getOrNull()
+}
+
+private fun currentTimeMillis(): Long = kotlin.time.Clock.System.now().toEpochMilliseconds()

core/database/src/androidMain/kotlin/com/mifos/room/MifosDatabase.kt

@@ -16,13 +16,15 @@ import com.mifos.room.dao.CenterDao
 import com.mifos.room.dao.ChargeDao
 import com.mifos.room.dao.ClientDao
 import com.mifos.room.dao.ColumnValueDao
+import com.mifos.room.dao.DraftDao
 import com.mifos.room.dao.GroupsDao
 import com.mifos.room.dao.LoanDao
 import com.mifos.room.dao.OfficeDao
 import com.mifos.room.dao.SavingsDao
 import com.mifos.room.dao.StaffDao
 import com.mifos.room.dao.SurveyDao
 import com.mifos.room.entities.PaymentTypeOptionEntity
+import com.mifos.room.entities.framework.DraftEntity
 import com.mifos.room.entities.accounts.loans.ActualDisbursementDateEntity
 import com.mifos.room.entities.accounts.loans.LoanAccountEntity
 import com.mifos.room.entities.accounts.loans.LoanRepaymentRequestEntity
@@ -148,6 +150,8 @@ import com.mifos.room.typeconverters.CustomTypeConverters
         LoanRepaymentTemplateEntity::class,
         // zip models package
         PaymentTypeOptionEntity::class,
+        // framework: submit-draft outbox
+        DraftEntity::class,
     ],
     version = MifosDatabase.VERSION,
     exportSchema = false,
@@ -161,6 +165,7 @@ actual abstract class MifosDatabase : RoomDatabase() {
     actual abstract val chargeDao: ChargeDao
     actual abstract val clientDao: ClientDao
     actual abstract val columnValueDao: ColumnValueDao
+    actual abstract val draftDao: DraftDao
     actual abstract val groupsDao: GroupsDao
     actual abstract val loanDao: LoanDao
     actual abstract val officeDao: OfficeDao
@@ -169,6 +174,6 @@ actual abstract class MifosDatabase : RoomDatabase() {
     actual abstract val surveyDao: SurveyDao
 
     companion object {
-        const val VERSION = 1
+        const val VERSION = 2
     }
 }

core/database/src/androidMain/kotlin/com/mifos/room/di/DatabaseModule.android.kt

@@ -9,7 +9,10 @@
  */
 package com.mifos.room.di
 
+import androidx.room3.migration.Migration
+import androidx.sqlite.SQLiteConnection
 import androidx.sqlite.driver.bundled.BundledSQLiteDriver
+import androidx.sqlite.execSQL
 import com.mifos.core.common.network.MifosDispatchers
 import com.mifos.core.common.utils.Constants
 import com.mifos.room.MifosDatabase
@@ -20,13 +23,36 @@ import org.koin.dsl.module
 import template.core.base.database.AppDatabaseFactory
 import kotlin.coroutines.CoroutineContext
 
+/**
+ * Adds the `framework_submit_drafts` table — see
+ * [com.mifos.room.entities.framework.DraftEntity] for the schema.
+ */
+internal val MIGRATION_1_2 = object : Migration(1, 2) {
+    override fun migrate(connection: SQLiteConnection) {
+        connection.execSQL(
+            """
+            CREATE TABLE IF NOT EXISTS `framework_submit_drafts` (
+                `id` INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
+                `formKey` TEXT NOT NULL,
+                `payloadJson` TEXT NOT NULL,
+                `status` TEXT NOT NULL,
+                `createdAtMs` INTEGER NOT NULL,
+                `updatedAtMs` INTEGER NOT NULL,
+                `errorMessage` TEXT
+            )
+            """.trimIndent(),
+        )
+    }
+}
+
 actual val PlatformSpecificDatabaseModule: Module = module {
     single<MifosDatabase> {
         val ioContext: CoroutineContext = getKoin().get(named(MifosDispatchers.IO.name))
 
         AppDatabaseFactory(androidApplication())
             .createDatabase(MifosDatabase::class.java, Constants.DATABASE_NAME)
             .fallbackToDestructiveMigrationOnDowngrade(false)
+            .addMigrations(MIGRATION_1_2)
             .setDriver(BundledSQLiteDriver())
             .setQueryCoroutineContext(ioContext)
             .build()

core/database/src/commonMain/kotlin/com/mifos/room/MifosDatabase.kt

@@ -13,6 +13,7 @@ import com.mifos.room.dao.CenterDao
 import com.mifos.room.dao.ChargeDao
 import com.mifos.room.dao.ClientDao
 import com.mifos.room.dao.ColumnValueDao
+import com.mifos.room.dao.DraftDao
 import com.mifos.room.dao.GroupsDao
 import com.mifos.room.dao.LoanDao
 import com.mifos.room.dao.OfficeDao
@@ -26,6 +27,7 @@ expect abstract class MifosDatabase {
     abstract val chargeDao: ChargeDao
     abstract val clientDao: ClientDao
     abstract val columnValueDao: ColumnValueDao
+    abstract val draftDao: DraftDao
     abstract val groupsDao: GroupsDao
     abstract val loanDao: LoanDao
     abstract val officeDao: OfficeDao

core/database/src/commonMain/kotlin/com/mifos/room/dao/DraftDao.kt

@@ -0,0 +1,75 @@
+/*
+ * Copyright 2025 Mifos Initiative
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ *
+ * See https://github.com/openMF/mifos-x-field-officer-app/blob/master/LICENSE.md
+ */
+package com.mifos.room.dao
+
+import com.mifos.room.entities.framework.DraftEntity
+import kotlinx.coroutines.flow.Flow
+import template.core.base.database.Dao
+import template.core.base.database.Insert
+import template.core.base.database.OnConflictStrategy
+import template.core.base.database.Query
+
+/**
+ * DAO for the framework-owned `framework_submit_drafts` table.
+ *
+ * Consumed by [com.mifos.core.data.infra.impl.RoomSubmitOutbox]. The framework uses
+ * this table to persist form payloads that failed to reach the server so users can
+ * resume or retry later.
+ */
+@Dao
+interface DraftDao {
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun insert(entity: DraftEntity): Long
+
+    @Query("SELECT * FROM framework_submit_drafts WHERE id = :id")
+    suspend fun getById(id: Long): DraftEntity?
+
+    @Query("SELECT * FROM framework_submit_drafts WHERE formKey = :formKey AND status = 'PENDING' LIMIT 1")
+    suspend fun getPendingByFormKey(formKey: String): DraftEntity?
+
+    @Query("SELECT * FROM framework_submit_drafts WHERE formKey = :formKey AND status = 'PENDING' LIMIT 1")
+    fun observePendingByFormKey(formKey: String): Flow<DraftEntity?>
+
+    @Query("SELECT * FROM framework_submit_drafts WHERE status = 'PENDING'")
+    suspend fun getAllPending(): List<DraftEntity>
+
+    @Query("UPDATE framework_submit_drafts SET status = 'RETRYING', updatedAtMs = :nowMs WHERE id = :id")
+    suspend fun markRetrying(id: Long, nowMs: Long)
+
+    @Query("UPDATE framework_submit_drafts SET status = 'SUBMITTED', updatedAtMs = :nowMs WHERE id = :id")
+    suspend fun markSubmitted(id: Long, nowMs: Long)
+
+    @Query(
+        "UPDATE framework_submit_drafts SET status = 'FAILED', " +
+            "updatedAtMs = :nowMs, errorMessage = :error WHERE id = :id",
+    )
+    suspend fun markFailed(id: Long, nowMs: Long, error: String?)
+
+    @Query("UPDATE framework_submit_drafts SET payloadJson = :payloadJson, updatedAtMs = :nowMs WHERE id = :id")
+    suspend fun updatePayload(id: Long, payloadJson: String, nowMs: Long)
+
+    @Query("DELETE FROM framework_submit_drafts WHERE formKey = :formKey")
+    suspend fun deleteByFormKey(formKey: String)
+
+    @Query("DELETE FROM framework_submit_drafts")
+    suspend fun deleteAll()
+
+    /**
+     * Deletes SUBMITTED and FAILED rows older than [thresholdMs] (epoch millis).
+     * PENDING drafts are never pruned here — the user may still want to resume them.
+     * Call on app start via the framework's StoreCacheManager.pruneExpiredDrafts hook.
+     */
+    @Query(
+        "DELETE FROM framework_submit_drafts " +
+            "WHERE createdAtMs < :thresholdMs AND status IN ('SUBMITTED', 'FAILED')",
+    )
+    suspend fun deleteOlderThan(thresholdMs: Long)
+}

core/database/src/commonMain/kotlin/com/mifos/room/di/DaoModule.kt

@@ -18,6 +18,7 @@ val DaoModule = module {
     single { get<MifosDatabase>().chargeDao }
     single { get<MifosDatabase>().clientDao }
     single { get<MifosDatabase>().columnValueDao }
+    single { get<MifosDatabase>().draftDao }
     single { get<MifosDatabase>().groupsDao }
     single { get<MifosDatabase>().loanDao }
     single { get<MifosDatabase>().officeDao }

core/database/src/commonMain/kotlin/com/mifos/room/entities/framework/DraftEntity.kt

@@ -0,0 +1,53 @@
+/*
+ * Copyright 2025 Mifos Initiative
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ *
+ * See https://github.com/openMF/mifos-x-field-officer-app/blob/master/LICENSE.md
+ */
+package com.mifos.room.entities.framework
+
+import template.core.base.database.Entity
+import template.core.base.database.PrimaryKey
+
+/**
+ * Durable row for a form payload that failed to reach the server.
+ *
+ * Written by [com.mifos.core.data.infra.impl.RoomSubmitOutbox] when a network error
+ * occurs during form submission. The row survives process death so the user can
+ * resume or retry later.
+ *
+ * @param id          Auto-generated surrogate key.
+ * @param formKey     Consumer-defined identifier that groups drafts by screen/form type
+ *                    (e.g. `"loan_application"`, `"client_registration"`). One pending
+ *                    draft per formKey is the intended invariant — consumers enforce
+ *                    uniqueness via [com.mifos.room.dao.DraftDao.deleteByFormKey] before
+ *                    inserting.
+ * @param payloadJson Serialized form payload (JSON). The concrete type is opaque to the
+ *                    framework; consumers encode/decode via kotlinx.serialization.
+ * @param status      Lifecycle state — one of
+ *                    [template.core.base.store.submit.SubmitOutboxStatus] values
+ *                    serialized as `.name`.
+ * @param createdAtMs Epoch millis when the draft was first saved.
+ * @param updatedAtMs Epoch millis of the most recent status transition.
+ * @param errorMessage Last failure reason for display in the resume UI (nullable).
+ */
+@Entity(
+    indices = [],
+    inheritSuperIndices = false,
+    primaryKeys = [],
+    foreignKeys = [],
+    ignoredColumns = [],
+    tableName = "framework_submit_drafts",
+)
+data class DraftEntity(
+    @PrimaryKey(autoGenerate = true) val id: Long = 0,
+    val formKey: String,
+    val payloadJson: String,
+    val status: String,
+    val createdAtMs: Long,
+    val updatedAtMs: Long,
+    val errorMessage: String? = null,
+)