android-sdd 1.0.0

package/skills/Data Layer/Paging/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: paging
+description: >
+  Jetpack Paging 3 setup and patterns for Android.
+  Load this skill when loading large datasets incrementally, implementing
+  infinite scroll, paginating network or database results, or combining
+  paged network data with a local Room cache.
+---
+
+# Paging
+
+## Overview
+Jetpack Paging 3 enables loading large datasets in pages — from network, database, or both. It integrates with Room, Retrofit, and Compose. The library handles load state, error retry, and list diffing automatically.
+
+---
+
+## Core Principles
+
+- Use Paging when a list **could grow unbounded** — don't load everything at once
+- **PagingSource** defines how to load a single page
+- **RemoteMediator** coordinates network + Room cache for offline-first paging
+- **PagingData** is consumed only once — use `cachedIn(viewModelScope)` to survive rotation
+- Never collect `PagingData` directly in ViewModel — use `collectAsLazyPagingItems` in Compose
+
+---
+
+## Setup
+
+```toml
+[versions]
+paging = "3.3.2"
+
+[libraries]
+paging-runtime = { module = "androidx.paging:paging-runtime", version.ref = "paging" }
+paging-compose  = { module = "androidx.paging:paging-compose", version.ref = "paging" }
+paging-room     = { module = "androidx.room:room-paging", version.ref = "room" }
+```
+
+---
+
+## PagingSource — Network Only
+
+```kotlin
+// ✅ Network-only PagingSource
+class UserPagingSource(
+    private val api: UserApi,
+    private val query: String
+) : PagingSource<Int, UserDto>() {
+
+    override suspend fun load(params: LoadParams<Int>): LoadResult<Int, UserDto> {
+        val page = params.key ?: 1
+
+        return try {
+            val response = api.getUsers(
+                query = query,
+                page = page,
+                pageSize = params.loadSize
+            )
+
+            LoadResult.Page(
+                data = response.users,
+                prevKey = if (page == 1) null else page - 1,
+                nextKey = if (response.users.isEmpty()) null else page + 1
+            )
+        } catch (e: IOException) {
+            LoadResult.Error(e)
+        } catch (e: HttpException) {
+            LoadResult.Error(e)
+        }
+    }
+
+    override fun getRefreshKey(state: PagingState<Int, UserDto>): Int? {
+        return state.anchorPosition?.let { anchor ->
+            state.closestPageToPosition(anchor)?.prevKey?.plus(1)
+                ?: state.closestPageToPosition(anchor)?.nextKey?.minus(1)
+        }
+    }
+}
+```
+
+---
+
+## Repository — Network-Only Paging
+
+```kotlin
+class UserRepository @Inject constructor(
+    private val api: UserApi,
+    private val mapper: UserMapper
+) {
+    fun searchUsers(query: String): Flow<PagingData<User>> = Pager(
+        config = PagingConfig(
+            pageSize = 20,
+            prefetchDistance = 5,
+            enablePlaceholders = false
+        ),
+        pagingSourceFactory = { UserPagingSource(api, query) }
+    ).flow.map { pagingData ->
+        pagingData.map { mapper.toDomain(it) }
+    }
+}
+```
+
+---
+
+## Room + Paging (Database-Only)
+
+```kotlin
+// ✅ Room generates PagingSource automatically
+@Dao
+interface UserDao {
+    @Query("SELECT * FROM users ORDER BY name ASC")
+    fun pagingSource(): PagingSource<Int, UserEntity>
+}
+
+// Repository
+class UserRepository @Inject constructor(private val userDao: UserDao) {
+    fun observeUsersPaged(): Flow<PagingData<User>> = Pager(
+        config = PagingConfig(pageSize = 20),
+        pagingSourceFactory = { userDao.pagingSource() }
+    ).flow.map { it.map(UserEntity::toDomain) }
+}
+```
+
+---
+
+## RemoteMediator — Network + Room Cache
+
+```kotlin
+// ✅ RemoteMediator: network fills Room, Room provides paged data
+@OptIn(ExperimentalPagingApi::class)
+class UserRemoteMediator(
+    private val api: UserApi,
+    private val db: AppDatabase
+) : RemoteMediator<Int, UserEntity>() {
+
+    override suspend fun load(
+        loadType: LoadType,
+        state: PagingState<Int, UserEntity>
+    ): MediatorResult {
+
+        val page = when (loadType) {
+            LoadType.REFRESH -> 1
+            LoadType.PREPEND -> return MediatorResult.Success(endOfPaginationReached = true)
+            LoadType.APPEND  -> {
+                val lastItem = state.lastItemOrNull()
+                    ?: return MediatorResult.Success(endOfPaginationReached = false)
+                getNextPageForItem(lastItem)
+            }
+        }
+
+        return try {
+            val response = api.getUsers(page = page, pageSize = state.config.pageSize)
+
+            db.withTransaction {
+                if (loadType == LoadType.REFRESH) {
+                    db.userDao().deleteAll()
+                }
+                db.userDao().upsertAll(response.users.map { it.toEntity() })
+            }
+
+            MediatorResult.Success(endOfPaginationReached = response.users.isEmpty())
+        } catch (e: IOException) {
+            MediatorResult.Error(e)
+        } catch (e: HttpException) {
+            MediatorResult.Error(e)
+        }
+    }
+
+    private suspend fun getNextPageForItem(item: UserEntity): Int {
+        // derive page number from item position
+        return (db.userDao().getItemIndex(item.id) / 20) + 2
+    }
+}
+
+// ✅ Pager with RemoteMediator
+@OptIn(ExperimentalPagingApi::class)
+fun usersPaged(): Flow<PagingData<User>> = Pager(
+    config = PagingConfig(pageSize = 20),
+    remoteMediator = UserRemoteMediator(api, db),
+    pagingSourceFactory = { db.userDao().pagingSource() }
+).flow.map { it.map(UserEntity::toDomain) }
+```
+
+---
+
+## ViewModel
+
+```kotlin
+@HiltViewModel
+class UserListViewModel @Inject constructor(
+    private val repository: UserRepository
+) : ViewModel() {
+
+    private val _query = MutableStateFlow("")
+
+    // ✅ cachedIn — survives rotation without re-fetching
+    val users: Flow<PagingData<User>> = _query
+        .debounce(300)
+        .flatMapLatest { query -> repository.searchUsers(query) }
+        .cachedIn(viewModelScope)
+
+    fun onQueryChanged(query: String) { _query.value = query }
+}
+```
+
+---
+
+## Compose UI
+
+```kotlin
+@Composable
+fun UserListScreen(viewModel: UserListViewModel = hiltViewModel()) {
+    val users = viewModel.users.collectAsLazyPagingItems()
+
+    LazyColumn {
+        items(
+            count = users.itemCount,
+            key = users.itemKey { it.id }
+        ) { index ->
+            val user = users[index]
+            if (user != null) UserCard(user = user)
+            else UserCardPlaceholder()
+        }
+
+        // ✅ Load state handling
+        when (val state = users.loadState.append) {
+            is LoadState.Loading -> item { LoadingIndicator() }
+            is LoadState.Error   -> item {
+                ErrorItem(
+                    message = state.error.message ?: "Error",
+                    onRetry = { users.retry() }
+                )
+            }
+            else -> Unit
+        }
+    }
+
+    // ✅ Refresh state
+    when (users.loadState.refresh) {
+        is LoadState.Loading -> FullScreenLoading()
+        is LoadState.Error   -> FullScreenError(onRetry = { users.refresh() })
+        else -> Unit
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Loading entire dataset without Paging when the list can grow unbounded
+- Not using `cachedIn(viewModelScope)` — re-fetches from page 1 on rotation
+- Collecting `PagingData` in ViewModel with `collect {}` — it's a one-shot stream
+- Missing load state handling — no loading indicator or error state shown
+- Using `enablePlaceholders = true` without proper placeholder UI
+
+---
+
+## Related Skills
+- `room` — Room PagingSource generation
+- `retrofit` — network data source for PagingSource
+- `repository-pattern` — Pager lives in repository
+- `compose` — LazyColumn with LazyPagingItems
+- `cache-strategy` — offline-first paging with RemoteMediator

package/skills/Data Layer/Proto DataStore/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: proto-datastore
+description: >
+  Proto DataStore setup and usage for typed object persistence in Android.
+  Load this skill when storing complex structured data with type safety,
+  using Protobuf schemas, or when Preferences DataStore is insufficient.
+---
+
+# Proto DataStore
+
+## Overview
+Proto DataStore stores typed objects defined by Protobuf schemas. Unlike Preferences DataStore (which uses string keys), Proto DataStore is strongly typed, schema-enforced, and forward-compatible by design. It is ideal for storing structured settings or state that evolves over time.
+
+---
+
+## Core Principles
+
+- Use Proto DataStore when **type safety and schema evolution** matter
+- Protobuf schemas define the contract — never change field numbers once released
+- Like Preferences DataStore — **one instance per file**, inject via Hilt
+- Always handle **IOException** in Flow collection
+- Add new fields to the proto — never remove or renumber existing fields
+
+---
+
+## Setup
+
+```toml
+# libs.versions.toml
+[versions]
+datastore = "1.1.1"
+protobuf = "4.26.1"
+protobuf-plugin = "0.9.4"
+
+[libraries]
+datastore-proto = { module = "androidx.datastore:datastore", version.ref = "datastore" }
+protobuf-javalite = { module = "com.google.protobuf:protobuf-javalite", version.ref = "protobuf" }
+protobuf-kotlin-lite = { module = "com.google.protobuf:protobuf-kotlin-lite", version.ref = "protobuf" }
+
+[plugins]
+protobuf = { id = "com.google.protobuf", version.ref = "protobuf-plugin" }
+```
+
+```kotlin
+// build.gradle.kts
+plugins {
+    alias(libs.plugins.protobuf)
+}
+
+dependencies {
+    implementation(libs.datastore.proto)
+    implementation(libs.protobuf.javalite)
+    implementation(libs.protobuf.kotlin.lite)
+}
+
+protobuf {
+    protoc {
+        artifact = "com.google.protobuf:protoc:${libs.versions.protobuf.get()}"
+    }
+    generateProtoTasks {
+        all().forEach { task ->
+            task.builtins {
+                create("java") { option("lite") }
+                create("kotlin") { option("lite") }
+            }
+        }
+    }
+}
+```
+
+---
+
+## Proto Schema Definition
+
+```protobuf
+// src/main/proto/user_preferences.proto
+syntax = "proto3";
+option java_package = "com.example.app.datastore";
+option java_multiple_files = true;
+
+message UserPreferences {
+    bool is_dark_mode = 1;
+    string language = 2;
+    int32 font_size = 3;
+    SortOrder sort_order = 4;
+    int64 last_sync_timestamp = 5;
+    // ✅ New fields added here — never remove or renumber existing
+}
+
+enum SortOrder {
+    SORT_ORDER_UNSPECIFIED = 0;
+    SORT_ORDER_ASC = 1;
+    SORT_ORDER_DESC = 2;
+}
+```
+
+---
+
+## Serializer
+
+```kotlin
+// ✅ Implement Serializer for the proto type
+object UserPreferencesSerializer : Serializer<UserPreferences> {
+
+    override val defaultValue: UserPreferences = UserPreferences.getDefaultInstance()
+
+    override suspend fun readFrom(input: InputStream): UserPreferences {
+        try {
+            return UserPreferences.parseFrom(input)
+        } catch (exception: InvalidProtocolBufferException) {
+            throw CorruptionException("Cannot read proto.", exception)
+        }
+    }
+
+    override suspend fun writeTo(t: UserPreferences, output: OutputStream) {
+        t.writeTo(output)
+    }
+}
+```
+
+---
+
+## Creating DataStore
+
+```kotlin
+// ✅ Create via extension property
+val Context.userPreferencesDataStore: DataStore<UserPreferences> by dataStore(
+    fileName = "user_preferences.pb",
+    serializer = UserPreferencesSerializer
+)
+
+// ✅ Provide via Hilt
+@Module
+@InstallIn(SingletonComponent::class)
+object DataStoreModule {
+
+    @Provides
+    @Singleton
+    fun provideUserPreferencesDataStore(
+        @ApplicationContext context: Context
+    ): DataStore<UserPreferences> = context.userPreferencesDataStore
+}
+```
+
+---
+
+## Repository
+
+```kotlin
+class UserPreferencesRepository @Inject constructor(
+    private val dataStore: DataStore<UserPreferences>
+) {
+
+    // ✅ Read — expose as Flow
+    val userPreferences: Flow<UserPreferences> = dataStore.data
+        .catch { e ->
+            if (e is IOException) emit(UserPreferences.getDefaultInstance())
+            else throw e
+        }
+
+    val isDarkMode: Flow<Boolean> = userPreferences.map { it.isDarkMode }
+    val language: Flow<String> = userPreferences.map { it.language }
+
+    // ✅ Write — use updateData or update (proto-specific)
+    suspend fun setDarkMode(enabled: Boolean) {
+        dataStore.updateData { current ->
+            current.toBuilder()
+                .setIsDarkMode(enabled)
+                .build()
+        }
+    }
+
+    suspend fun setLanguage(language: String) {
+        dataStore.updateData { current ->
+            current.toBuilder()
+                .setLanguage(language)
+                .build()
+        }
+    }
+
+    // ✅ Kotlin DSL style (with protobuf-kotlin-lite)
+    suspend fun updatePreferences(update: UserPreferences.Builder.() -> Unit) {
+        dataStore.updateData { current ->
+            current.copy(update)
+        }
+    }
+
+    // Usage:
+    // preferencesRepository.updatePreferences {
+    //     isDarkMode = true
+    //     language = "fa"
+    // }
+}
+```
+
+---
+
+## Schema Evolution Rules
+
+```protobuf
+// ✅ Safe changes
+// - Add new optional fields with new field numbers
+// - Add new enum values (with default 0 for unknown)
+
+// ❌ Breaking changes — NEVER do these to a released schema
+// - Remove a field
+// - Rename a field (the name is cosmetic in proto3, but confusing)
+// - Change a field's type
+// - Reuse a field number for a different field
+
+// ✅ Example: safe evolution
+message UserPreferences {
+    bool is_dark_mode = 1;
+    string language = 2;
+    int32 font_size = 3;       // existing
+    SortOrder sort_order = 4;  // existing
+    // New field in v2 — safe to add
+    bool notifications_enabled = 5;
+    string theme_color = 6;
+}
+```
+
+---
+
+## Proto DataStore vs Preferences DataStore
+
+| | Proto DataStore | Preferences DataStore |
+|--|----------------|----------------------|
+| Type safety | ✅ Strongly typed | ⚠️ Key-based |
+| Schema evolution | ✅ Protobuf rules | ❌ Manual |
+| Setup complexity | ⚠️ Higher | ✅ Simple |
+| Best for | Structured objects | Simple settings |
+
+---
+
+## Anti-Patterns
+
+- Reusing or renumbering proto field numbers — corrupts data for existing users
+- Removing fields from proto — breaks deserialization of existing data
+- Not providing a default value in Serializer — crashes on empty/new install
+- Multiple DataStore instances for the same file — data corruption
+- Storing large binary data in proto — use files or Room instead
+
+---
+
+## Related Skills
+- `datastore` — Preferences DataStore for simple key-value storage
+- `hilt` — singleton DataStore provision
+- `repository-pattern` — wrapping DataStore in a Repository
+- `key-value-store-strategy` — choosing between DataStore variants