android-sdd 1.0.0

package/skills/Data Layer/DAO/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: dao
+description: >
+  Room DAO design — queries, inserts, updates, deletes, transactions, and Flow.
+  Load this skill when writing DAO interfaces, designing SQL queries,
+  handling reactive queries with Flow, or performing batch operations.
+---
+
+# DAO (Data Access Object)
+
+## Overview
+A DAO is the interface through which the app accesses the Room database. It defines the contract between the app and the database — what queries to run, what data to return, and how writes happen. DAOs are generated at compile time and SQL is verified at compile time.
+
+---
+
+## Core Principles
+
+- DAOs are **interfaces or abstract classes** — never concrete classes
+- Use **Flow** for observable queries — use **suspend** for one-shot operations
+- Prefer **upsert** over separate insert + update logic
+- Keep queries **focused** — one query, one purpose
+- Use **@Transaction** for operations that must be atomic
+
+---
+
+## Basic DAO Structure
+
+```kotlin
+@Dao
+interface UserDao {
+
+    // ✅ Observable query — Flow
+    @Query("SELECT * FROM users ORDER BY full_name ASC")
+    fun observeAll(): Flow<List<UserEntity>>
+
+    // ✅ Observable single item
+    @Query("SELECT * FROM users WHERE id = :id")
+    fun observeById(id: String): Flow<UserEntity?>
+
+    // ✅ One-shot query
+    @Query("SELECT * FROM users WHERE id = :id")
+    suspend fun getById(id: String): UserEntity?
+
+    // ✅ Upsert — insert or replace on conflict
+    @Upsert
+    suspend fun upsert(user: UserEntity)
+
+    @Upsert
+    suspend fun upsertAll(users: List<UserEntity>)
+
+    // ✅ Insert with conflict strategy
+    @Insert(onConflict = OnConflictStrategy.IGNORE)
+    suspend fun insertIfNotExists(user: UserEntity)
+
+    // ✅ Update
+    @Update
+    suspend fun update(user: UserEntity)
+
+    // ✅ Delete by entity
+    @Delete
+    suspend fun delete(user: UserEntity)
+
+    // ✅ Delete by ID
+    @Query("DELETE FROM users WHERE id = :id")
+    suspend fun deleteById(id: String)
+
+    // ✅ Delete all
+    @Query("DELETE FROM users")
+    suspend fun deleteAll()
+}
+```
+
+---
+
+## Filtered and Sorted Queries
+
+```kotlin
+@Dao
+interface UserDao {
+
+    // ✅ Filter by column
+    @Query("SELECT * FROM users WHERE status = :status ORDER BY full_name ASC")
+    fun observeByStatus(status: String): Flow<List<UserEntity>>
+
+    // ✅ Search with LIKE
+    @Query("SELECT * FROM users WHERE full_name LIKE '%' || :query || '%' OR email LIKE '%' || :query || '%'")
+    fun search(query: String): Flow<List<UserEntity>>
+
+    // ✅ Filter with IN clause
+    @Query("SELECT * FROM users WHERE id IN (:ids)")
+    suspend fun getByIds(ids: List<String>): List<UserEntity>
+
+    // ✅ Count
+    @Query("SELECT COUNT(*) FROM users WHERE status = :status")
+    fun observeCountByStatus(status: String): Flow<Int>
+
+    // ✅ Exists check
+    @Query("SELECT EXISTS(SELECT 1 FROM users WHERE email = :email)")
+    suspend fun existsByEmail(email: String): Boolean
+
+    // ✅ Pagination with LIMIT and OFFSET
+    @Query("SELECT * FROM users ORDER BY created_at DESC LIMIT :limit OFFSET :offset")
+    suspend fun getPage(limit: Int, offset: Int): List<UserEntity>
+}
+```
+
+---
+
+## Joins and Relations
+
+```kotlin
+@Dao
+interface UserDao {
+
+    // ✅ Join query — returns a POJO (not entity)
+    @Query("""
+        SELECT u.*, o.id as order_id, o.total as order_total
+        FROM users u
+        INNER JOIN orders o ON u.id = o.user_id
+        WHERE u.id = :userId
+    """)
+    suspend fun getUserWithOrders(userId: String): UserWithOrdersEntity?
+
+    // ✅ @Transaction for relation queries
+    @Transaction
+    @Query("SELECT * FROM users WHERE id = :userId")
+    suspend fun getUserWithProfile(userId: String): UserWithProfileEntity?
+
+    // ✅ @Transaction for all @Relation queries
+    @Transaction
+    @Query("SELECT * FROM users")
+    fun observeAllWithOrders(): Flow<List<UserWithOrdersEntity>>
+}
+```
+
+---
+
+## Transactions
+
+```kotlin
+@Dao
+interface UserDao {
+
+    // ✅ @Transaction — atomic multi-step operation
+    @Transaction
+    suspend fun replaceAll(users: List<UserEntity>) {
+        deleteAll()
+        upsertAll(users)
+    }
+
+    @Transaction
+    suspend fun transferOrders(fromUserId: String, toUserId: String) {
+        updateOrderOwner(fromUserId, toUserId)
+        updateUserOrderCount(fromUserId)
+        updateUserOrderCount(toUserId)
+    }
+
+    @Query("UPDATE orders SET user_id = :toUserId WHERE user_id = :fromUserId")
+    suspend fun updateOrderOwner(fromUserId: String, toUserId: String)
+
+    @Query("UPDATE users SET order_count = (SELECT COUNT(*) FROM orders WHERE user_id = :userId) WHERE id = :userId")
+    suspend fun updateUserOrderCount(userId: String)
+}
+```
+
+---
+
+## Return Types Reference
+
+| Operation | Return Type |
+|-----------|------------|
+| Observable query (list) | `Flow<List<Entity>>` |
+| Observable query (single) | `Flow<Entity?>` |
+| Observable count | `Flow<Int>` |
+| One-shot query | `suspend fun`: `Entity?`, `List<Entity>` |
+| Insert | `suspend fun`: `Long` (row id) or `Unit` |
+| Upsert | `suspend fun`: `Unit` |
+| Update | `suspend fun`: `Int` (rows affected) or `Unit` |
+| Delete | `suspend fun`: `Int` (rows affected) or `Unit` |
+
+---
+
+## POJOs for Custom Queries
+
+```kotlin
+// ✅ POJO for projection queries — not an @Entity
+data class UserSummary(
+    val id: String,
+    @ColumnInfo(name = "full_name") val name: String,
+    @ColumnInfo(name = "order_count") val orderCount: Int
+)
+
+@Dao
+interface UserDao {
+    @Query("""
+        SELECT u.id, u.full_name, COUNT(o.id) as order_count
+        FROM users u
+        LEFT JOIN orders o ON u.id = o.user_id
+        GROUP BY u.id
+        ORDER BY order_count DESC
+    """)
+    fun observeUserSummaries(): Flow<List<UserSummary>>
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Returning entities directly from Repository — always map to domain models
+- Using `LiveData` instead of `Flow` in new code — Flow is preferred
+- Missing `@Transaction` on `@Relation` queries — causes inconsistent data reads
+- Using `suspend` for observable queries — use `Flow` instead
+- Writing business logic in SQL queries — keep queries data-focused
+- Not using `@Upsert` when insert-or-update is needed — avoids conflict handling mistakes
+- Large `IN` clauses with dynamic lists — SQLite has limits; batch if needed
+
+---
+
+## Related Skills
+- `room` — Room database setup and configuration
+- `migration` — schema changes and migrations
+- `dto-mapping` — Entity ↔ Domain model mapping
+- `repository-pattern` — Repository wrapping DAOs
+- `coroutine` — Dispatchers.IO for DAO operations

package/skills/Data Layer/DTO Mapping/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: dto-mapping
+description: >
+  DTO to domain model mapping patterns for Android.
+  Load this skill when writing mappers between API responses (DTOs),
+  database entities, and domain models — or when designing the data
+  layer boundary in a clean architecture project.
+---
+
+# DTO Mapping
+
+## Overview
+DTO (Data Transfer Object) mapping is the translation between data representations across layer boundaries. API responses (DTOs), database rows (Entities), and domain models are separate types — mapping between them keeps each layer independent and testable.
+
+---
+
+## Core Principles
+
+- **Domain models are the language of business logic** — pure Kotlin, no framework annotations
+- **DTOs mirror the API contract** — annotated with `@Serializable`, snake_case fields
+- **Entities mirror the DB schema** — annotated with `@Entity`, `@ColumnInfo`
+- Mapping always happens at the **repository layer** — never in ViewModel or UseCase
+- Mappers are **pure functions** — no side effects, no dependencies
+
+---
+
+## Layer Boundaries
+
+```
+Network (JSON)          DTO             @Serializable
+       ↓ mapper
+Domain Layer         Domain Model       Pure Kotlin data class
+       ↓ mapper
+Database (SQLite)       Entity          @Entity, @ColumnInfo
+```
+
+---
+
+## Domain Model
+
+```kotlin
+// ✅ Pure Kotlin — no framework dependencies
+data class User(
+    val id: String,
+    val name: String,
+    val email: String,
+    val status: UserStatus,
+    val createdAt: Instant
+)
+
+enum class UserStatus { ACTIVE, INACTIVE, PENDING }
+```
+
+---
+
+## DTO (API Response)
+
+```kotlin
+// ✅ Mirrors API contract — annotated for serialization
+@Serializable
+data class UserDto(
+    @SerialName("user_id") val id: String,
+    @SerialName("full_name") val name: String,
+    @SerialName("email_address") val email: String,
+    @SerialName("account_status") val status: String,
+    @SerialName("created_timestamp") val createdAt: Long
+)
+```
+
+---
+
+## Entity (Database Row)
+
+```kotlin
+// ✅ Mirrors DB schema — annotated for Room
+@Entity(tableName = "users")
+data class UserEntity(
+    @PrimaryKey val id: String,
+    @ColumnInfo(name = "full_name") val name: String,
+    @ColumnInfo(name = "email") val email: String,
+    @ColumnInfo(name = "status") val status: String,
+    @ColumnInfo(name = "created_at") val createdAt: Long
+)
+```
+
+---
+
+## Mapper — Extension Functions (Simple)
+
+```kotlin
+// ✅ Extension function mapper — concise for simple cases
+fun UserDto.toDomain(): User = User(
+    id = id,
+    name = name,
+    email = email,
+    status = UserStatus.valueOf(status.uppercase()),
+    createdAt = Instant.ofEpochMilli(createdAt)
+)
+
+fun UserEntity.toDomain(): User = User(
+    id = id,
+    name = name,
+    email = email,
+    status = UserStatus.valueOf(status),
+    createdAt = Instant.ofEpochMilli(createdAt)
+)
+
+fun User.toEntity(): UserEntity = UserEntity(
+    id = id,
+    name = name,
+    email = email,
+    status = status.name,
+    createdAt = createdAt.toEpochMilli()
+)
+
+fun User.toDto(): UserDto = UserDto(
+    id = id,
+    name = name,
+    email = email,
+    status = status.name.lowercase(),
+    createdAt = createdAt.toEpochMilli()
+)
+```
+
+---
+
+## Mapper — Class-Based (Testable, Injectable)
+
+```kotlin
+// ✅ Class mapper — preferred when mapping has dependencies or is complex
+class UserMapper @Inject constructor(
+    private val clock: Clock = Clock.systemUTC()
+) {
+    fun toDomain(dto: UserDto): User = User(
+        id = dto.id,
+        name = dto.name.trim(),
+        email = dto.email.lowercase(),
+        status = mapStatus(dto.status),
+        createdAt = Instant.ofEpochMilli(dto.createdAt)
+    )
+
+    fun toDomain(entity: UserEntity): User = User(
+        id = entity.id,
+        name = entity.name,
+        email = entity.email,
+        status = UserStatus.valueOf(entity.status),
+        createdAt = Instant.ofEpochMilli(entity.createdAt)
+    )
+
+    fun toEntity(domain: User): UserEntity = UserEntity(
+        id = domain.id,
+        name = domain.name,
+        email = domain.email,
+        status = domain.status.name,
+        createdAt = domain.createdAt.toEpochMilli()
+    )
+
+    private fun mapStatus(raw: String): UserStatus = when (raw.lowercase()) {
+        "active"   -> UserStatus.ACTIVE
+        "inactive" -> UserStatus.INACTIVE
+        else       -> UserStatus.PENDING
+    }
+}
+```
+
+---
+
+## Repository Using Mapper
+
+```kotlin
+class UserRepository @Inject constructor(
+    private val userApi: UserApi,
+    private val userDao: UserDao,
+    private val userMapper: UserMapper
+) {
+
+    fun observeUsers(): Flow<List<User>> =
+        userDao.observeAll()
+            .map { entities -> entities.map(userMapper::toDomain) }
+
+    suspend fun refreshUsers() {
+        val dtos = userApi.getUsers()
+        val entities = dtos.map(userMapper::toEntity)
+        userDao.upsertAll(entities)
+    }
+
+    suspend fun createUser(user: User): User {
+        val dto = userApi.createUser(user.toDto())
+        val entity = userMapper.toEntity(userMapper.toDomain(dto))
+        userDao.upsert(entity)
+        return userMapper.toDomain(dto)
+    }
+}
+```
+
+---
+
+## Handling Nullable / Missing Fields
+
+```kotlin
+// ✅ Provide sensible defaults — never return null for required domain fields
+fun UserDto.toDomain(): User = User(
+    id = id,
+    name = name.takeIf { it.isNotBlank() } ?: "Unknown",
+    email = email,
+    status = runCatching { UserStatus.valueOf(status.uppercase()) }
+        .getOrDefault(UserStatus.PENDING),
+    createdAt = if (createdAt > 0) Instant.ofEpochMilli(createdAt) else Instant.now()
+)
+```
+
+---
+
+## Testing Mappers
+
+```kotlin
+// ✅ Mappers are pure — easy to unit test without mocks
+class UserMapperTest {
+
+    private val mapper = UserMapper()
+
+    @Test
+    fun `DTO maps to domain correctly`() {
+        val dto = UserDto(
+            id = "1",
+            name = "Ali Rezaei",
+            email = "ali@example.com",
+            status = "active",
+            createdAt = 1_700_000_000_000L
+        )
+
+        val domain = mapper.toDomain(dto)
+
+        assertEquals("1", domain.id)
+        assertEquals("Ali Rezaei", domain.name)
+        assertEquals(UserStatus.ACTIVE, domain.status)
+    }
+
+    @Test
+    fun `domain maps to entity and back`() {
+        val user = User("1", "Ali", "ali@example.com", UserStatus.ACTIVE, Instant.now())
+        val entity = mapper.toEntity(user)
+        val restored = mapper.toDomain(entity)
+
+        assertEquals(user.id, restored.id)
+        assertEquals(user.status, restored.status)
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Using DTOs directly in ViewModel or Compose — couples UI to API contract
+- Using Entities in domain or UI layer — couples business logic to DB schema
+- Mapping in ViewModel — mapping belongs in repository/data layer
+- Not handling unknown enum values — crashes when API adds a new status
+- Giant mapper files — split by domain entity
+- Returning `null` for required domain fields — use defaults or `Result<T>`
+
+---
+
+## Related Skills
+- `serialization` — DTO serialization setup
+- `room` — Entity design and Room setup
+- `repository-pattern` — repository using mappers
+- `entity-design` — designing domain entities
+- `domain-modeling` — domain model design principles