android-sdd 1.0.0

package/skills/Android Platform/State Restoration/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: state-restoration
+description: >
+  Complete state restoration strategy for Android — covering UI state,
+  scroll position, form data, and Compose rememberSaveable.
+  Load this skill when deciding how to persist and restore UI state
+  across configuration changes and process death.
+---
+
+# State Restoration
+
+## Overview
+
+State restoration ensures the user sees a consistent UI after configuration changes (rotation) or returning after process death. Android provides multiple layers of restoration — from automatic (Compose rememberSaveable) to manual (SavedStateHandle). Choosing the right layer for each piece of state is the key design decision.
+
+---
+
+## Core Principles
+
+- Match the **persistence layer** to the **state lifetime**
+- UI-local state → `rememberSaveable`
+- ViewModel state that must survive process death → `SavedStateHandle`
+- Data loaded from network/DB → don't save, reload from repository
+- Never duplicate state across multiple layers — one source of truth per state
+
+---
+
+## State Restoration Layers
+
+| Layer                | Survives Rotation | Survives Process Death | Use For                               |
+| -------------------- | ----------------- | ---------------------- | ------------------------------------- |
+| `remember`           | ❌                 | ❌                      | Transient UI state (animation, focus) |
+| `rememberSaveable`   | ✅                 | ✅                      | Local UI state (expanded, scroll)     |
+| `SavedStateHandle`   | ✅                 | ✅                      | ViewModel state (query, selected ID)  |
+| `Room` / `DataStore` | ✅                 | ✅                      | Persistent data                       |
+
+---
+
+## Compose — rememberSaveable
+
+```kotlin
+// ✅ Simple value — auto-saved
+@Composable
+fun SearchBar() {
+    var query by rememberSaveable { mutableStateOf("") }
+    // query survives rotation and process death
+    TextField(value = query, onValueChange = { query = it })
+}
+
+// ✅ Custom type — requires Saver
+data class FilterState(val category: String, val sort: String)
+
+val FilterStateSaver = run {
+    val categoryKey = "category"
+    val sortKey = "sort"
+    mapSaver(
+        save = { mapOf(categoryKey to it.category, sortKey to it.sort) },
+        restore = { FilterState(it[categoryKey] as String, it[sortKey] as String) }
+    )
+}
+
+@Composable
+fun FilterPanel() {
+    var filter by rememberSaveable(stateSaver = FilterStateSaver) {
+        mutableStateOf(FilterState("all", "asc"))
+    }
+}
+
+// ✅ List state — scroll position
+@Composable
+fun UserList(users: List<User>) {
+    val listState = rememberLazyListState()
+    // listState scroll position is automatically saved by rememberLazyListState
+    LazyColumn(state = listState) {
+        items(users) { UserItem(it) }
+    }
+}
+```
+
+---
+
+## Compose — Hoist State to ViewModel
+
+```kotlin
+// ✅ When state needs to be shared or outlive a single composable
+// → hoist to ViewModel backed by SavedStateHandle
+
+@HiltViewModel
+class ProductViewModel @Inject constructor(
+    savedStateHandle: SavedStateHandle,
+    private val repository: ProductRepository
+) : ViewModel() {
+
+    // ✅ Search query — saved across process death
+    val query: StateFlow<String> = savedStateHandle
+        .getStateFlow("query", "")
+
+    // ✅ Products — reloaded from DB, not saved
+    val products: StateFlow<List<Product>> = query
+        .flatMapLatest { repository.search(it) }
+        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), emptyList())
+
+    fun onQueryChanged(q: String) { savedStateHandle["query"] = q }
+}
+
+@Composable
+fun ProductScreen(viewModel: ProductViewModel = hiltViewModel()) {
+    val query by viewModel.query.collectAsStateWithLifecycle()
+    val products by viewModel.products.collectAsStateWithLifecycle()
+
+    // UI renders from ViewModel state — no local state needed
+}
+```
+
+---
+
+## View System — onSaveInstanceState
+
+```kotlin
+// ✅ For custom Views that need to save state
+class CounterView(context: Context) : View(context) {
+
+    private var count = 0
+
+    override fun onSaveInstanceState(): Parcelable {
+        val superState = super.onSaveInstanceState()
+        return SavedState(superState, count)
+    }
+
+    override fun onRestoreInstanceState(state: Parcelable?) {
+        if (state is SavedState) {
+            super.onRestoreInstanceState(state.superState)
+            count = state.count
+        } else {
+            super.onRestoreInstanceState(state)
+        }
+    }
+
+    @Parcelize
+    class SavedState(val parcelable: Parcelable?, val count: Int) : BaseSavedState(parcelable)
+}
+```
+
+---
+
+## Restoration Decision Tree
+
+```
+Is this state local to a single composable?
+    YES → rememberSaveable
+    NO ↓
+
+Is this state loaded from DB or network?
+    YES → reload from repository (don't save)
+    NO ↓
+
+Is this state user input or a selected ID?
+    YES → SavedStateHandle in ViewModel
+    NO ↓
+
+Is this critical persistent data?
+    YES → Room or DataStore
+```
+
+---
+
+## Testing Restoration
+
+```kotlin
+// ✅ Test rememberSaveable with StateRestorationTester
+@Test
+fun searchQuery_survivesStateRestoration() {
+    val restorationTester = StateRestorationTester(composeTestRule)
+
+    restorationTester.setContent {
+        SearchBar()
+    }
+
+    composeTestRule.onNodeWithTag("search_field").performTextInput("kotlin")
+    restorationTester.emulateSavedInstanceStateRestore()
+    composeTestRule.onNodeWithTag("search_field").assertTextEquals("kotlin")
+}
+
+// ✅ Test SavedStateHandle restoration
+@Test
+fun viewModel_restoresQueryAfterProcessDeath() {
+    val handle = SavedStateHandle(mapOf("query" to "android"))
+    val vm = ProductViewModel(handle, fakeRepository)
+    assertThat(vm.query.value).isEqualTo("android")
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Using `remember` instead of `rememberSaveable` for user-visible state — lost on rotation
+- Saving large lists or bitmaps in `rememberSaveable` or `SavedStateHandle` — size limit and slow
+- Duplicating state: saving in both ViewModel and rememberSaveable — two sources of truth
+- Not testing restoration — the most common cause of rotation bugs
+- Manually saving scroll position when `rememberLazyListState` does it automatically
+
+---
+
+## Related Skills
+
+- `savedstatehandle` — SavedStateHandle in ViewModel
+- `process-death-recovery` — surviving system-initiated kills
+- `compose` — rememberSaveable and state hoisting in Compose
+- `lifecycle` — when restoration occurs in the lifecycle

package/skills/Architecture/Bounded Context/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: bounded-context
+description: >
+  Bounded Context pattern for Android feature organization.
+  Load this skill when defining feature boundaries, deciding what belongs
+  in a shared domain vs a feature-specific domain, preventing model pollution
+  across features, or designing the conceptual boundaries of a module.
+---
+
+# Bounded Context
+
+## Overview
+
+A Bounded Context defines the boundary within which a domain model is consistent and valid. In Android, each feature module (or major feature area) is a Bounded Context — it owns its own models, rules, and language. The same real-world concept (e.g. "User") may exist in multiple contexts with different shapes and responsibilities.
+
+---
+
+## Core Principles
+
+- Each context owns its **own model** — never share a model across contexts if they evolve differently
+- **Context map** makes inter-context relationships explicit
+- Cross-context communication happens through **well-defined interfaces** — not direct model sharing
+- The same word can mean different things in different contexts — that's intentional
+- Shared kernel only for concepts that are **truly identical** across contexts
+
+---
+
+## Example: "User" in Multiple Contexts
+
+```kotlin
+// ❌ Tempting but wrong — one "User" class used everywhere
+data class User(
+    val id: String,
+    val name: String,
+    val email: String,
+    val role: UserRole,
+    val shippingAddresses: List<Address>,    // only needed in Orders context
+    val orderHistory: List<OrderSummary>,    // only needed in Orders context
+    val savedCards: List<PaymentCard>,       // only needed in Payment context
+    val notificationPreferences: NotificationPrefs // only needed in Notifications
+)
+// This model becomes a dumping ground — bloated and hard to maintain
+
+// ✅ Correct — each context defines its own model
+// Auth context
+data class AuthUser(
+    val id: String,
+    val email: String,
+    val role: UserRole,
+    val sessionToken: String
+)
+
+// Orders context
+data class OrderCustomer(
+    val id: String,
+    val displayName: String,
+    val defaultShippingAddress: Address?
+)
+
+// Profile context
+data class UserProfile(
+    val id: String,
+    val fullName: String,
+    val avatarUrl: String?,
+    val bio: String?
+)
+
+// Notifications context
+data class NotificationRecipient(
+    val userId: String,
+    val pushToken: String?,
+    val preferences: NotificationPreferences
+)
+```
+
+---
+
+## Context Map
+
+```kotlin
+// ✅ Explicit translation between contexts
+// When Orders needs user info, it requests it through an interface
+
+// Orders context defines what it needs
+interface CustomerInfoProvider {
+    suspend fun getCustomer(userId: String): Result<OrderCustomer>
+}
+
+// The implementation in :app or a shared module translates
+class CustomerInfoProviderImpl @Inject constructor(
+    private val userRepository: UserRepository  // Auth/Profile context
+) : CustomerInfoProvider {
+
+    override suspend fun getCustomer(userId: String): Result<OrderCustomer> =
+        userRepository.getUser(userId).map { user ->
+            OrderCustomer(
+                id = user.id,
+                displayName = user.name,
+                defaultShippingAddress = user.addresses.firstOrNull { it.isDefault }
+            )
+        }
+}
+```
+
+---
+
+## Feature Module as Bounded Context
+
+```kotlin
+// ✅ :feature:orders owns its domain model
+// feature/orders/domain/model/
+data class Order(val id: String, val customerId: String, val items: List<OrderItem>, ...)
+data class OrderItem(val productId: String, val name: String, val quantity: Int, ...)
+data class OrderSummary(val id: String, val status: OrderStatus, val totalAmount: Money)
+
+// ✅ :feature:catalog owns its domain model — Product means something different here
+// feature/catalog/domain/model/
+data class Product(val id: String, val name: String, val description: String, val price: Money, ...)
+data class Category(val id: String, val name: String, val products: List<ProductSummary>)
+
+// ✅ :feature:cart owns its domain model — Product in cart context = CartItem
+// feature/cart/domain/model/
+data class Cart(val id: String, val items: List<CartItem>)
+data class CartItem(val productId: String, val productName: String, val unitPrice: Money, val quantity: Int)
+// Note: CartItem has productName denormalized — it owns what it needs
+```
+
+---
+
+## Shared Kernel
+
+```kotlin
+// ✅ Truly shared concepts live in :core:domain
+// These are stable and identical across all contexts
+
+// :core:domain/model/shared/
+@JvmInline value class UserId(val value: String)
+@JvmInline value class ProductId(val value: String)
+data class Money(val amount: Long, val currency: Currency)
+enum class Currency { IRR, USD, EUR }
+
+// All features import these from :core:domain — not from each other
+```
+
+---
+
+## Anti-Corruption Layer
+
+```kotlin
+// ✅ Translate external API models without polluting domain
+// When integrating a payment gateway, don't let its model bleed in
+
+// External (Zarinpal, Stripe, etc.)
+data class PaymentGatewayResponse(
+    val status: Int,
+    val ref_id: String?,
+    val error_code: String?
+)
+
+// Anti-corruption layer — translates to domain language
+class PaymentGatewayAdapter @Inject constructor(
+    private val gateway: PaymentGatewayService
+) {
+    suspend fun processPayment(request: PaymentRequest): Result<PaymentConfirmation> =
+        runCatching {
+            val response = gateway.pay(request.toGatewayRequest())
+            when (response.status) {
+                100 -> PaymentConfirmation(
+                    transactionId = response.ref_id ?: error("Missing ref_id"),
+                    amount = request.amount
+                )
+                else -> throw PaymentException(response.error_code ?: "Unknown error")
+            }
+        }
+}
+```
+
+---
+
+## When to Split vs Share
+
+| Signal                                                 | Action                                           |
+| ------------------------------------------------------ | ------------------------------------------------ |
+| Same concept evolves differently in two features       | Split into two models                            |
+| Same concept has identical fields and rules everywhere | Put in shared kernel                             |
+| Feature A needs data from Feature B                    | Define interface in A, implement in :app         |
+| Two features share a DTO from the same API endpoint    | Split into feature-specific domain models anyway |
+| Changing one feature's model breaks another feature    | Context boundary is violated — split             |
+
+---
+
+## Anti-Patterns
+
+- One giant `User` class used by auth, profile, orders, notifications — split by context
+- Feature modules importing domain models from other feature modules — route through :core or interfaces
+- Shared kernel growing to include feature-specific concepts — keep shared kernel minimal and stable
+- Skipping the translation layer — directly mapping API DTOs to domain models used by multiple features
+
+---
+
+## Related Skills
+
+- `modularization` — module boundaries that enforce context boundaries
+- `feature-isolation` — isolating feature implementation details
+- `domain-modeling` — modeling within a bounded context
+- `clean-architecture` — layer boundaries within a context
+- `repository-pattern` — repository interfaces as context boundaries

package/skills/Architecture/Clean Architecture/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: clean-architecture
+description: >
+  Clean Architecture layering for Android projects.
+  Load this skill when designing layer boundaries, defining dependencies between
+  layers, structuring packages, or deciding where logic belongs (UI vs Domain vs Data).
+---
+
+# Clean Architecture
+
+## Overview
+
+Clean Architecture organizes code into three concentric layers: **Presentation**, **Domain**, and **Data**. Dependencies flow inward only — outer layers depend on inner layers, never the reverse. The Domain layer is pure Kotlin with no Android dependencies.
+
+---
+
+## Layer Structure
+
+```
+app/
+├── presentation/       # Compose UI, ViewModels, UiState, UiEvent
+│   └── feature/
+│       ├── FeatureScreen.kt
+│       ├── FeatureViewModel.kt
+│       └── FeatureUiState.kt
+├── domain/             # Pure Kotlin — UseCases, Entities, Repository interfaces
+│   ├── model/
+│   │   └── User.kt
+│   ├── repository/
+│   │   └── UserRepository.kt        # interface only
+│   └── usecase/
+│       └── GetUserUseCase.kt
+└── data/               # Repository implementations, Room, Retrofit, DataStore
+    ├── repository/
+    │   └── UserRepositoryImpl.kt
+    ├── local/
+    │   ├── UserDao.kt
+    │   └── UserEntity.kt
+    ├── remote/
+    │   ├── UserApiService.kt
+    │   └── UserDto.kt
+    └── mapper/
+        └── UserMapper.kt
+```
+
+---
+
+## Dependency Rule
+
+```
+Presentation → Domain ← Data
+```
+
+- **Domain** depends on nothing (no Android, no Room, no Retrofit)
+- **Presentation** depends on Domain (uses UseCases and models)
+- **Data** depends on Domain (implements Repository interfaces)
+- **Data** never imports from **Presentation**
+- **Presentation** never imports from **Data** directly
+
+---
+
+## Domain Layer
+
+```kotlin
+// ✅ Entity — pure Kotlin data class, no annotations
+data class User(
+    val id: String,
+    val name: String,
+    val email: String,
+    val role: UserRole
+)
+
+enum class UserRole { ADMIN, MEMBER, GUEST }
+
+// ✅ Repository interface — defined in Domain, implemented in Data
+interface UserRepository {
+    suspend fun getUser(id: String): Result<User>
+    suspend fun getUsers(): Result<List<User>>
+    suspend fun saveUser(user: User): Result<Unit>
+    fun observeUsers(): Flow<List<User>>
+}
+
+// ✅ UseCase — single responsibility, pure logic
+class GetUserUseCase @Inject constructor(
+    private val repository: UserRepository
+) {
+    suspend operator fun invoke(id: String): Result<User> =
+        repository.getUser(id)
+}
+
+class GetActiveUsersUseCase @Inject constructor(
+    private val repository: UserRepository
+) {
+    operator fun invoke(): Flow<List<User>> =
+        repository.observeUsers().map { users ->
+            users.filter { it.role != UserRole.GUEST }
+        }
+}
+```
+
+---
+
+## Data Layer
+
+```kotlin
+// ✅ Entity — Room-specific, isolated in data layer
+@Entity(tableName = "users")
+data class UserEntity(
+    @PrimaryKey val id: String,
+    val name: String,
+    val email: String,
+    val role: String
+)
+
+// ✅ DTO — API response model
+data class UserDto(
+    @SerialName("id") val id: String,
+    @SerialName("full_name") val name: String,
+    @SerialName("email_address") val email: String,
+    @SerialName("role") val role: String
+)
+
+// ✅ Mapper — converts between layers
+object UserMapper {
+    fun UserDto.toDomain(): User = User(
+        id = id,
+        name = name,
+        email = email,
+        role = UserRole.valueOf(role.uppercase())
+    )
+
+    fun UserEntity.toDomain(): User = User(
+        id = id,
+        name = name,
+        email = email,
+        role = UserRole.valueOf(role.uppercase())
+    )
+
+    fun User.toEntity(): UserEntity = UserEntity(
+        id = id,
+        name = name,
+        email = email,
+        role = role.name.lowercase()
+    )
+}
+
+// ✅ Repository implementation — in Data, implements Domain interface
+class UserRepositoryImpl @Inject constructor(
+    private val api: UserApiService,
+    private val dao: UserDao
+) : UserRepository {
+
+    override suspend fun getUser(id: String): Result<User> = runCatching {
+        val entity = dao.getUserById(id)
+        entity?.toDomain() ?: run {
+            val dto = api.getUser(id)
+            val domain = dto.toDomain()
+            dao.insert(domain.toEntity())
+            domain
+        }
+    }
+
+    override fun observeUsers(): Flow<List<User>> =
+        dao.observeAll().map { entities -> entities.map { it.toDomain() } }
+}
+```
+
+---
+
+## Presentation Layer
+
+```kotlin
+// ✅ ViewModel uses UseCases — never Repository directly
+@HiltViewModel
+class UserListViewModel @Inject constructor(
+    private val getActiveUsersUseCase: GetActiveUsersUseCase
+) : ViewModel() {
+
+    val state: StateFlow<UserListUiState> =
+        getActiveUsersUseCase()
+            .map { UserListUiState.Success(it) }
+            .catch { emit(UserListUiState.Error(it.message ?: "Error")) }
+            .stateIn(
+                scope = viewModelScope,
+                started = SharingStarted.WhileSubscribed(5_000),
+                initialValue = UserListUiState.Loading
+            )
+}
+```
+
+---
+
+## Hilt Binding
+
+```kotlin
+// ✅ Bind interface to implementation in data module
+@Module
+@InstallIn(SingletonComponent::class)
+abstract class RepositoryModule {
+
+    @Binds
+    @Singleton
+    abstract fun bindUserRepository(
+        impl: UserRepositoryImpl
+    ): UserRepository
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Importing `android.*` or `androidx.*` in Domain layer — Domain must be pure Kotlin
+- ViewModel calling Repository directly — always go through a UseCase
+- Presentation importing Data classes (Entity, DTO) — only Domain models cross into Presentation
+- UseCase containing more than one responsibility — one UseCase, one operation
+- Repository interface defined in Data layer — interfaces belong in Domain
+- Skipping the mapper — never pass DTO or Entity into Domain or Presentation
+
+---
+
+## Related Skills
+
+- `mvvm` — ViewModel and UI state structure
+- `use-case-design` — designing UseCases in Domain layer
+- `repository-pattern` — Repository interface and implementation patterns
+- `dto-mapping` — mapping between layers
+- `hilt` — dependency injection wiring
+- `domain-modeling` — modeling domain entities