android-sdd 1.0.0

package/skills/Architecture/Side Effect Management/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: side-effect-management
+description: >
+  Side effect handling patterns in Android/Kotlin across all layers.
+  Load this skill when dealing with one-time events, navigation triggers,
+  analytics calls, toast/snackbar messages, or any operation that causes
+  observable change outside the current scope.
+---
+
+# Side Effect Management
+
+## Overview
+
+A side effect is any operation that changes state or causes observable behavior outside the current function's scope — navigation, showing a toast, logging, analytics, network calls triggered by UI events. Managing side effects correctly prevents duplication, memory leaks, and lifecycle bugs.
+
+---
+
+## Core Principles
+
+- Side effects must be **lifecycle-aware** — never fire after the UI is gone
+- **One-time events** (navigation, snackbar) must never be modeled as persistent state
+- Side effects in ViewModel are communicated to UI via **SharedFlow events**
+- Side effects in Compose use `LaunchedEffect`, `SideEffect`, or `DisposableEffect`
+- Never trigger side effects inside `map {}`, `combine {}`, or composable body directly
+
+---
+
+## Layer Responsibility
+
+| Layer        | Side Effects                                | How                                    |
+| ------------ | ------------------------------------------- | -------------------------------------- |
+| UI (Compose) | Navigation, show dialog, request permission | `LaunchedEffect`, collect `SharedFlow` |
+| ViewModel    | Emit one-time events to UI                  | `MutableSharedFlow`                    |
+| UseCase      | None — pure logic only                      | —                                      |
+| Repository   | Logging, cache invalidation                 | Contained within repository            |
+| Data Source  | Network call, DB write                      | Result returned, not side-effected     |
+
+---
+
+## ViewModel — One-Time Events via SharedFlow
+
+```kotlin
+// ✅ Sealed class for typed events
+sealed class UserDetailEvent {
+    data class NavigateToEdit(val userId: String) : UserDetailEvent()
+    data class ShowSnackbar(val message: String) : UserDetailEvent()
+    object NavigateBack : UserDetailEvent()
+    object ShowDeleteConfirmation : UserDetailEvent()
+}
+
+@HiltViewModel
+class UserDetailViewModel @Inject constructor(
+    private val repository: UserRepository
+) : ViewModel() {
+
+    private val _state = MutableStateFlow(UserDetailUiState())
+    val state: StateFlow<UserDetailUiState> = _state.asStateFlow()
+
+    // ✅ SharedFlow for events — replay = 0, never persisted
+    private val _events = MutableSharedFlow<UserDetailEvent>()
+    val events: SharedFlow<UserDetailEvent> = _events.asSharedFlow()
+
+    fun onEditClicked() {
+        viewModelScope.launch {
+            _events.emit(UserDetailEvent.NavigateToEdit(state.value.userId))
+        }
+    }
+
+    fun onDeleteClicked() {
+        viewModelScope.launch {
+            _events.emit(UserDetailEvent.ShowDeleteConfirmation)
+        }
+    }
+
+    fun onDeleteConfirmed() {
+        viewModelScope.launch {
+            repository.deleteUser(state.value.userId)
+                .onSuccess {
+                    _events.emit(UserDetailEvent.NavigateBack)
+                }
+                .onFailure { error ->
+                    _events.emit(UserDetailEvent.ShowSnackbar(error.message ?: "Error"))
+                }
+        }
+    }
+}
+```
+
+---
+
+## UI — Collecting Events
+
+```kotlin
+@Composable
+fun UserDetailScreen(
+    navController: NavController,
+    viewModel: UserDetailViewModel = hiltViewModel()
+) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+    val snackbarHostState = remember { SnackbarHostState() }
+    val lifecycleOwner = LocalLifecycleOwner.current
+
+    // ✅ Collect one-time events with lifecycle awareness
+    LaunchedEffect(Unit) {
+        viewModel.events
+            .flowWithLifecycle(lifecycleOwner.lifecycle, Lifecycle.State.STARTED)
+            .collect { event ->
+                when (event) {
+                    is UserDetailEvent.NavigateToEdit ->
+                        navController.navigate(EditUserRoute(event.userId))
+                    is UserDetailEvent.ShowSnackbar ->
+                        snackbarHostState.showSnackbar(event.message)
+                    is UserDetailEvent.NavigateBack ->
+                        navController.navigateUp()
+                    is UserDetailEvent.ShowDeleteConfirmation ->
+                        // show dialog via local state
+                        showDeleteDialog = true
+                }
+            }
+    }
+
+    Scaffold(snackbarHost = { SnackbarHost(snackbarHostState) }) { padding ->
+        UserDetailContent(
+            state = state,
+            onEditClick = viewModel::onEditClicked,
+            onDeleteClick = viewModel::onDeleteClicked,
+            modifier = Modifier.padding(padding)
+        )
+    }
+}
+```
+
+---
+
+## Compose Side Effects
+
+```kotlin
+// ✅ LaunchedEffect — coroutine side effect, runs when key changes
+@Composable
+fun AutoScrollList(scrollToIndex: Int) {
+    val listState = rememberLazyListState()
+
+    LaunchedEffect(scrollToIndex) {
+        listState.animateScrollToItem(scrollToIndex)
+    }
+}
+
+// ✅ SideEffect — sync Compose state to external system on every recomposition
+@Composable
+fun AnalyticsTracker(screenName: String) {
+    SideEffect {
+        analytics.setCurrentScreen(screenName)
+    }
+}
+
+// ✅ DisposableEffect — register/unregister listener
+@Composable
+fun NetworkMonitor(onNetworkChange: (Boolean) -> Unit) {
+    val context = LocalContext.current
+    DisposableEffect(Unit) {
+        val callback = object : ConnectivityManager.NetworkCallback() {
+            override fun onAvailable(network: Network) = onNetworkChange(true)
+            override fun onLost(network: Network) = onNetworkChange(false)
+        }
+        val cm = context.getSystemService(ConnectivityManager::class.java)
+        cm.registerDefaultNetworkCallback(callback)
+        onDispose { cm.unregisterNetworkCallback(callback) }
+    }
+}
+
+// ✅ rememberCoroutineScope — imperative trigger from event handler
+@Composable
+fun SaveButton(viewModel: FormViewModel) {
+    val scope = rememberCoroutineScope()
+    val snackbarHostState = remember { SnackbarHostState() }
+
+    Button(onClick = {
+        scope.launch {
+            snackbarHostState.showSnackbar("Saved!")
+        }
+    }) {
+        Text("Save")
+    }
+}
+```
+
+---
+
+## Analytics as Side Effect
+
+```kotlin
+// ✅ Analytics in ViewModel — after state change, before emitting event
+fun onPurchaseCompleted(orderId: String) {
+    viewModelScope.launch {
+        val result = repository.completeOrder(orderId)
+        result.onSuccess {
+            analytics.track("purchase_completed", mapOf("order_id" to orderId))
+            _events.emit(OrderEvent.NavigateToConfirmation(orderId))
+        }
+    }
+}
+
+// ❌ Analytics inside UseCase — use cases must be pure
+class CompleteOrderUseCase {
+    operator fun invoke(orderId: String) {
+        // ❌ Don't call analytics here — side effect in wrong layer
+        analytics.track("purchase_completed")
+    }
+}
+```
+
+---
+
+## Side Effects in Flow Pipelines
+
+```kotlin
+// ✅ onEach — non-transforming side effect in flow
+fun observeOrders(): Flow<List<Order>> =
+    repository.observeOrders()
+        .onEach { orders ->
+            if (orders.any { it.isUrgent }) {
+                notificationManager.showUrgentOrderAlert()
+            }
+        }
+
+// ✅ onStart / onCompletion — lifecycle side effects
+fun fetchUsers(): Flow<List<User>> =
+    repository.fetchUsers()
+        .onStart { analytics.track("users_fetch_started") }
+        .onCompletion { error ->
+            if (error == null) analytics.track("users_fetch_success")
+        }
+        .catch { error ->
+            logger.error("Failed to fetch users", error)
+            emit(emptyList())
+        }
+```
+
+---
+
+## Preventing Duplicate Events
+
+```kotlin
+// ✅ SharedFlow with replay=0 — events are NOT replayed on new collectors
+private val _events = MutableSharedFlow<Event>(
+    replay = 0,
+    extraBufferCapacity = 1,
+    onBufferOverflow = BufferOverflow.DROP_OLDEST
+)
+
+// ✅ Channel for guaranteed delivery (but only one collector)
+private val _events = Channel<Event>(Channel.BUFFERED)
+val events = _events.receiveAsFlow()
+
+// ❌ StateFlow for events — replays last event on rotation
+private val _navigateTo = MutableStateFlow<Route?>(null)  // wrong — replays on rotation
+```
+
+---
+
+## Anti-Patterns
+
+- Modeling navigation/snackbar as state (`UiState.navigateTo`) — replays on rotation
+- Calling `analytics.track()` directly inside a composable body
+- Triggering side effects inside `map {}` / `combine {}` operators
+- Using `GlobalScope` for event emission — not lifecycle-aware
+- Forgetting `flowWithLifecycle` when collecting events — fires in background
+- Using `replay = 1` on event SharedFlow — event fires again on re-subscription
+
+---
+
+## Related Skills
+
+- `reactive-state-management` — state vs events distinction
+- `compose` — LaunchedEffect, SideEffect, DisposableEffect
+- `coroutine` — scope and dispatcher for side effects
+- `mvvm` — ViewModel event emission patterns
+- `use-case-design` — keeping use cases free of side effects

package/skills/Architecture/State Management/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: state-management
+description: >
+  State management patterns for Android with Compose and ViewModel.
+  Load this skill when designing UI state models, choosing between
+  StateFlow vs SharedFlow vs Channel, managing loading/error/success states,
+  handling state persistence, or combining multiple state sources.
+---
+
+# State Management
+
+## Overview
+
+State management defines where state lives, how it flows to the UI, and how it changes. In Android with Compose, state lives in the ViewModel as `StateFlow`, flows to composables via `collectAsStateWithLifecycle()`, and changes only through explicit events or function calls. One-time events (navigation, toasts) use `Channel` — not `StateFlow`.
+
+---
+
+## Core Principles
+
+- **Single source of truth** — one `StateFlow<UiState>` per screen
+- **Immutable state** — always produce a new state via `copy()`, never mutate
+- **StateFlow for persistent state** — last value replayed to new collectors
+- **Channel for one-time events** — not replayed, not missed when buffered
+- **`collectAsStateWithLifecycle()`** — lifecycle-aware collection in Compose
+
+---
+
+## State Shape Patterns
+
+```kotlin
+// ✅ Pattern 1: Sealed class — for screens with distinct modes
+sealed interface ProductDetailUiState {
+    data object Loading : ProductDetailUiState
+    data class Success(val product: Product, val isFavorite: Boolean) : ProductDetailUiState
+    data class Error(val message: String) : ProductDetailUiState
+}
+
+// ✅ Pattern 2: Data class — for screens with parallel state fields
+data class ProductListUiState(
+    val isLoading: Boolean = false,
+    val products: List<Product> = emptyList(),
+    val error: String? = null,
+    val searchQuery: String = "",
+    val selectedFilter: Filter = Filter.All,
+    val totalCount: Int = 0
+)
+
+// When to use which:
+// Sealed class → screen has mutually exclusive modes (loading OR content OR error)
+// Data class → screen has multiple independent fields shown simultaneously
+```
+
+---
+
+## StateFlow Patterns
+
+```kotlin
+// ✅ Simple StateFlow
+private val _state = MutableStateFlow(ProductListUiState())
+val state: StateFlow<ProductListUiState> = _state.asStateFlow()
+
+// Update with copy()
+_state.update { it.copy(isLoading = true) }
+
+// ✅ StateFlow from Flow (derived state)
+val state: StateFlow<ProductListUiState> =
+    repository.observeProducts()
+        .map { products -> ProductListUiState(products = products) }
+        .catch { e -> emit(ProductListUiState(error = e.message)) }
+        .stateIn(
+            scope = viewModelScope,
+            started = SharingStarted.WhileSubscribed(5_000),  // cancel 5s after UI gone
+            initialValue = ProductListUiState(isLoading = true)
+        )
+
+// ✅ Combining multiple sources
+val state: StateFlow<DashboardUiState> = combine(
+    userRepository.observeCurrentUser(),
+    orderRepository.observeRecentOrders(),
+    notificationRepository.observeUnreadCount()
+) { user, orders, unreadCount ->
+    DashboardUiState(
+        userName = user.name,
+        recentOrders = orders,
+        unreadNotifications = unreadCount
+    )
+}.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), DashboardUiState())
+```
+
+---
+
+## One-Time Events: Channel
+
+```kotlin
+// ✅ Use Channel for events that happen exactly once
+sealed interface ProductEvent {
+    data object NavigateToCart : ProductEvent
+    data class ShowSnackbar(val message: String) : ProductEvent
+    data class NavigateToDetail(val productId: String) : ProductEvent
+}
+
+private val _events = Channel<ProductEvent>(Channel.BUFFERED)
+val events: Flow<ProductEvent> = _events.receiveAsFlow()
+
+fun onAddToCart(product: Product) {
+    viewModelScope.launch {
+        addToCartUseCase(product).fold(
+            onSuccess = { _events.send(ProductEvent.ShowSnackbar("Added to cart")) },
+            onFailure = { _events.send(ProductEvent.ShowSnackbar("Failed to add")) }
+        )
+    }
+}
+
+// ✅ Collect events in Compose
+LaunchedEffect(Unit) {
+    viewModel.events.collect { event ->
+        when (event) {
+            is ProductEvent.NavigateToCart -> navController.navigate(CartRoute)
+            is ProductEvent.ShowSnackbar -> snackbarHost.showSnackbar(event.message)
+            is ProductEvent.NavigateToDetail -> navController.navigate(DetailRoute(event.productId))
+        }
+    }
+}
+```
+
+---
+
+## StateFlow vs SharedFlow vs Channel
+
+|                     | StateFlow  | SharedFlow   | Channel            |
+| ------------------- | ---------- | ------------ | ------------------ |
+| Replays last value  | ✅ Always   | Configurable | ❌ Never            |
+| Has initial value   | ✅ Required | ❌ No         | ❌ No               |
+| Multiple collectors | ✅          | ✅            | ❌ Single consumer  |
+| Use for             | UI state   | Event bus    | One-time UI events |
+
+```kotlin
+// ✅ StateFlow — UI state (always has a value, replays to new subscribers)
+val uiState: StateFlow<MyState>
+
+// ✅ Channel — one-time events (navigation, toast) — won't miss events when buffered
+val events: Flow<MyEvent> = _channel.receiveAsFlow()
+
+// ✅ SharedFlow — multi-cast events to multiple collectors (rare in UI layer)
+val sharedEvents = MutableSharedFlow<Event>(extraBufferCapacity = 1)
+```
+
+---
+
+## Loading / Error / Success
+
+```kotlin
+// ✅ Async operation pattern
+fun loadProduct(id: String) {
+    viewModelScope.launch {
+        _state.update { it.copy(isLoading = true, error = null) }
+        getProductUseCase(id).fold(
+            onSuccess = { product ->
+                _state.update { it.copy(isLoading = false, product = product) }
+            },
+            onFailure = { error ->
+                _state.update { it.copy(isLoading = false, error = error.message ?: "Unknown error") }
+            }
+        )
+    }
+}
+
+// ✅ Collecting in Compose
+@Composable
+fun ProductScreen(viewModel: ProductViewModel = hiltViewModel()) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+
+    when {
+        state.isLoading  -> LoadingIndicator()
+        state.error != null -> ErrorView(state.error, onRetry = viewModel::retry)
+        state.product != null -> ProductDetail(state.product)
+    }
+}
+```
+
+---
+
+## Persisted State
+
+```kotlin
+// ✅ Persist UI state across process death via SavedStateHandle
+@HiltViewModel
+class SearchViewModel @Inject constructor(
+    savedStateHandle: SavedStateHandle,
+    private val searchUseCase: SearchUseCase
+) : ViewModel() {
+
+    // ✅ Query persists across process death
+    var searchQuery by savedStateHandle.saveable { mutableStateOf("") }
+        private set
+
+    // ✅ StateFlow backed by SavedStateHandle
+    private val _query = savedStateHandle.getStateFlow("query", "")
+    val results: StateFlow<List<Result>> = _query
+        .debounce(300)
+        .flatMapLatest { searchUseCase(it) }
+        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), emptyList())
+
+    fun onQueryChanged(query: String) {
+        savedStateHandle["query"] = query
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Exposing `MutableStateFlow` publicly — always expose as `StateFlow`
+- Using `StateFlow` for navigation events — they replay on resubscription (double navigation)
+- Multiple `StateFlow` for one screen — combine into one state class
+- Mutating state directly (`_state.value.list.add(...)`) — use `copy()` and `update()`
+- `collectAsState()` instead of `collectAsStateWithLifecycle()` — leaks collection in background
+
+---
+
+## Related Skills
+
+- `mvvm` — ViewModel pattern using state management
+- `mvi` — MVI pattern with strict state management
+- `unidirectional-data-flow` — the underlying principle
+- `reactive-state-management` — Flow operators for state derivation
+- `savedstatehandle` — persisting state across process death
+- `side-effect-management` — managing effects alongside state

package/skills/Architecture/Unidirectional Data Flow/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: unidirectional-data-flow
+description: >
+  Unidirectional Data Flow (UDF) pattern for Android.
+  Load this skill when designing how state flows from ViewModel to UI,
+  how events flow from UI to ViewModel, understanding the UDF cycle,
+  or enforcing a single source of truth for UI state.
+---
+
+# Unidirectional Data Flow (UDF)
+
+## Overview
+
+UDF is the underlying principle behind both MVVM and MVI. State flows **down** from ViewModel to UI; events flow **up** from UI to ViewModel. The UI never mutates state directly — it only emits events. This creates a predictable, traceable, and testable state cycle.
+
+---
+
+## The UDF Cycle
+
+```
+      ┌──────────────────────────────┐
+      │           ViewModel          │
+      │                              │
+      │  event → logic → new state   │
+      └──────┬───────────────────────┘
+             │ State (StateFlow)
+             ▼
+      ┌──────────────────────────────┐
+      │              UI              │
+      │                              │
+      │  render(state)               │
+      │  user interaction → event ──►│
+      └──────────────────────────────┘
+```
+
+1. **State flows down** — ViewModel emits `StateFlow`, UI observes and renders
+2. **Events flow up** — UI emits events (clicks, input), ViewModel processes them
+3. **ViewModel owns state** — UI never mutates state; it requests changes via events
+4. **Single source of truth** — one `StateFlow` per screen, not scattered variables
+
+---
+
+## Core Principles
+
+- State is **immutable** — always produce a new state, never mutate in place
+- UI is a **pure function of state** — same state always produces same UI
+- Events are **the only way** to trigger state changes
+- ViewModel is the **single source of truth** for UI state
+- No two-way data binding that hides event flow
+
+---
+
+## Implementation
+
+```kotlin
+// ✅ State flows down via StateFlow
+data class SearchUiState(
+    val query: String = "",
+    val results: List<Product> = emptyList(),
+    val isLoading: Boolean = false,
+    val error: String? = null
+)
+
+// ✅ Events flow up — all triggers modeled explicitly
+sealed interface SearchEvent {
+    data class QueryChanged(val query: String) : SearchEvent
+    data object SearchSubmitted : SearchEvent
+    data object ClearSearch : SearchEvent
+    data class FilterSelected(val filter: Filter) : SearchEvent
+}
+
+@HiltViewModel
+class SearchViewModel @Inject constructor(
+    private val searchProductsUseCase: SearchProductsUseCase
+) : ViewModel() {
+
+    private val _state = MutableStateFlow(SearchUiState())
+    val state: StateFlow<SearchUiState> = _state.asStateFlow()
+
+    fun onEvent(event: SearchEvent) {
+        when (event) {
+            is SearchEvent.QueryChanged    -> _state.update { it.copy(query = event.query) }
+            is SearchEvent.SearchSubmitted -> search(_state.value.query)
+            is SearchEvent.ClearSearch     -> _state.update { SearchUiState() }
+            is SearchEvent.FilterSelected  -> applyFilter(event.filter)
+        }
+    }
+
+    private fun search(query: String) {
+        viewModelScope.launch {
+            _state.update { it.copy(isLoading = true, error = null) }
+            searchProductsUseCase(query).fold(
+                onSuccess = { results ->
+                    _state.update { it.copy(isLoading = false, results = results) }
+                },
+                onFailure = { error ->
+                    _state.update { it.copy(isLoading = false, error = error.message) }
+                }
+            )
+        }
+    }
+}
+
+// ✅ UI observes state and emits events — never modifies state
+@Composable
+fun SearchScreen(viewModel: SearchViewModel = hiltViewModel()) {
+    val state by viewModel.state.collectAsStateWithLifecycle()
+
+    SearchContent(
+        state = state,
+        onEvent = viewModel::onEvent
+    )
+}
+
+@Composable
+private fun SearchContent(
+    state: SearchUiState,
+    onEvent: (SearchEvent) -> Unit
+) {
+    Column {
+        OutlinedTextField(
+            value = state.query,
+            onValueChange = { onEvent(SearchEvent.QueryChanged(it)) },  // ✅ event up
+            trailingIcon = {
+                IconButton(onClick = { onEvent(SearchEvent.SearchSubmitted) }) {
+                    Icon(Icons.Default.Search, contentDescription = null)
+                }
+            }
+        )
+
+        when {
+            state.isLoading  -> CircularProgressIndicator()
+            state.error != null -> ErrorMessage(state.error)
+            else -> ResultList(state.results)
+        }
+    }
+}
+```
+
+---
+
+## State Updates
+
+```kotlin
+// ✅ Immutable update via copy()
+_state.update { currentState ->
+    currentState.copy(
+        isLoading = false,
+        results = newResults
+    )
+}
+
+// ✅ update{} is atomic — safe for concurrent updates
+// update() uses compareAndSet internally — no race conditions
+
+// ❌ Direct mutation — never do this
+_state.value.results.add(item)  // breaks UDF — state is mutated, not replaced
+```
+
+---
+
+## Derived State
+
+```kotlin
+// ✅ Derive additional state from primary state
+val filteredUsers: StateFlow<List<User>> = combine(
+    _users,
+    _searchQuery
+) { users, query ->
+    if (query.isBlank()) users
+    else users.filter { it.name.contains(query, ignoreCase = true) }
+}.stateIn(
+    scope = viewModelScope,
+    started = SharingStarted.WhileSubscribed(5_000),
+    initialValue = emptyList()
+)
+```
+
+---
+
+## Anti-Patterns
+
+- UI mutating ViewModel state directly — UI only emits events
+- Two-way data binding (`var` exposed directly) — breaks traceability
+- Multiple independent StateFlows for one screen — hard to reason about combined state
+- Calling ViewModel functions with side-effect names from UI ("submit", "navigate") — model as events instead
+- Mutable collections inside state — use `List`, not `MutableList`
+
+---
+
+## Related Skills
+
+- `mvvm` — MVVM applies UDF with ViewModel + StateFlow
+- `mvi` — MVI is a strict formalization of UDF with Intent/State/Effect
+- `state-management` — advanced state patterns
+- `reactive-state-management` — Flow operators for deriving state