android-sdd 1.0.0

package/skills/Architecture/Use Case Design/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: use-case-design
+description: >
+  Use Case design for Android Clean Architecture.
+  Load this skill when creating UseCase classes, deciding what logic
+  belongs in a UseCase vs Repository vs ViewModel, structuring UseCase
+  inputs and outputs, or composing multiple UseCases together.
+---
+
+# Use Case Design
+
+## Overview
+
+A UseCase (also called Interactor) encapsulates a single business operation. It lives in the Domain layer, depends only on Repository interfaces and domain models, and is called by the ViewModel. ViewModels never call Repositories directly — they always go through a UseCase.
+
+---
+
+## Core Principles
+
+- **One UseCase, one operation** — `GetUserUseCase`, not `UserUseCase`
+- Lives in **Domain layer** — pure Kotlin, no Android imports
+- Depends on **Repository interfaces** — not implementations
+- Called by **ViewModel only** — never from UI or another UseCase (compose at ViewModel level)
+- Returns **Result<T>** for suspend operations, **Flow<T>** for reactive streams
+- **No state** — UseCases are stateless; state lives in ViewModel
+
+---
+
+## Standard UseCase (Suspend)
+
+```kotlin
+// ✅ Suspend UseCase — one operation, invokable via operator fun
+class GetUserUseCase @Inject constructor(
+    private val userRepository: UserRepository
+) {
+    suspend operator fun invoke(userId: String): Result<User> =
+        userRepository.getUser(userId)
+}
+
+class DeleteUserUseCase @Inject constructor(
+    private val userRepository: UserRepository
+) {
+    suspend operator fun invoke(userId: String): Result<Unit> =
+        userRepository.deleteUser(userId)
+}
+
+class CreateOrderUseCase @Inject constructor(
+    private val orderRepository: OrderRepository,
+    private val cartRepository: CartRepository,
+    private val inventoryRepository: InventoryRepository
+) {
+    suspend operator fun invoke(cartId: String, userId: String): Result<Order> =
+        runCatching {
+            val cart = cartRepository.getCart(cartId).getOrThrow()
+            require(cart.items.isNotEmpty()) { "Cannot create order from empty cart" }
+
+            // Business rule: validate inventory before placing order
+            cart.items.forEach { item ->
+                val available = inventoryRepository.getStock(item.productId).getOrThrow()
+                require(available >= item.quantity) {
+                    "Insufficient stock for ${item.productName}"
+                }
+            }
+
+            val order = orderRepository.create(cart.toOrderRequest(userId)).getOrThrow()
+            cartRepository.clear(cartId)
+            order
+        }
+}
+```
+
+---
+
+## Reactive UseCase (Flow)
+
+```kotlin
+// ✅ Flow UseCase — for ongoing observation
+class ObserveUsersUseCase @Inject constructor(
+    private val userRepository: UserRepository
+) {
+    operator fun invoke(): Flow<List<User>> =
+        userRepository.observeUsers()
+}
+
+// ✅ Flow UseCase with transformation
+class ObserveActiveUsersUseCase @Inject constructor(
+    private val userRepository: UserRepository
+) {
+    operator fun invoke(): Flow<List<User>> =
+        userRepository.observeUsers()
+            .map { users -> users.filter { it.status == UserStatus.ACTIVE } }
+            .distinctUntilChanged()
+}
+
+// ✅ Flow UseCase combining multiple sources
+class ObserveDashboardUseCase @Inject constructor(
+    private val userRepository: UserRepository,
+    private val orderRepository: OrderRepository
+) {
+    operator fun invoke(userId: String): Flow<DashboardData> =
+        combine(
+            userRepository.observeUser(userId),
+            orderRepository.observeRecentOrders(userId)
+        ) { user, orders ->
+            DashboardData(
+                userName = user?.name ?: "",
+                recentOrderCount = orders.size,
+                pendingOrderCount = orders.count { it.status == OrderStatus.PENDING }
+            )
+        }
+}
+```
+
+---
+
+## UseCase with Parameters
+
+```kotlin
+// ✅ Simple primitive params — pass directly
+class SearchProductsUseCase @Inject constructor(
+    private val repository: ProductRepository
+) {
+    suspend operator fun invoke(query: String, filter: ProductFilter): Result<List<Product>> =
+        repository.search(query, filter)
+}
+
+// ✅ Complex params — use a dedicated Params data class
+class PlaceOrderUseCase @Inject constructor(
+    private val repository: OrderRepository
+) {
+    data class Params(
+        val cartId: String,
+        val shippingAddressId: String,
+        val paymentMethodId: String,
+        val couponCode: String? = null
+    )
+
+    suspend operator fun invoke(params: Params): Result<Order> =
+        runCatching {
+            // apply coupon if present
+            val discount = params.couponCode?.let {
+                repository.validateCoupon(it).getOrThrow()
+            }
+            repository.placeOrder(params.toRequest(discount)).getOrThrow()
+        }
+}
+
+// ViewModel usage
+fun onPlaceOrder() {
+    viewModelScope.launch {
+        val params = PlaceOrderUseCase.Params(
+            cartId = state.value.cartId,
+            shippingAddressId = state.value.selectedAddressId,
+            paymentMethodId = state.value.selectedPaymentId,
+            couponCode = state.value.couponCode.takeIf { it.isNotBlank() }
+        )
+        placeOrderUseCase(params).fold(
+            onSuccess = { _events.send(Event.NavigateToConfirmation(it.id)) },
+            onFailure = { _state.update { s -> s.copy(error = it.message) } }
+        )
+    }
+}
+```
+
+---
+
+## ViewModel Usage
+
+```kotlin
+// ✅ ViewModel composes UseCases — never calls Repository directly
+@HiltViewModel
+class UserDetailViewModel @Inject constructor(
+    savedStateHandle: SavedStateHandle,
+    private val getUserUseCase: GetUserUseCase,
+    private val updateUserUseCase: UpdateUserUseCase,
+    private val deleteUserUseCase: DeleteUserUseCase
+) : ViewModel() {
+
+    private val userId: String = checkNotNull(savedStateHandle["userId"])
+
+    val state: StateFlow<UserDetailUiState> =
+        getUserUseCase.asFlow(userId)   // extension if needed
+            .map { result ->
+                result.fold(
+                    onSuccess = { UserDetailUiState.Success(it) },
+                    onFailure = { UserDetailUiState.Error(it.message ?: "Error") }
+                )
+            }
+            .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), UserDetailUiState.Loading)
+
+    fun onDeleteClick() {
+        viewModelScope.launch {
+            deleteUserUseCase(userId).fold(
+                onSuccess = { _events.send(Event.NavigateBack) },
+                onFailure = { _events.send(Event.ShowError(it.message ?: "Delete failed")) }
+            )
+        }
+    }
+}
+```
+
+---
+
+## UseCase Package Structure
+
+```
+domain/
+└── usecase/
+    ├── user/
+    │   ├── GetUserUseCase.kt
+    │   ├── GetUsersUseCase.kt
+    │   ├── ObserveUsersUseCase.kt
+    │   ├── CreateUserUseCase.kt
+    │   ├── UpdateUserUseCase.kt
+    │   └── DeleteUserUseCase.kt
+    ├── order/
+    │   ├── PlaceOrderUseCase.kt
+    │   ├── CancelOrderUseCase.kt
+    │   └── ObserveOrdersUseCase.kt
+    └── auth/
+        ├── LoginUseCase.kt
+        └── LogoutUseCase.kt
+```
+
+---
+
+## Anti-Patterns
+
+- ViewModel calling Repository directly — always go through UseCase
+- UseCase with multiple unrelated responsibilities — split into separate UseCases
+- UseCase holding state — stateless only; state belongs in ViewModel
+- UseCase importing Android framework classes — Domain layer is pure Kotlin
+- Generic `UserUseCase` with many methods — one class, one operation
+- UseCase calling another UseCase — compose at ViewModel level instead
+
+---
+
+## Related Skills
+
+- `clean-architecture` — layer structure UseCase sits within
+- `mvvm` — ViewModel calling UseCases
+- `repository-pattern` — Repository interfaces UseCase depends on
+- `domain-modeling` — domain models UseCase operates on
+- `side-effect-management` — handling side effects triggered by UseCases

package/skills/Architecture/Value Object/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: value-object
+description: >
+  Value Object pattern for Android domain modeling.
+  Load this skill when wrapping primitive types with business meaning,
+  implementing validation at construction time, designing immutable value types,
+  using Kotlin inline/value classes, or eliminating primitive obsession.
+---
+
+# Value Object
+
+## Overview
+
+A Value Object is an immutable object defined entirely by its values, not by identity. Two Value Objects with the same values are equal. They encapsulate validation and domain rules at the point of creation, eliminating invalid states and primitive obsession across the codebase.
+
+---
+
+## Core Principles
+
+- **No identity** — equality is based on values, not `id`
+- **Immutable** — all fields are `val`; produce new instances instead of mutating
+- **Self-validating** — invalid values cannot be constructed; validation in `init`
+- **Behavior-rich** — operations and rules belong here, not in the caller
+- **Replaces primitives** — prefer `Email` over `String`, `Money` over `Long`
+
+---
+
+## Kotlin Value Class (Inline Class)
+
+```kotlin
+// ✅ Single-field value object — use @JvmInline value class (zero overhead)
+@JvmInline
+value class Email(val value: String) {
+    init {
+        require(value.isNotBlank()) { "Email cannot be blank" }
+        require(value.contains("@")) { "Invalid email format: $value" }
+        require(value.length <= 254) { "Email exceeds maximum length" }
+    }
+
+    val domain: String get() = value.substringAfter("@")
+    val local: String get() = value.substringBefore("@")
+}
+
+@JvmInline
+value class UserId(val value: String) {
+    init { require(value.isNotBlank()) { "UserId cannot be blank" } }
+}
+
+@JvmInline
+value class PhoneNumber(val value: String) {
+    init {
+        val digits = value.filter { it.isDigit() }
+        require(digits.length in 10..15) { "Invalid phone number: $value" }
+    }
+
+    val normalized: String get() = value.filter { it.isDigit() }
+}
+
+@JvmInline
+value class Percentage(val value: Double) {
+    init {
+        require(value in 0.0..100.0) { "Percentage must be between 0 and 100: $value" }
+    }
+
+    fun toFraction(): Double = value / 100.0
+}
+```
+
+---
+
+## Multi-Field Value Object
+
+```kotlin
+// ✅ Multi-field value object — regular data class
+data class Money(
+    val amount: Long,         // smallest unit (e.g. cents, rials)
+    val currency: Currency
+) {
+    init {
+        require(amount >= 0) { "Money amount cannot be negative: $amount" }
+    }
+
+    operator fun plus(other: Money): Money {
+        require(currency == other.currency) { "Cannot add different currencies" }
+        return copy(amount = amount + other.amount)
+    }
+
+    operator fun minus(other: Money): Money {
+        require(currency == other.currency) { "Cannot subtract different currencies" }
+        require(amount >= other.amount) { "Cannot subtract: result would be negative" }
+        return copy(amount = amount - other.amount)
+    }
+
+    operator fun times(factor: Int): Money = copy(amount = amount * factor)
+
+    fun isZero(): Boolean = amount == 0L
+    fun isPositive(): Boolean = amount > 0L
+
+    companion object {
+        fun zero(currency: Currency) = Money(0L, currency)
+        fun ofRials(amount: Long) = Money(amount, Currency.IRR)
+    }
+}
+
+data class Address(
+    val street: String,
+    val city: String,
+    val postalCode: PostalCode,
+    val country: Country
+) {
+    init {
+        require(street.isNotBlank()) { "Street cannot be blank" }
+        require(city.isNotBlank()) { "City cannot be blank" }
+    }
+
+    fun formatted(): String = "$street, $city, ${postalCode.value}, ${country.displayName}"
+}
+
+data class DateRange(
+    val start: LocalDate,
+    val end: LocalDate
+) {
+    init {
+        require(!end.isBefore(start)) { "End date must not be before start date" }
+    }
+
+    fun contains(date: LocalDate): Boolean =
+        !date.isBefore(start) && !date.isAfter(end)
+
+    fun overlaps(other: DateRange): Boolean =
+        !start.isAfter(other.end) && !end.isBefore(other.start)
+
+    fun durationDays(): Long = ChronoUnit.DAYS.between(start, end)
+}
+```
+
+---
+
+## Safe Construction with Result
+
+```kotlin
+// ✅ When validation failure should be handled gracefully (not crash)
+@JvmInline
+value class Username private constructor(val value: String) {
+    companion object {
+        fun create(value: String): Result<Username> = runCatching {
+            require(value.length in 3..20) { "Username must be 3-20 characters" }
+            require(value.all { it.isLetterOrDigit() || it == '_' }) {
+                "Username can only contain letters, digits, and underscores"
+            }
+            Username(value)
+        }
+    }
+}
+
+// Usage
+val result = Username.create(input)
+result.fold(
+    onSuccess = { username -> proceed(username) },
+    onFailure = { error -> showValidationError(error.message) }
+)
+```
+
+---
+
+## Storage Mapping
+
+```kotlin
+// ✅ TypeConverter for Value Objects in Room
+class ValueObjectConverters {
+
+    @TypeConverter
+    fun fromEmail(email: Email?): String? = email?.value
+
+    @TypeConverter
+    fun toEmail(value: String?): Email? = value?.let { Email(it) }
+
+    @TypeConverter
+    fun fromMoney(money: Money?): String? =
+        money?.let { "${it.amount}:${it.currency.name}" }
+
+    @TypeConverter
+    fun toMoney(value: String?): Money? = value?.let {
+        val (amount, currency) = it.split(":")
+        Money(amount.toLong(), Currency.valueOf(currency))
+    }
+}
+```
+
+---
+
+## Serialization Mapping
+
+```kotlin
+// ✅ Never serialize Value Objects directly — map at the boundary
+data class UserDto(
+    @SerialName("id") val id: String,
+    @SerialName("email") val email: String,    // raw String in DTO
+)
+
+// ✅ Map to domain Value Object in mapper
+fun UserDto.toDomain(): User = User(
+    id = UserId(id),
+    email = Email(email),                       // construct Value Object here
+    ...
+)
+```
+
+---
+
+## Anti-Patterns
+
+- Passing raw `String` for email, phone, ID across the codebase — use Value Objects
+- Validating the same constraint in multiple places — validation belongs in the Value Object constructor
+- Mutable Value Objects (`var` fields) — Value Objects must be immutable
+- Using `@JvmInline value class` for multi-field objects — value classes only support one property
+- Throwing generic `IllegalArgumentException` without a message — always include context in the message
+
+---
+
+## Related Skills
+
+- `domain-modeling` — where Value Objects are used within the domain
+- `entity-design` — mapping Value Objects to database columns
+- `dto-mapping` — mapping between raw DTO strings and Value Objects
+- `immutability` — immutability principles in Kotlin