android-sdd 1.0.0

package/skills/Architecture/Domain Modeling/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: domain-modeling
+description: >
+  Domain modeling for Android Clean Architecture projects.
+  Load this skill when designing domain entities, defining business rules
+  in the domain layer, modeling relationships between domain objects,
+  choosing between Entity vs Value Object, or structuring the domain package.
+---
+
+# Domain Modeling
+
+## Overview
+
+Domain modeling defines the core business concepts of the application as pure Kotlin classes — free of Android framework, database annotations, or network serialization. The domain model is the language of the business, shared across all layers via mapping.
+
+---
+
+## Core Principles
+
+- Domain models are **pure Kotlin** — no `@Entity`, `@SerialName`, `@Parcelize`
+- Domain models express **business concepts** — not database tables or API contracts
+- **Behavior belongs in domain** — validation, business rules, computations live here
+- **Immutable** — use `val`, use `data class`, use `copy()` for changes
+- Domain models are the **shared language** — same names used in UI, DB, API (via mapping)
+
+---
+
+## Entity vs Value Object
+
+|           | Entity                   | Value Object               |
+| --------- | ------------------------ | -------------------------- |
+| Identity  | Has unique `id`          | Defined by its values      |
+| Equality  | By `id`                  | By all fields              |
+| Lifecycle | Persisted, tracked       | Transient, replaceable     |
+| Example   | `User(id=1, name="Ali")` | `Email("ali@example.com")` |
+
+---
+
+## Domain Entity
+
+```kotlin
+// ✅ Entity — has identity, represents a business object
+data class User(
+    val id: String,
+    val name: String,
+    val email: Email,           // ✅ use Value Object for validated fields
+    val role: UserRole,
+    val status: UserStatus,
+    val createdAt: Instant
+) {
+    // ✅ Business rules as functions — not in ViewModel
+    fun canEdit(actor: User): Boolean =
+        actor.id == id || actor.role == UserRole.ADMIN
+
+    fun isActive(): Boolean = status == UserStatus.ACTIVE
+
+    fun withRole(newRole: UserRole): User = copy(role = newRole)
+}
+
+data class Order(
+    val id: String,
+    val customerId: String,
+    val items: List<OrderItem>,
+    val status: OrderStatus,
+    val placedAt: Instant
+) {
+    val totalAmount: Money
+        get() = items.fold(Money.ZERO) { acc, item -> acc + item.subtotal }
+
+    fun canBeCancelled(): Boolean =
+        status == OrderStatus.PENDING || status == OrderStatus.PROCESSING
+
+    fun withStatus(newStatus: OrderStatus): Order = copy(status = newStatus)
+}
+```
+
+---
+
+## Value Object
+
+```kotlin
+// ✅ Value Object — validated, no identity
+@JvmInline
+value class Email(val value: String) {
+    init {
+        require(value.contains("@")) { "Invalid email: $value" }
+        require(value.length <= 254) { "Email too long" }
+    }
+}
+
+@JvmInline
+value class UserId(val value: String) {
+    init { require(value.isNotBlank()) { "UserId cannot be blank" } }
+}
+
+data class Money(
+    val amount: Long,           // stored in smallest unit (cents/rials)
+    val currency: Currency
+) {
+    operator fun plus(other: Money): Money {
+        require(currency == other.currency) { "Currency mismatch" }
+        return copy(amount = amount + other.amount)
+    }
+
+    fun isPositive(): Boolean = amount > 0
+
+    companion object {
+        val ZERO = Money(0, Currency.IRR)
+    }
+}
+
+data class DateRange(
+    val start: LocalDate,
+    val end: LocalDate
+) {
+    init { require(!end.isBefore(start)) { "End must be after start" } }
+
+    fun contains(date: LocalDate): Boolean = !date.isBefore(start) && !date.isAfter(end)
+    fun durationDays(): Long = ChronoUnit.DAYS.between(start, end)
+}
+```
+
+---
+
+## Enums and Sealed Classes
+
+```kotlin
+// ✅ Simple states — enum
+enum class UserRole { ADMIN, MEMBER, GUEST }
+enum class UserStatus { ACTIVE, SUSPENDED, DELETED }
+enum class OrderStatus { PENDING, PROCESSING, SHIPPED, DELIVERED, CANCELLED }
+
+// ✅ States with data — sealed class
+sealed interface PaymentResult {
+    data class Success(val transactionId: String, val amount: Money) : PaymentResult
+    data class Failed(val reason: String, val code: Int) : PaymentResult
+    data object Cancelled : PaymentResult
+}
+
+sealed interface ValidationResult {
+    data object Valid : ValidationResult
+    data class Invalid(val errors: List<String>) : ValidationResult
+
+    fun isValid(): Boolean = this is Valid
+}
+```
+
+---
+
+## Aggregate Design
+
+```kotlin
+// ✅ Aggregate root — owns its children, enforces consistency
+data class Cart(
+    val id: String,
+    val customerId: String,
+    val items: List<CartItem> = emptyList()
+) {
+    val totalAmount: Money
+        get() = items.fold(Money.ZERO) { acc, item -> acc + item.subtotal }
+
+    val itemCount: Int get() = items.sumOf { it.quantity }
+
+    fun addItem(product: Product, quantity: Int): Cart {
+        require(quantity > 0) { "Quantity must be positive" }
+        val existing = items.find { it.productId == product.id }
+        return if (existing != null) {
+            copy(items = items.map {
+                if (it.productId == product.id)
+                    it.copy(quantity = it.quantity + quantity)
+                else it
+            })
+        } else {
+            copy(items = items + CartItem(product.id, product.name, product.price, quantity))
+        }
+    }
+
+    fun removeItem(productId: String): Cart =
+        copy(items = items.filter { it.productId != productId })
+
+    fun clear(): Cart = copy(items = emptyList())
+}
+
+data class CartItem(
+    val productId: String,
+    val productName: String,
+    val unitPrice: Money,
+    val quantity: Int
+) {
+    val subtotal: Money get() = Money(unitPrice.amount * quantity, unitPrice.currency)
+}
+```
+
+---
+
+## Domain Package Structure
+
+```
+domain/
+├── model/
+│   ├── User.kt
+│   ├── Order.kt
+│   ├── Cart.kt
+│   └── Product.kt
+├── value/
+│   ├── Email.kt
+│   ├── Money.kt
+│   ├── DateRange.kt
+│   └── UserId.kt
+├── repository/
+│   ├── UserRepository.kt
+│   └── OrderRepository.kt
+└── usecase/
+    ├── GetUserUseCase.kt
+    └── PlaceOrderUseCase.kt
+```
+
+---
+
+## Anti-Patterns
+
+- Domain models with `@Entity` or `@SerialName` — domain must not know about persistence or network
+- Anemic domain model — models with only `data class` fields and no behavior; business rules scattered in ViewModel
+- Using `String` for everything — wrap validated concepts in Value Objects (`Email`, `UserId`)
+- Mutable domain models (`var` fields) — always `val` + `copy()`
+- Domain model inheriting from framework class — domain is pure Kotlin only
+
+---
+
+## Related Skills
+
+- `entity-design` — designing Room entities that map to domain models
+- `value-object` — in-depth Value Object patterns
+- `clean-architecture` — where domain sits in the layer structure
+- `dto-mapping` — mapping between domain and data layer models
+- `use-case-design` — business operations that act on domain models

package/skills/Architecture/Entity Design/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: entity-design
+description: >
+  Designing Room database entities for Android.
+  Load this skill when defining @Entity classes, choosing primary keys,
+  modeling relationships (one-to-many, many-to-many), using type converters,
+  handling nullable columns, or mapping between domain models and entities.
+---
+
+# Entity Design
+
+## Overview
+
+Room entities are data classes annotated with `@Entity` that map directly to SQLite tables. Entities live in the Data layer and must never leak into Domain or Presentation. The mapping between Entity and Domain model is always explicit.
+
+---
+
+## Core Principles
+
+- Entities live in **Data layer only** — never imported by Domain or Presentation
+- Entity fields map to **SQLite columns** — use types SQLite supports natively or via TypeConverter
+- Every entity has a **primary key** — prefer `String` UUID over auto-generated `Int` for distributed data
+- **Nullable columns** only when the data is truly optional — not as a lazy default
+- Entity names reflect **storage** — Domain names reflect **business concepts**
+
+---
+
+## Basic Entity
+
+```kotlin
+// ✅ Standard entity
+@Entity(tableName = "users")
+data class UserEntity(
+    @PrimaryKey val id: String,
+    @ColumnInfo(name = "full_name") val name: String,
+    @ColumnInfo(name = "email_address") val email: String,
+    @ColumnInfo(name = "role") val role: String,          // store enum as String
+    @ColumnInfo(name = "is_active") val isActive: Boolean,
+    @ColumnInfo(name = "created_at") val createdAt: Long, // store Instant as epoch millis
+    @ColumnInfo(name = "updated_at") val updatedAt: Long
+)
+
+// ✅ Mapping to/from domain
+fun UserEntity.toDomain(): User = User(
+    id = id,
+    name = name,
+    email = Email(email),
+    role = UserRole.valueOf(role),
+    status = if (isActive) UserStatus.ACTIVE else UserStatus.SUSPENDED,
+    createdAt = Instant.ofEpochMilli(createdAt)
+)
+
+fun User.toEntity(): UserEntity = UserEntity(
+    id = id,
+    name = name,
+    email = email.value,
+    role = role.name,
+    isActive = status == UserStatus.ACTIVE,
+    createdAt = createdAt.toEpochMilli(),
+    updatedAt = System.currentTimeMillis()
+)
+```
+
+---
+
+## Primary Keys
+
+```kotlin
+// ✅ String UUID — preferred for distributed/synced data
+@Entity(tableName = "orders")
+data class OrderEntity(
+    @PrimaryKey val id: String = UUID.randomUUID().toString(),
+    ...
+)
+
+// ✅ Auto-increment Int — for local-only data with no sync
+@Entity(tableName = "drafts")
+data class DraftEntity(
+    @PrimaryKey(autoGenerate = true) val id: Int = 0,
+    val content: String,
+    val createdAt: Long
+)
+
+// ✅ Composite primary key
+@Entity(
+    tableName = "user_roles",
+    primaryKeys = ["user_id", "role_id"]
+)
+data class UserRoleEntity(
+    @ColumnInfo(name = "user_id") val userId: String,
+    @ColumnInfo(name = "role_id") val roleId: String,
+    @ColumnInfo(name = "assigned_at") val assignedAt: Long
+)
+```
+
+---
+
+## Relationships
+
+```kotlin
+// ✅ One-to-many: Order has many OrderItems
+@Entity(tableName = "orders")
+data class OrderEntity(
+    @PrimaryKey val id: String,
+    @ColumnInfo(name = "customer_id") val customerId: String,
+    @ColumnInfo(name = "status") val status: String,
+    @ColumnInfo(name = "placed_at") val placedAt: Long
+)
+
+@Entity(
+    tableName = "order_items",
+    foreignKeys = [
+        ForeignKey(
+            entity = OrderEntity::class,
+            parentColumns = ["id"],
+            childColumns = ["order_id"],
+            onDelete = ForeignKey.CASCADE  // delete items when order deleted
+        )
+    ],
+    indices = [Index("order_id")]  // ✅ index foreign key columns
+)
+data class OrderItemEntity(
+    @PrimaryKey val id: String,
+    @ColumnInfo(name = "order_id") val orderId: String,
+    @ColumnInfo(name = "product_id") val productId: String,
+    @ColumnInfo(name = "quantity") val quantity: Int,
+    @ColumnInfo(name = "unit_price") val unitPrice: Long
+)
+
+// ✅ Relation data class for queries
+data class OrderWithItems(
+    @Embedded val order: OrderEntity,
+    @Relation(
+        parentColumn = "id",
+        entityColumn = "order_id"
+    )
+    val items: List<OrderItemEntity>
+)
+
+// ✅ Many-to-many via junction table
+@Entity(
+    tableName = "product_tags",
+    primaryKeys = ["product_id", "tag_id"]
+)
+data class ProductTagCrossRef(
+    @ColumnInfo(name = "product_id") val productId: String,
+    @ColumnInfo(name = "tag_id") val tagId: String
+)
+
+data class ProductWithTags(
+    @Embedded val product: ProductEntity,
+    @Relation(
+        parentColumn = "id",
+        entityColumn = "id",
+        associateBy = Junction(ProductTagCrossRef::class,
+            parentColumn = "product_id",
+            entityColumn = "tag_id")
+    )
+    val tags: List<TagEntity>
+)
+```
+
+---
+
+## Type Converters
+
+```kotlin
+// ✅ TypeConverter for types Room can't store natively
+class Converters {
+
+    // List<String>
+    @TypeConverter
+    fun fromStringList(value: List<String>): String = value.joinToString(",")
+
+    @TypeConverter
+    fun toStringList(value: String): List<String> =
+        if (value.isBlank()) emptyList() else value.split(",")
+
+    // Enum (store as String, not ordinal — ordinals break on reorder)
+    @TypeConverter
+    fun fromUserRole(role: UserRole): String = role.name
+
+    @TypeConverter
+    fun toUserRole(value: String): UserRole = UserRole.valueOf(value)
+
+    // Instant (store as epoch millis)
+    @TypeConverter
+    fun fromInstant(instant: Instant?): Long? = instant?.toEpochMilli()
+
+    @TypeConverter
+    fun toInstant(value: Long?): Instant? = value?.let { Instant.ofEpochMilli(it) }
+}
+
+// ✅ Register converters on the database
+@Database(entities = [...], version = 1)
+@TypeConverters(Converters::class)
+abstract class AppDatabase : RoomDatabase()
+```
+
+---
+
+## Indices
+
+```kotlin
+// ✅ Index frequently queried columns
+@Entity(
+    tableName = "products",
+    indices = [
+        Index(value = ["category_id"]),                          // single column
+        Index(value = ["name", "category_id"]),                  // composite
+        Index(value = ["sku"], unique = true)                    // unique constraint
+    ]
+)
+data class ProductEntity(
+    @PrimaryKey val id: String,
+    @ColumnInfo(name = "name") val name: String,
+    @ColumnInfo(name = "sku") val sku: String,
+    @ColumnInfo(name = "category_id") val categoryId: String,
+    @ColumnInfo(name = "price") val price: Long
+)
+```
+
+---
+
+## Anti-Patterns
+
+- `@Entity` class used in Domain or Presentation layer — entities are Data layer only
+- Storing enum as ordinal (`role.ordinal`) — breaks when enum values are reordered; use `name`
+- Missing `Index` on foreign key columns — causes full table scan on joins
+- `onDelete = ForeignKey.NO_ACTION` on cascading data — leaves orphan rows
+- Using `@Ignore` to skip fields instead of proper mapping — creates confusion about what's stored
+- Storing complex objects as JSON strings without a TypeConverter — makes querying impossible
+
+---
+
+## Related Skills
+
+- `dao` — DAO patterns for querying entities
+- `room` — Room database setup and configuration
+- `migration` — handling entity schema changes
+- `domain-modeling` — domain models that entities map to
+- `dto-mapping` — mapping patterns between layers
+- `indexing` — in-depth index strategy for performance

package/skills/Architecture/Feature Isolation/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: feature-isolation
+description: >
+  Feature isolation patterns for Android modular projects.
+  Load this skill when ensuring features don't leak implementation details,
+  designing feature APIs, preventing feature-to-feature coupling,
+  or structuring a feature module's internal vs public surface.
+---
+
+# Feature Isolation
+
+## Overview
+
+Feature isolation ensures that each feature module exposes only a minimal, stable public API while hiding all implementation details as `internal`. Features never depend on each other directly. Cross-feature communication happens via shared interfaces, callbacks, or a shared core module — never via direct imports.
+
+---
+
+## Core Principles
+
+- **`internal` by default** — everything inside a feature is `internal` unless explicitly needed outside
+- **No feature-to-feature imports** — features only import from `:core:*` modules
+- **Public API is minimal** — expose only navigation routes, DI modules, and nav graph extensions
+- **Feature entry points are composable extensions** — `NavGraphBuilder.featureGraph()`
+- **Callbacks over navigation coupling** — features receive lambdas for cross-feature navigation
+
+---
+
+## Feature Public Surface
+
+```kotlin
+// ✅ What a feature exposes (public)
+// feature/orders/src/main/kotlin/.../
+
+// 1. Navigation contract
+object OrdersNavigation {
+    const val graphRoute = "orders_graph"
+    const val listRoute = "orders/list"
+    const val detailRoute = "orders/detail/{orderId}"
+
+    fun detailRoute(orderId: String) = "orders/detail/$orderId"
+}
+
+// 2. NavGraph extension — entry point for :app
+fun NavGraphBuilder.ordersGraph(
+    navController: NavController,
+    onNavigateToProduct: (productId: String) -> Unit,   // cross-feature via callback
+    onNavigateToProfile: () -> Unit
+) {
+    navigation(
+        startDestination = OrdersNavigation.listRoute,
+        route = OrdersNavigation.graphRoute
+    ) {
+        composable(OrdersNavigation.listRoute) {
+            OrderListScreen(                              // internal composable
+                onOrderClick = { orderId ->
+                    navController.navigate(OrdersNavigation.detailRoute(orderId))
+                }
+            )
+        }
+        composable(
+            route = OrdersNavigation.detailRoute,
+            arguments = listOf(navArgument("orderId") { type = NavType.StringType })
+        ) { backStackEntry ->
+            val orderId = backStackEntry.arguments?.getString("orderId") ?: return@composable
+            OrderDetailScreen(
+                orderId = orderId,
+                onNavigateToProduct = onNavigateToProduct,
+                onNavigateToProfile = onNavigateToProfile
+            )
+        }
+    }
+}
+
+// 3. Hilt module (internal — bindings are auto-discovered by Hilt)
+@Module
+@InstallIn(SingletonComponent::class)
+internal abstract class OrdersModule {
+    @Binds
+    abstract fun bindOrderRepository(impl: OrderRepositoryImpl): OrderRepository
+}
+```
+
+---
+
+## Internal Implementation
+
+```kotlin
+// ✅ Everything implementation-related is internal
+internal class OrderRepositoryImpl @Inject constructor(
+    private val dao: OrderDao,
+    private val api: OrderApiService
+) : OrderRepository { ... }
+
+internal class GetOrdersUseCase @Inject constructor(
+    private val repository: OrderRepository
+) {
+    operator fun invoke(): Flow<List<Order>> = repository.observeOrders()
+}
+
+@HiltViewModel
+internal class OrderListViewModel @Inject constructor(
+    private val getOrdersUseCase: GetOrdersUseCase
+) : ViewModel() { ... }
+
+@Composable
+internal fun OrderListScreen(onOrderClick: (String) -> Unit) { ... }
+
+@Composable
+internal fun OrderDetailScreen(
+    orderId: String,
+    onNavigateToProduct: (String) -> Unit,
+    onNavigateToProfile: () -> Unit
+) { ... }
+```
+
+---
+
+## Cross-Feature Communication Patterns
+
+```kotlin
+// ✅ Pattern 1: Callbacks (simplest — for navigation)
+// :app wires the callback
+ordersGraph(
+    navController = navController,
+    onNavigateToProduct = { productId ->
+        navController.navigate(CatalogNavigation.detailRoute(productId))
+    },
+    onNavigateToProfile = {
+        navController.navigate(ProfileNavigation.graphRoute)
+    }
+)
+
+// ✅ Pattern 2: Shared interface in :core:domain (for data)
+// :core:domain
+interface ProductInfoProvider {
+    suspend fun getProductSummary(productId: String): Result<ProductSummary>
+}
+
+// :feature:catalog implements it
+internal class ProductInfoProviderImpl @Inject constructor(
+    private val repository: ProductRepository
+) : ProductInfoProvider { ... }
+
+// :feature:orders uses it (no knowledge of :feature:catalog)
+internal class OrderDetailViewModel @Inject constructor(
+    private val productInfoProvider: ProductInfoProvider  // injected, not imported
+) : ViewModel() { ... }
+
+// ✅ Pattern 3: Shared ViewModel in :app (for truly global state)
+// :app — AuthViewModel scoped to root nav graph
+@Composable
+fun AppNavHost(navController: NavHostController) {
+    val appViewModel: AppViewModel = hiltViewModel()  // scoped to root
+    val authState by appViewModel.authState.collectAsStateWithLifecycle()
+
+    ordersGraph(
+        navController = navController,
+        currentUserId = authState.userId   // passed down as param
+    )
+}
+```
+
+---
+
+## Feature API Contract Checklist
+
+```
+✅ Public (exposed to :app):
+  - Navigation object with route constants
+  - NavGraphBuilder extension function
+  - Hilt module (auto-discovered, but still internal annotation on bindings)
+
+❌ Must be internal:
+  - All ViewModel classes
+  - All composable functions
+  - All UseCase classes
+  - All Repository implementations
+  - All DAO and API service classes
+  - All domain model classes (unless in :core:domain)
+  - All Hilt @Binds/@Provides methods
+```
+
+---
+
+## Detecting Isolation Violations
+
+```kotlin
+// ❌ Violation: feature:cart importing from feature:catalog
+import com.example.feature.catalog.domain.model.Product  // WRONG
+
+// ✅ Fix: define what cart needs in :core:domain or via an interface
+// :core:domain
+data class ProductSummary(val id: String, val name: String, val price: Money)
+
+// :feature:cart uses ProductSummary — :feature:catalog maps to it
+```
+
+---
+
+## Anti-Patterns
+
+- `public` on internal ViewModels or composables — leaks implementation, creates coupling
+- Feature importing another feature's ViewModel — use shared ViewModel in :app instead
+- Passing navigation controller deep into composables — use callbacks instead
+- Shared mutable state between features via static/companion objects — use proper DI scope
+- One feature calling another feature's UseCase directly — go through shared interface in :core
+
+---
+
+## Related Skills
+
+- `modularization` — module structure that enables isolation
+- `multi-module-architecture` — full multi-module setup
+- `bounded-context` — conceptual boundaries between features
+- `hilt` — scoping DI across modules correctly
+- `navigation` — wiring navigation between isolated features