CLAUDE.md ΓÇö FLW Mobile App

This file gives AI coding agents (Claude Code, Cursor, Copilot) instant contextual knowledge of the FLW-Mobile-App codebase so they can assist without requiring manual context pasting.

What this app is

The FLW (Field-Level Worker) Mobile App is an Android application built on the AMRIT platform. It digitises the daily work of ASHA community health workers across India ΓÇö household registration, pregnancy and delivery tracking, child health records, NCD screening, and immunization.

Critical constraint: The app is offline-first. ASHA workers operate in low-connectivity rural environments. Every feature must work without internet and sync when connectivity returns.

Tech stack

Package structure

org.piramalswasthya.sakhi
Γö£ΓöÇΓöÇ database/
Γöé   Γö£ΓöÇΓöÇ converters/          # Room TypeConverters
Γöé   Γö£ΓöÇΓöÇ room/
Γöé   Γöé   Γö£ΓöÇΓöÇ dao/             # All DAO interfaces
Γöé   Γöé   Γöé   ΓööΓöÇΓöÇ dynamicSchemaDao/
Γöé   Γöé   ΓööΓöÇΓöÇ InAppDb.kt       # @Database class ΓÇö single source of truth
Γöé   ΓööΓöÇΓöÇ shared_preferences/
Γöé       ΓööΓöÇΓöÇ PreferenceDao.kt # All SharedPreferences access
Γö£ΓöÇΓöÇ di/                      # Hilt modules
Γö£ΓöÇΓöÇ gamification/            # Gamification engine (sealed events, engine, catalog)
Γö£ΓöÇΓöÇ helpers/                 # Utility classes
Γö£ΓöÇΓöÇ model/                   # All Room @Entity data classes
Γö£ΓöÇΓöÇ network/                 # Retrofit API services
Γö£ΓöÇΓöÇ repositories/            # Data layer ΓÇö one repo per domain
Γö£ΓöÇΓöÇ ui/
Γöé   Γö£ΓöÇΓöÇ home_activity/       # Feature fragments (one folder per feature)
Γöé   Γöé   ΓööΓöÇΓöÇ <feature>/
Γöé   Γöé       Γö£ΓöÇΓöÇ <Feature>Fragment.kt
Γöé   Γöé       ΓööΓöÇΓöÇ <Feature>ViewModel.kt
Γöé   ΓööΓöÇΓöÇ ...
Γö£ΓöÇΓöÇ work/                    # WorkManager workers
ΓööΓöÇΓöÇ SakhiApplication.kt

Critical conventions

1. Database (Room)

DB class: InAppDb ΓÇö NOT AppDatabase. Located at database/room/InAppDb.kt. Current version: 58.

Never bump the version without adding a migration.

Entity pattern:

@Entity(tableName = "MY_TABLE")
data class MyCache(
    @PrimaryKey
    @ColumnInfo(name = "id")
    val id: Long,

    @ColumnInfo(name = "myField")
    val myField: String,

    // Always use Int for sync state, never Boolean
    @ColumnInfo(name = "syncState")
    val syncState: Int = 0   // 0=UNSYNCED, 1=SYNCING, 2=SYNCED
)

syncState convention: Always Int, never Boolean isSynced.

Migration pattern ΓÇö always use guards:

val MIGRATION_X_Y = object : Migration(X, Y) {
    override fun migrate(database: SupportSQLiteDatabase) {
        if (!tableExists(database, "MY_TABLE")) {
            database.execSQL("CREATE TABLE `MY_TABLE` (...)")
        }
        if (!columnExists(database, "MY_TABLE", "myColumn")) {
            database.execSQL("ALTER TABLE MY_TABLE ADD COLUMN myColumn TEXT")
        }
    }
}

tableExists() and columnExists() are companion object functions on InAppDb. Always use them ΓÇö never assume a table or column exists.

Adding a new entity checklist:

2. DAO pattern

@Dao
interface MyDao {
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun upsert(entity: MyCache)

    @Query("SELECT * FROM MY_TABLE WHERE id = :id")
    suspend fun getById(id: Long): MyCache?

    // Use Flow for observation ΓÇö never LiveData
    @Query("SELECT * FROM MY_TABLE WHERE syncState = 0")
    fun observeUnsynced(): Flow<List<MyCache>>

    @Query("UPDATE MY_TABLE SET syncState = 2 WHERE id = :id")
    suspend fun markSynced(id: Long)
}

3. Repository pattern

@Singleton
class MyRepo @Inject constructor(
    private val myDao: MyDao,
    private val apiService: AmritApiService,
    private val prefDao: PreferenceDao
) {
    // All DB calls ΓÇö no context switch needed, Room handles threading
    suspend fun getById(id: Long) = myDao.getById(id)

    // All network calls ΓÇö always switch to IO dispatcher
    suspend fun syncToServer(): NetworkResult<String> {
        return withContext(Dispatchers.IO) {
            try {
                val response = apiService.myEndpoint(...)
                if (response.isSuccessful) NetworkResult.Success(...)
                else NetworkResult.Error(response.code(), ...)
            } catch (e: IOException) {
                NetworkResult.Error(-1, "Unable to connect to Internet!")
            } catch (e: SocketTimeoutException) {
                NetworkResult.Error(-3, "Request Timed out! Please try again!")
            }
        }
    }
}

4. ViewModel pattern

@HiltViewModel
class MyViewModel @Inject constructor(
    private val myRepo: MyRepo
) : ViewModel() {

    // Use StateFlow, never LiveData
    val myData: StateFlow<MyData?> = myRepo
        .observeMyData()
        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), null)

    fun doSomething() {
        viewModelScope.launch {
            myRepo.doSomething()
        }
    }
}

5. Fragment pattern

@AndroidEntryPoint
class MyFragment : Fragment() {

    private val viewModel: MyViewModel by viewModels()
    private var _binding: FragmentMyBinding? = null
    private val binding get() = _binding!!

    override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?,
        savedInstanceState: Bundle?): View {
        _binding = FragmentMyBinding.inflate(inflater, container, false)
        return binding.root
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        viewLifecycleOwner.lifecycleScope.launch {
            repeatOnLifecycle(Lifecycle.State.STARTED) {
                viewModel.myData.collect { data -> render(data) }
            }
        }
    }

    override fun onDestroyView() {
        super.onDestroyView()
        _binding = null   // Always null binding to prevent memory leaks
    }
}

6. WorkManager worker pattern

@HiltWorker
class MySyncWorker @AssistedInject constructor(
    @Assisted context: Context,
    @Assisted params: WorkerParameters,
    private val myRepo: MyRepo
) : CoroutineWorker(context, params) {

    override suspend fun doWork(): Result {
        return try {
            // do sync
            Result.success()
        } catch (e: CancellationException) {
            throw e   // Always rethrow CancellationException
        } catch (e: Exception) {
            if (runAttemptCount < 3) Result.retry() else Result.failure()
        }
    }

    companion object {
        fun schedule(workManager: WorkManager) {
            workManager.enqueueUniquePeriodicWork(
                "MySyncWorker",
                ExistingPeriodicWorkPolicy.KEEP,
                PeriodicWorkRequestBuilder<MySyncWorker>(6, TimeUnit.HOURS)
                    .setConstraints(Constraints.Builder()
                        .setRequiredNetworkType(NetworkType.CONNECTED)
                        .build())
                    .build()
            )
        }
    }
}

7. Getting the logged-in user

// Inject PreferenceDao and call:
val user = preferenceDao.getLoggedInUser()  // returns User?
val userId = user?.userId                    // Int
val userName = user?.userName               // String

Never access SharedPreferences directly ΓÇö always use PreferenceDao.

8. API 25 compatibility rules

9. Localization

All user-facing strings must exist in three files:

Never hardcode user-visible text in Kotlin or XML layout files.

10. What NOT to do

Health domain context

The app tracks:

The BenBasicCache is a Room @DatabaseView that joins most of these into a single queryable view used by the main beneficiary list screen.

Gamification module (added in v58)

Located at gamification/. Consists of:

To trigger gamification from a health form after a successful save:

gamificationViewModel.onHealthEvent(
    userId,
    GamificationEvent.AncVisitCompleted(benId.toString())
)

Available events: HouseholdRegistered, BeneficiaryRegistered, AncVisitCompleted, DeliveryOutcomeRecorded, PncVisitCompleted, ImmunizationRecorded, HrpCaseIdentified, NcdScreeningCompleted, CbacFormFilled, DailyLogin.