android-sdd 1.0.0

package/skills/Concurrency/Coroutine/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: coroutine
+description: >
+  Kotlin Coroutines fundamentals and patterns for Android development.
+  Load this skill when launching coroutines, choosing the right scope,
+  managing coroutine lifecycle, handling exceptions, or structuring
+  async operations with suspend functions.
+---
+
+# Coroutine
+
+## Overview
+
+Kotlin Coroutines provide a structured way to write asynchronous code sequentially. On Android, coroutines are the standard for all async operations — network calls, database queries, and background work. Every coroutine must be launched in a scope that controls its lifecycle.
+
+---
+
+## Core Principles
+
+- Always use the **narrowest scope** available — `viewModelScope`, `lifecycleScope`, not `GlobalScope`
+- Use `Dispatchers.IO` for blocking I/O, `Dispatchers.Default` for CPU-heavy work
+- Never use `GlobalScope` — it has no lifecycle and can't be cancelled
+- Exceptions in coroutines must be handled explicitly — they don't propagate like regular exceptions
+- Use `supervisorScope` when child failures should not cancel siblings
+
+---
+
+## Scope Selection
+
+```kotlin
+// ✅ viewModelScope — cancelled when ViewModel is cleared
+class UserViewModel : ViewModel() {
+    fun loadUser() {
+        viewModelScope.launch {
+            // auto-cancelled when ViewModel is destroyed
+        }
+    }
+}
+
+// ✅ lifecycleScope — cancelled when lifecycle is destroyed
+class UserFragment : Fragment() {
+    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
+        viewLifecycleOwner.lifecycleScope.launch {
+            repeatOnLifecycle(Lifecycle.State.STARTED) {
+                // cancelled when below STARTED
+            }
+        }
+    }
+}
+
+// ✅ Custom scope — for non-lifecycle components
+@Singleton
+class SyncManager @Inject constructor() {
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
+
+    fun startSync() {
+        scope.launch { /* ... */ }
+    }
+
+    fun cancel() {
+        scope.cancel()
+    }
+}
+
+// ❌ Never use GlobalScope
+GlobalScope.launch { /* no lifecycle, no cancellation */ }
+```
+
+---
+
+## Dispatcher Selection
+
+```kotlin
+// ✅ IO — network, database, file operations
+viewModelScope.launch(Dispatchers.IO) {
+    val users = userDao.getAll()
+}
+
+// ✅ Default — CPU-intensive work (sorting, parsing, computation)
+viewModelScope.launch(Dispatchers.Default) {
+    val sorted = largeList.sortedBy { it.name }
+}
+
+// ✅ Main — UI updates (usually implicit in viewModelScope)
+viewModelScope.launch(Dispatchers.Main) {
+    binding.textView.text = "Updated"
+}
+
+// ✅ withContext — switch dispatcher inside a coroutine
+suspend fun processData(): List<Item> = withContext(Dispatchers.Default) {
+    rawData.map { parse(it) }
+}
+```
+
+---
+
+## Exception Handling
+
+```kotlin
+// ✅ try/catch inside launch
+viewModelScope.launch {
+    try {
+        val user = repository.getUser(id)
+        _state.value = UiState.Success(user)
+    } catch (e: Exception) {
+        _state.value = UiState.Error(e.message ?: "Error")
+    }
+}
+
+// ✅ CoroutineExceptionHandler for unhandled exceptions
+val handler = CoroutineExceptionHandler { _, throwable ->
+    Timber.e(throwable, "Unhandled coroutine exception")
+}
+
+viewModelScope.launch(handler) {
+    riskyOperation()
+}
+
+// ✅ runCatching — functional style
+val result = runCatching { repository.getUser(id) }
+result.onSuccess { _state.value = UiState.Success(it) }
+result.onFailure { _state.value = UiState.Error(it.message ?: "Error") }
+
+// ❌ async exception — not caught by try/catch on launch
+val deferred = viewModelScope.async { riskyOperation() }
+deferred.await()  // exception thrown here — wrap in try/catch
+```
+
+---
+
+## Parallel Execution
+
+```kotlin
+// ✅ Run multiple operations in parallel with async
+suspend fun loadDashboard(): Dashboard {
+    return coroutineScope {
+        val users = async { userRepository.getUsers() }
+        val orders = async { orderRepository.getOrders() }
+        val stats = async { statsRepository.getStats() }
+
+        Dashboard(
+            users = users.await().getOrDefault(emptyList()),
+            orders = orders.await().getOrDefault(emptyList()),
+            stats = stats.await().getOrNull()
+        )
+    }
+}
+
+// ✅ supervisorScope — one failure doesn't cancel others
+suspend fun loadOptionalData() = supervisorScope {
+    val primary = async { primaryRepository.getData() }
+    val secondary = async { secondaryRepository.getData() }  // failure here won't cancel primary
+
+    PrimaryData(
+        main = primary.await(),
+        extra = runCatching { secondary.await() }.getOrNull()
+    )
+}
+```
+
+---
+
+## Cancellation
+
+```kotlin
+// ✅ Check cancellation in long loops
+suspend fun processItems(items: List<Item>) {
+    items.forEach { item ->
+        ensureActive()  // throws CancellationException if cancelled
+        processItem(item)
+    }
+}
+
+// ✅ withTimeout
+suspend fun fetchWithTimeout(): User = withTimeout(5_000) {
+    api.getUser(id)
+}
+
+// ✅ withTimeoutOrNull — returns null on timeout
+val user = withTimeoutOrNull(5_000) { api.getUser(id) }
+```
+
+---
+
+## Anti-Patterns
+
+- Using `GlobalScope` — no lifecycle management, can't be cancelled
+- Launching coroutines without handling exceptions — silent failures
+- Calling blocking functions (`Thread.sleep`, blocking I/O) without `Dispatchers.IO`
+- Using `runBlocking` in Android code outside of tests — blocks the thread
+- Ignoring `CancellationException` in catch blocks — breaks structured concurrency
+
+---
+
+## Related Skills
+
+- `flow` — reactive streams with coroutines
+- `structured-concurrency` — parent-child coroutine relationships
+- `viewmodel` — viewModelScope usage
+- `lifecycle` — lifecycleScope and repeatOnLifecycle

package/skills/Concurrency/Flow/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: flow
+description: >
+  Kotlin Flow for reactive streams in Android.
+  Load this skill when building cold streams, transforming data pipelines,
+  collecting flows with lifecycle awareness, combining multiple flows,
+  or converting callbacks to Flow.
+---
+
+# Flow
+
+## Overview
+
+Kotlin Flow is a cold, asynchronous stream built on coroutines. It emits values sequentially and is collected in a coroutine. Flow is the standard for reactive data streams in Android — from database queries to UI state. Unlike LiveData, Flow is lifecycle-agnostic and must be collected with lifecycle awareness in the UI layer.
+
+---
+
+## Core Principles
+
+- Flow is **cold** — it only runs when collected
+- Collect flows in the UI with `collectAsStateWithLifecycle` (Compose) or `repeatOnLifecycle`
+- Use `flowOn` to switch the dispatcher for upstream operators — not for collection
+- Prefer `StateFlow` for UI state and `SharedFlow` for events — not plain `Flow`
+- Use `callbackFlow` to bridge callback-based APIs to Flow
+
+---
+
+## Basic Flow
+
+```kotlin
+// ✅ Cold flow — runs fresh for each collector
+fun getUsers(): Flow<List<User>> = flow {
+    while (true) {
+        emit(repository.getUsers())
+        delay(30_000)  // poll every 30s
+    }
+}
+
+// ✅ Flow from Room — already a Flow
+fun getUsersFromDb(): Flow<List<User>> = userDao.getAllUsers()  // Room emits on every change
+```
+
+---
+
+## Flow Operators
+
+```kotlin
+// ✅ Transform
+val userNames: Flow<List<String>> = getUsersFlow()
+    .map { users -> users.map { it.name } }
+
+// ✅ Filter
+val activeUsers: Flow<List<User>> = getUsersFlow()
+    .map { users -> users.filter { it.isActive } }
+
+// ✅ debounce — wait for stable value
+val searchResults: Flow<List<User>> = searchQuery
+    .debounce(300)
+    .distinctUntilChanged()
+    .flatMapLatest { query -> searchRepository.search(query) }
+
+// ✅ combine — merge two flows into one
+val uiState: Flow<UiState> = combine(usersFlow, filtersFlow) { users, filters ->
+    UiState(users = users.filter { filters.matches(it) })
+}
+
+// ✅ zip — pair emissions one-to-one
+val paired: Flow<Pair<User, Order>> = usersFlow.zip(ordersFlow) { user, order ->
+    user to order
+}
+
+// ✅ flatMapLatest — cancel previous and switch to latest
+val results: Flow<List<Result>> = queryFlow
+    .flatMapLatest { query -> searchUseCase(query) }
+```
+
+---
+
+## Error Handling
+
+```kotlin
+// ✅ catch — handle errors in the stream
+getUsersFlow()
+    .catch { error ->
+        emit(emptyList())  // emit fallback
+        Timber.e(error)
+    }
+    .collect { users -> render(users) }
+
+// ✅ retry
+getUsersFlow()
+    .retry(3) { cause -> cause is IOException }
+    .collect { users -> render(users) }
+
+// ✅ onEach for side effects
+getUsersFlow()
+    .onEach { users -> Timber.d("Received ${users.size} users") }
+    .catch { Timber.e(it) }
+    .collect { render(it) }
+```
+
+---
+
+## Lifecycle-Aware Collection
+
+```kotlin
+// ✅ Compose — collectAsStateWithLifecycle
+@Composable
+fun UserListScreen(viewModel: UserListViewModel = hiltViewModel()) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+    UserListContent(state)
+}
+
+// ✅ Fragment — repeatOnLifecycle
+viewLifecycleOwner.lifecycleScope.launch {
+    repeatOnLifecycle(Lifecycle.State.STARTED) {
+        viewModel.state.collect { render(it) }
+    }
+}
+
+// ❌ Never collect without lifecycle awareness in UI
+lifecycleScope.launch {
+    viewModel.state.collect { render(it) }  // doesn't cancel when backgrounded
+}
+```
+
+---
+
+## callbackFlow — Bridge Callbacks to Flow
+
+```kotlin
+// ✅ Convert callback API to Flow
+fun listenToLocation(): Flow<Location> = callbackFlow {
+    val callback = object : LocationCallback() {
+        override fun onLocationResult(result: LocationResult) {
+            result.lastLocation?.let { trySend(it) }
+        }
+    }
+
+    locationManager.requestUpdates(callback)
+
+    awaitClose {
+        locationManager.removeUpdates(callback)  // cleanup on cancellation
+    }
+}
+```
+
+---
+
+## flowOn — Upstream Dispatcher
+
+```kotlin
+// ✅ flowOn changes dispatcher for everything upstream of it
+val processedData: Flow<List<Item>> = rawDataFlow
+    .map { parseHeavy(it) }      // runs on Default
+    .filter { it.isValid }        // runs on Default
+    .flowOn(Dispatchers.Default)  // applies to map + filter above
+    .map { it.toUiModel() }       // runs on collection dispatcher
+```
+
+---
+
+## Anti-Patterns
+
+- Collecting flow without lifecycle awareness in Android UI — subscribes even in background
+- Using `flow { }` for hot data that should be `StateFlow` or `SharedFlow`
+- Calling `.collect {}` directly in a composable body — use `collectAsStateWithLifecycle`
+- Using `flatMapMerge` for search/autocomplete — use `flatMapLatest` to cancel previous
+- Not calling `awaitClose` in `callbackFlow` — resource leak on cancellation
+
+---
+
+## Related Skills
+
+- `stateflow` — hot state holder for UI state
+- `sharedflow` — hot shared stream for events
+- `coroutine` — coroutine fundamentals
+- `lifecycle` — lifecycle-aware collection patterns
+- `reactive-streams` — broader reactive programming concepts

package/skills/Concurrency/Mutex Strategy/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: mutex-strategy
+description: >
+  Mutex and coroutine-based locking strategies in Android.
+  Load this skill when protecting shared mutable state across coroutines,
+  preventing concurrent access to a critical section, serializing operations,
+  or avoiding race conditions in async code.
+---
+
+# Mutex Strategy
+
+## Overview
+`Mutex` is a coroutine-friendly mutual exclusion lock. Unlike Java's `synchronized`, it suspends rather than blocks the thread while waiting for the lock. It is the correct tool for protecting shared mutable state that multiple coroutines may access concurrently.
+
+---
+
+## Core Principles
+
+- Use `Mutex` instead of `synchronized` in coroutine code — `synchronized` blocks the thread
+- Keep the critical section **as short as possible** — don't do heavy work inside `withLock`
+- Never `withLock` on the main dispatcher for blocking operations
+- Use `Mutex` for single-resource protection — use `Semaphore` for limiting concurrency count
+- Prefer immutable state + atomic updates where possible — avoid Mutex if you can
+
+---
+
+## Basic Mutex Usage
+
+```kotlin
+// ✅ Protect shared mutable state
+class TokenCache @Inject constructor() {
+    private val mutex = Mutex()
+    private var cachedToken: String? = null
+    private var tokenExpiry: Long = 0L
+
+    suspend fun getToken(fetchToken: suspend () -> String): String {
+        mutex.withLock {
+            val now = System.currentTimeMillis()
+            if (cachedToken != null && now < tokenExpiry) {
+                return cachedToken!!
+            }
+            val newToken = fetchToken()
+            cachedToken = newToken
+            tokenExpiry = now + 3_600_000L  // 1 hour
+            return newToken
+        }
+    }
+
+    suspend fun invalidate() {
+        mutex.withLock {
+            cachedToken = null
+            tokenExpiry = 0L
+        }
+    }
+}
+```
+
+---
+
+## Token Refresh with Mutex
+
+```kotlin
+// ✅ Prevent multiple simultaneous token refreshes
+class AuthRepository @Inject constructor(
+    private val api: AuthApi,
+    private val tokenStorage: TokenStorage
+) {
+    private val refreshMutex = Mutex()
+
+    suspend fun refreshToken(): String? {
+        return refreshMutex.withLock {
+            // Check if another coroutine already refreshed while we were waiting
+            val currentToken = tokenStorage.getAccessToken()
+            if (currentToken != null && !isTokenExpired(currentToken)) {
+                return@withLock currentToken
+            }
+
+            runCatching {
+                val response = api.refresh(tokenStorage.getRefreshToken() ?: return@withLock null)
+                tokenStorage.saveTokens(response.accessToken, response.refreshToken)
+                response.accessToken
+            }.getOrNull()
+        }
+    }
+}
+```
+
+---
+
+## Semaphore — Limit Concurrency
+
+```kotlin
+// ✅ Semaphore — allow max N concurrent operations
+class ImageProcessor @Inject constructor() {
+    // Max 3 concurrent image processing operations
+    private val semaphore = Semaphore(3)
+
+    suspend fun processImage(imageUri: Uri): Bitmap {
+        return semaphore.withPermit {
+            heavyImageProcessing(imageUri)
+        }
+    }
+}
+
+// ✅ Rate-limited API calls
+class ApiThrottler(maxConcurrent: Int = 5) {
+    private val semaphore = Semaphore(maxConcurrent)
+
+    suspend fun <T> throttled(call: suspend () -> T): T {
+        return semaphore.withPermit { call() }
+    }
+}
+```
+
+---
+
+## Mutex vs Other Synchronization
+
+| Tool | Suspends? | Use For |
+|------|-----------|---------|
+| `Mutex` | ✅ Yes | Single-resource exclusive access |
+| `Semaphore` | ✅ Yes | Limit number of concurrent operations |
+| `synchronized` | ❌ Blocks thread | Non-coroutine Java interop only |
+| `AtomicInteger` | N/A | Simple counter without lock |
+| `StateFlow.update` | N/A | Atomic state updates |
+
+---
+
+## Atomic Alternatives
+
+```kotlin
+// ✅ AtomicInteger for simple counters — no Mutex needed
+class RequestCounter {
+    private val count = AtomicInteger(0)
+    fun increment() = count.incrementAndGet()
+    fun get() = count.get()
+}
+
+// ✅ StateFlow.update for UI state — thread-safe without Mutex
+private val _state = MutableStateFlow(UiState())
+fun updateUser(user: User) {
+    _state.update { it.copy(user = user) }  // atomic — no Mutex needed
+}
+```
+
+---
+
+## tryLock — Non-Blocking Attempt
+
+```kotlin
+// ✅ tryLock — skip if already locked
+class PeriodicSync @Inject constructor() {
+    private val syncMutex = Mutex()
+
+    suspend fun trySyncNow() {
+        if (!syncMutex.tryLock()) {
+            // sync already in progress — skip
+            return
+        }
+        try {
+            performSync()
+        } finally {
+            syncMutex.unlock()
+        }
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Using `synchronized {}` in coroutine code — blocks the thread, not coroutine-friendly
+- Long operations inside `withLock` — holds the lock too long, blocks other coroutines
+- Nested `withLock` calls on the same Mutex — deadlock
+- Using Mutex for simple counter updates — use `AtomicInteger` instead
+- Not releasing the lock in finally — use `withLock` extension, not manual lock/unlock
+
+---
+
+## Related Skills
+- `coroutine` — coroutine fundamentals
+- `structured-concurrency` — parent-child relationships and cancellation
+- `synchronization-policy` — broader thread safety strategy
+- `authentication` — token refresh with Mutex