android-sdd 1.0.0

package/skills/Architecture/Offline First/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: offline-first
+description: >
+  Offline-first architecture for Android apps.
+  Load this skill when designing apps that must work without network,
+  implementing local-first data access, syncing data with a remote server,
+  handling network availability changes, or designing cache invalidation strategy.
+---
+
+# Offline First
+
+## Overview
+
+Offline-first means the app reads and writes to local storage first. The network is treated as an unreliable sync mechanism — not a requirement. The local database is the single source of truth; the UI observes local data, and a sync engine reconciles local state with the remote server in the background.
+
+---
+
+## Core Principles
+
+- **Local DB is the source of truth** — UI never reads directly from network
+- **Write locally first** — operations succeed immediately, sync later
+- **Observe local, sync remotely** — UI observes Room/DataStore, background sync updates local DB
+- **Surface sync status** — UI shows sync state, errors, last-synced time
+- **Idempotent sync** — syncing the same data twice must not corrupt state
+
+---
+
+## Architecture Pattern
+
+```
+UI → ViewModel → UseCase → Repository
+                              │
+                    ┌─────────┴─────────┐
+                    ▼                   ▼
+              LocalDataSource      RemoteDataSource
+              (Room / DataStore)   (Retrofit / Ktor)
+                    │
+                    ▼
+              Single Source of Truth
+              (UI observes this)
+
+SyncManager (WorkManager) periodically:
+  1. Fetches remote data
+  2. Writes to LocalDataSource
+  3. UI updates automatically via Flow
+```
+
+---
+
+## Repository Implementation
+
+```kotlin
+// ✅ Repository — reads local, triggers sync, exposes Flow
+class UserRepositoryImpl @Inject constructor(
+    private val localDataSource: UserLocalDataSource,
+    private val remoteDataSource: UserRemoteDataSource,
+    private val syncManager: SyncManager
+) : UserRepository {
+
+    // ✅ Always return local Flow — UI updates automatically when sync writes to DB
+    override fun observeUsers(): Flow<List<User>> =
+        localDataSource.observeAll().map { entities -> entities.map { it.toDomain() } }
+
+    // ✅ Read-through cache
+    override suspend fun getUser(id: String): Result<User> = runCatching {
+        localDataSource.getById(id)?.toDomain()
+            ?: fetchAndCacheUser(id)
+    }
+
+    // ✅ Write-through: write locally first, enqueue remote sync
+    override suspend fun updateUser(user: User): Result<Unit> = runCatching {
+        localDataSource.upsert(user.toEntity().copy(syncStatus = SyncStatus.PENDING))
+        syncManager.enqueueUserSync()
+    }
+
+    private suspend fun fetchAndCacheUser(id: String): User {
+        val dto = remoteDataSource.getUser(id)
+        val entity = dto.toDomain().toEntity().copy(syncStatus = SyncStatus.SYNCED)
+        localDataSource.upsert(entity)
+        return entity.toDomain()
+    }
+}
+```
+
+---
+
+## Sync Status Tracking
+
+```kotlin
+// ✅ Track sync state per entity
+enum class SyncStatus { SYNCED, PENDING, FAILED }
+
+@Entity(tableName = "users")
+data class UserEntity(
+    @PrimaryKey val id: String,
+    val name: String,
+    val email: String,
+    val syncStatus: SyncStatus = SyncStatus.SYNCED,
+    val lastModified: Long = System.currentTimeMillis()
+)
+
+// ✅ DAO queries for pending sync
+@Dao
+interface UserDao {
+    @Query("SELECT * FROM users WHERE syncStatus = 'PENDING'")
+    suspend fun getPendingSync(): List<UserEntity>
+
+    @Query("UPDATE users SET syncStatus = :status WHERE id = :id")
+    suspend fun updateSyncStatus(id: String, status: SyncStatus)
+}
+```
+
+---
+
+## Sync Engine with WorkManager
+
+```kotlin
+// ✅ Periodic sync via WorkManager
+class UserSyncWorker @AssistedInject constructor(
+    @Assisted context: Context,
+    @Assisted workerParams: WorkerParameters,
+    private val userRepository: UserRepository,
+    private val remoteDataSource: UserRemoteDataSource,
+    private val localDataSource: UserLocalDataSource
+) : CoroutineWorker(context, workerParams) {
+
+    override suspend fun doWork(): Result {
+        return try {
+            // Push pending changes
+            val pending = localDataSource.getPendingSync()
+            pending.forEach { entity ->
+                remoteDataSource.updateUser(entity.toDto())
+                localDataSource.updateSyncStatus(entity.id, SyncStatus.SYNCED)
+            }
+
+            // Pull remote changes
+            val remoteUsers = remoteDataSource.getUsers()
+            localDataSource.upsertAll(remoteUsers.map { it.toDomain().toEntity() })
+
+            Result.success()
+        } catch (e: Exception) {
+            if (runAttemptCount < 3) Result.retry() else Result.failure()
+        }
+    }
+
+    companion object {
+        fun schedule(workManager: WorkManager) {
+            val request = PeriodicWorkRequestBuilder<UserSyncWorker>(15, TimeUnit.MINUTES)
+                .setConstraints(
+                    Constraints.Builder()
+                        .setRequiredNetworkType(NetworkType.CONNECTED)
+                        .build()
+                )
+                .build()
+            workManager.enqueueUniquePeriodicWork(
+                "user_sync",
+                ExistingPeriodicWorkPolicy.KEEP,
+                request
+            )
+        }
+    }
+}
+```
+
+---
+
+## Network Connectivity Observation
+
+```kotlin
+// ✅ Observe network state
+class NetworkMonitor @Inject constructor(
+    @ApplicationContext private val context: Context
+) {
+    val isOnline: Flow<Boolean> = callbackFlow {
+        val manager = context.getSystemService(ConnectivityManager::class.java)
+
+        val callback = object : ConnectivityManager.NetworkCallback() {
+            override fun onAvailable(network: Network) { trySend(true) }
+            override fun onLost(network: Network) { trySend(false) }
+        }
+
+        val request = NetworkRequest.Builder()
+            .addCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET)
+            .build()
+
+        manager.registerNetworkCallback(request, callback)
+        trySend(manager.activeNetwork != null)
+
+        awaitClose { manager.unregisterNetworkCallback(callback) }
+    }.distinctUntilChanged()
+}
+
+// ✅ Surface network state in ViewModel
+@HiltViewModel
+class HomeViewModel @Inject constructor(
+    private val networkMonitor: NetworkMonitor
+) : ViewModel() {
+
+    val isOffline: StateFlow<Boolean> = networkMonitor.isOnline
+        .map { !it }
+        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), false)
+}
+```
+
+---
+
+## UI: Offline Banner
+
+```kotlin
+// ✅ Show offline indicator when not connected
+@Composable
+fun OfflineBanner(isOffline: Boolean) {
+    AnimatedVisibility(visible = isOffline) {
+        Surface(color = MaterialTheme.colorScheme.errorContainer) {
+            Row(
+                modifier = Modifier
+                    .fillMaxWidth()
+                    .padding(horizontal = 16.dp, vertical = 8.dp),
+                horizontalArrangement = Arrangement.Center
+            ) {
+                Icon(Icons.Default.WifiOff, contentDescription = null)
+                Spacer(Modifier.width(8.dp))
+                Text("You're offline", style = MaterialTheme.typography.labelMedium)
+            }
+        }
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Reading directly from network in ViewModel — always read from local source
+- No sync status tracking — can't tell which records need to be pushed
+- Replacing entire local DB on every sync — causes UI flicker; use upsert
+- Syncing on main thread — always use WorkManager or background coroutine
+- No conflict resolution strategy — when local and remote diverge, there must be a rule
+
+---
+
+## Related Skills
+
+- `room` — local database for offline storage
+- `sync-engine` — advanced sync patterns and conflict resolution
+- `workmanager` — background sync scheduling
+- `conflict-resolution` — handling remote/local data conflicts
+- `repository-pattern` — repository wiring for offline-first
+- `cache-strategy` — cache invalidation and expiry

package/skills/Architecture/Repository Pattern/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: repository-pattern
+description: >
+  Repository pattern for Android data access abstraction.
+  Load this skill when implementing a Repository, defining its interface,
+  coordinating between local and remote data sources, handling caching logic,
+  or structuring the data layer of a feature.
+---
+
+# Repository Pattern
+
+## Overview
+
+The Repository pattern abstracts data sources behind a single interface. The ViewModel and UseCases never know whether data comes from Room, Retrofit, DataStore, or memory cache — they only interact with the Repository interface defined in the Domain layer. The implementation in the Data layer coordinates between local and remote sources.
+
+---
+
+## Core Principles
+
+- Repository **interface** lives in Domain — pure Kotlin, no Android dependencies
+- Repository **implementation** lives in Data — knows about Room, Retrofit, etc.
+- Repository is the **only entry point** to data — no direct DAO or API calls from UseCases
+- Repositories return **Domain models** — never DTOs or Entities
+- One repository per **aggregate root** — not per screen or per DAO
+
+---
+
+## Interface (Domain Layer)
+
+```kotlin
+// ✅ Interface in domain — clean, no framework dependencies
+interface UserRepository {
+    // Reactive — for UI observation
+    fun observeUsers(): Flow<List<User>>
+    fun observeUser(id: String): Flow<User?>
+
+    // Suspend — for one-time reads and writes
+    suspend fun getUser(id: String): Result<User>
+    suspend fun getUsers(): Result<List<User>>
+    suspend fun createUser(user: User): Result<User>
+    suspend fun updateUser(user: User): Result<Unit>
+    suspend fun deleteUser(id: String): Result<Unit>
+
+    // Domain operations
+    suspend fun searchUsers(query: String): Result<List<User>>
+    suspend fun syncUsers(): Result<Unit>
+}
+```
+
+---
+
+## Implementation (Data Layer)
+
+```kotlin
+// ✅ Implementation in data layer — coordinates sources
+class UserRepositoryImpl @Inject constructor(
+    private val userDao: UserDao,
+    private val userApiService: UserApiService,
+    private val dispatcher: CoroutineDispatcher = Dispatchers.IO
+) : UserRepository {
+
+    // ✅ Observe local DB — UI updates automatically when DB changes
+    override fun observeUsers(): Flow<List<User>> =
+        userDao.observeAll()
+            .map { entities -> entities.map { it.toDomain() } }
+            .flowOn(dispatcher)
+
+    // ✅ Cache-first read
+    override suspend fun getUser(id: String): Result<User> = withContext(dispatcher) {
+        runCatching {
+            userDao.getById(id)?.toDomain()
+                ?: fetchAndCacheUser(id)
+        }
+    }
+
+    // ✅ Write to local + remote
+    override suspend fun createUser(user: User): Result<User> = withContext(dispatcher) {
+        runCatching {
+            val dto = userApiService.createUser(user.toCreateRequest())
+            val created = dto.toDomain()
+            userDao.insert(created.toEntity())
+            created
+        }
+    }
+
+    override suspend fun updateUser(user: User): Result<Unit> = withContext(dispatcher) {
+        runCatching {
+            userApiService.updateUser(user.id, user.toUpdateRequest())
+            userDao.upsert(user.toEntity())
+        }
+    }
+
+    override suspend fun deleteUser(id: String): Result<Unit> = withContext(dispatcher) {
+        runCatching {
+            userApiService.deleteUser(id)
+            userDao.deleteById(id)
+        }
+    }
+
+    override suspend fun syncUsers(): Result<Unit> = withContext(dispatcher) {
+        runCatching {
+            val dtos = userApiService.getUsers()
+            val entities = dtos.map { it.toDomain().toEntity() }
+            userDao.replaceAll(entities)
+        }
+    }
+
+    private suspend fun fetchAndCacheUser(id: String): User {
+        val dto = userApiService.getUser(id)
+        val domain = dto.toDomain()
+        userDao.insert(domain.toEntity())
+        return domain
+    }
+}
+```
+
+---
+
+## Hilt Binding
+
+```kotlin
+// ✅ Bind interface to implementation
+@Module
+@InstallIn(SingletonComponent::class)
+abstract class UserRepositoryModule {
+
+    @Binds
+    @Singleton
+    abstract fun bindUserRepository(
+        impl: UserRepositoryImpl
+    ): UserRepository
+}
+```
+
+---
+
+## Repository Strategies
+
+```kotlin
+// ✅ Strategy 1: Network-first (always fresh data)
+override suspend fun getUser(id: String): Result<User> = runCatching {
+    val dto = userApiService.getUser(id)
+    val domain = dto.toDomain()
+    userDao.upsert(domain.toEntity())
+    domain
+}
+
+// ✅ Strategy 2: Cache-first (fast, offline-capable)
+override suspend fun getUser(id: String): Result<User> = runCatching {
+    userDao.getById(id)?.toDomain() ?: run {
+        val dto = userApiService.getUser(id)
+        val domain = dto.toDomain()
+        userDao.insert(domain.toEntity())
+        domain
+    }
+}
+
+// ✅ Strategy 3: Cache-then-network (show cached, refresh in background)
+override fun observeUserWithRefresh(id: String): Flow<User> = flow {
+    userDao.getById(id)?.toDomain()?.let { emit(it) }
+    val refreshed = userApiService.getUser(id).toDomain()
+    userDao.upsert(refreshed.toEntity())
+    emit(refreshed)
+}
+```
+
+---
+
+## Fake Repository for Testing
+
+```kotlin
+// ✅ Fake implementation for unit tests — no Room, no Retrofit
+class FakeUserRepository : UserRepository {
+    private val users = MutableStateFlow<List<User>>(emptyList())
+    var shouldThrow = false
+
+    override fun observeUsers(): Flow<List<User>> = users
+
+    override suspend fun getUser(id: String): Result<User> {
+        if (shouldThrow) return Result.failure(Exception("Network error"))
+        return users.value.find { it.id == id }
+            ?.let { Result.success(it) }
+            ?: Result.failure(Exception("Not found"))
+    }
+
+    override suspend fun createUser(user: User): Result<User> {
+        users.update { it + user }
+        return Result.success(user)
+    }
+
+    fun emit(userList: List<User>) {
+        users.value = userList
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- DAO called directly from ViewModel or UseCase — always go through Repository
+- Repository returning Entity or DTO — always map to Domain model before returning
+- One Repository per screen — one Repository per aggregate root (User, Order, Product)
+- Repository containing UI logic — Repository only handles data access and mapping
+- Not using `flowOn(dispatcher)` — DB and network operations must not run on Main thread
+
+---
+
+## Related Skills
+
+- `clean-architecture` — where Repository fits in layer structure
+- `dao` — DAO patterns the Repository coordinates
+- `dto-mapping` — mapping between DTO/Entity and Domain model
+- `use-case-design` — UseCases that call Repositories
+- `cache-strategy` — cache invalidation and expiry policies
+- `offline-first` — Repository design for offline-capable apps