android-sdd 1.0.0

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

@@ -0,0 +1,244 @@
+---
+name: room
+description: >
+  Room database setup, configuration, and best practices for Android.
+  Load this skill when setting up Room, defining entities, configuring
+  the database class, handling migrations, or integrating Room with
+  repositories and coroutines/Flow.
+---
+
+# Room
+
+## Overview
+Room is Android's SQLite abstraction library. It provides compile-time SQL verification, coroutine/Flow support, and migration tooling. Room is the standard local database solution for Android and works as the offline-first data source in a Repository pattern.
+
+---
+
+## Core Principles
+
+- Room operations must always run on **Dispatchers.IO** — never main thread
+- Expose **Flow** from DAOs for observable queries — never suspend for reactive data
+- Use **suspend** for one-shot write operations (insert, update, delete)
+- Never expose entities outside the data layer — map to domain models in Repository
+- Always define **indices** on columns used in WHERE and JOIN clauses
+
+---
+
+## Setup
+
+```toml
+# libs.versions.toml
+[versions]
+room = "2.6.1"
+
+[libraries]
+room-runtime = { module = "androidx.room:room-runtime", version.ref = "room" }
+room-ktx     = { module = "androidx.room:room-ktx", version.ref = "room" }
+room-compiler = { module = "androidx.room:room-compiler", version.ref = "room" }
+
+[plugins]
+ksp = { id = "com.google.devtools.ksp", version = "2.0.0-1.0.21" }
+```
+
+```kotlin
+// build.gradle.kts
+plugins {
+    alias(libs.plugins.ksp)
+}
+
+dependencies {
+    implementation(libs.room.runtime)
+    implementation(libs.room.ktx)
+    ksp(libs.room.compiler)
+}
+
+// ✅ Schema export — for migration verification
+ksp {
+    arg("room.schemaLocation", "$projectDir/schemas")
+    arg("room.incremental", "true")
+}
+```
+
+---
+
+## Entity
+
+```kotlin
+// ✅ Entity — maps to a database table
+@Entity(
+    tableName = "users",
+    indices = [
+        Index(value = ["email"], unique = true),
+        Index(value = ["status"])
+    ]
+)
+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,
+    @ColumnInfo(name = "updated_at") val updatedAt: Long
+)
+
+// ✅ Embedded object
+data class Address(
+    val street: String,
+    val city: String,
+    val country: String
+)
+
+@Entity(tableName = "users")
+data class UserEntity(
+    @PrimaryKey val id: String,
+    val name: String,
+    @Embedded val address: Address
+)
+
+// ✅ Relation — one-to-many
+data class UserWithOrders(
+    @Embedded val user: UserEntity,
+    @Relation(
+        parentColumn = "id",
+        entityColumn = "user_id"
+    )
+    val orders: List<OrderEntity>
+)
+```
+
+---
+
+## Database Class
+
+```kotlin
+// ✅ Database definition
+@Database(
+    entities = [
+        UserEntity::class,
+        OrderEntity::class,
+        ProductEntity::class
+    ],
+    version = 3,
+    exportSchema = true  // always true — needed for migration testing
+)
+@TypeConverters(Converters::class)
+abstract class AppDatabase : RoomDatabase() {
+
+    abstract fun userDao(): UserDao
+    abstract fun orderDao(): OrderDao
+    abstract fun productDao(): ProductDao
+
+    companion object {
+        @Volatile
+        private var INSTANCE: AppDatabase? = null
+
+        fun getInstance(context: Context): AppDatabase {
+            return INSTANCE ?: synchronized(this) {
+                Room.databaseBuilder(
+                    context.applicationContext,
+                    AppDatabase::class.java,
+                    "app_database"
+                )
+                .addMigrations(MIGRATION_1_2, MIGRATION_2_3)
+                .fallbackToDestructiveMigrationOnDowngrade()
+                .build()
+                .also { INSTANCE = it }
+            }
+        }
+    }
+}
+
+// ✅ With Hilt — preferred over manual singleton
+@Module
+@InstallIn(SingletonComponent::class)
+object DatabaseModule {
+
+    @Provides
+    @Singleton
+    fun provideDatabase(@ApplicationContext context: Context): AppDatabase =
+        Room.databaseBuilder(context, AppDatabase::class.java, "app_database")
+            .addMigrations(MIGRATION_1_2, MIGRATION_2_3)
+            .build()
+
+    @Provides
+    fun provideUserDao(database: AppDatabase): UserDao = database.userDao()
+}
+```
+
+---
+
+## Type Converters
+
+```kotlin
+// ✅ For types Room can't store natively
+class Converters {
+
+    @TypeConverter
+    fun fromTimestamp(value: Long?): Date? =
+        value?.let { Date(it) }
+
+    @TypeConverter
+    fun dateToTimestamp(date: Date?): Long? =
+        date?.time
+
+    @TypeConverter
+    fun fromStringList(value: String): List<String> =
+        Json.decodeFromString(value)
+
+    @TypeConverter
+    fun toStringList(list: List<String>): String =
+        Json.encodeToString(list)
+}
+```
+
+---
+
+## Integration with Repository
+
+```kotlin
+// ✅ Repository maps Entity ↔ Domain model
+class UserRepository @Inject constructor(
+    private val userDao: UserDao,
+    private val userMapper: UserMapper
+) {
+
+    // Observable query — Flow
+    fun observeUsers(): Flow<List<User>> =
+        userDao.observeAll()
+            .map { entities -> entities.map { userMapper.toDomain(it) } }
+
+    // One-shot read
+    suspend fun getUserById(id: String): User? =
+        userDao.getById(id)?.let { userMapper.toDomain(it) }
+
+    // Write operations
+    suspend fun saveUser(user: User) {
+        userDao.upsert(userMapper.toEntity(user))
+    }
+
+    suspend fun deleteUser(id: String) {
+        userDao.deleteById(id)
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Running Room queries on the main thread — causes ANR
+- Exposing `UserEntity` outside the data layer — couples UI to DB schema
+- Using `allowMainThreadQueries()` — only acceptable in tests
+- Not exporting schema (`exportSchema = false`) — can't write or test migrations
+- Missing indices on queried columns — slow queries on large datasets
+- Using `@PrimaryKey(autoGenerate = true)` with String IDs — use UUID instead
+- Accessing database instance directly from ViewModel — always go through Repository
+
+---
+
+## Related Skills
+- `dao` — DAO queries and operations
+- `migration` — database schema migrations
+- `dto-mapping` — Entity ↔ Domain mapping
+- `repository-pattern` — Repository wrapping Room
+- `hilt` — injecting Room database and DAOs

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

@@ -0,0 +1,255 @@
+---
+name: sqlite
+description: >
+  SQLite fundamentals and direct SQLite usage in Android.
+  Load this skill when working with raw SQLite queries, SupportSQLiteDatabase
+  in migrations, understanding SQLite constraints, or diagnosing SQL issues
+  that go beyond Room's abstraction.
+---
+
+# SQLite
+
+## Overview
+SQLite is the embedded relational database engine used by Android. Room is built on top of SQLite and handles most use cases. Direct SQLite access is needed in migrations, performance diagnostics, and edge cases that Room doesn't cover. Understanding SQLite's constraints prevents data integrity bugs.
+
+---
+
+## Core Principles
+
+- Prefer Room over raw SQLite — use raw SQLite only when Room is insufficient
+- SQLite is **not thread-safe** — always use Room's dispatcher management
+- SQLite uses **dynamic typing** — enforce types via constraints, not the engine
+- SQLite does **not enforce foreign keys by default** — must be enabled explicitly
+- Transactions are the primary tool for performance and atomicity
+
+---
+
+## SQLite Type System
+
+```sql
+-- SQLite storage classes (not strict types)
+NULL     -- null value
+INTEGER  -- signed integer (1, 2, 3, 4, 6, or 8 bytes)
+REAL     -- floating point (8-byte IEEE 754)
+TEXT     -- UTF-8/16 string
+BLOB     -- binary data
+
+-- Room maps Kotlin types to SQLite:
+-- String  → TEXT
+-- Int     → INTEGER
+-- Long    → INTEGER
+-- Double  → REAL
+-- Boolean → INTEGER (0 or 1)
+-- ByteArray → BLOB
+```
+
+---
+
+## Foreign Keys — Must Be Enabled
+
+```kotlin
+// ✅ Enable foreign key enforcement in Room
+Room.databaseBuilder(context, AppDatabase::class.java, "app_database")
+    .addCallback(object : RoomDatabase.Callback() {
+        override fun onOpen(db: SupportSQLiteDatabase) {
+            db.execSQL("PRAGMA foreign_keys = ON")
+        }
+    })
+    .build()
+
+// Without this, foreign key constraints are silently ignored
+```
+
+---
+
+## Direct SQL in Migrations
+
+```kotlin
+val MIGRATION_3_4 = object : Migration(3, 4) {
+    override fun migrate(database: SupportSQLiteDatabase) {
+
+        // ✅ Create table
+        database.execSQL("""
+            CREATE TABLE IF NOT EXISTS products (
+                id TEXT NOT NULL PRIMARY KEY,
+                name TEXT NOT NULL,
+                price INTEGER NOT NULL DEFAULT 0,
+                category TEXT NOT NULL,
+                created_at INTEGER NOT NULL
+            )
+        """)
+
+        // ✅ Add column
+        database.execSQL("ALTER TABLE users ADD COLUMN avatar_url TEXT")
+
+        // ✅ Create index
+        database.execSQL(
+            "CREATE INDEX IF NOT EXISTS index_products_category ON products(category)"
+        )
+
+        // ✅ Create unique index
+        database.execSQL(
+            "CREATE UNIQUE INDEX IF NOT EXISTS index_users_email ON users(email)"
+        )
+
+        // ✅ Drop index
+        database.execSQL("DROP INDEX IF EXISTS old_index_name")
+
+        // ✅ Drop table
+        database.execSQL("DROP TABLE IF EXISTS old_table")
+
+        // ✅ Rename table (within migration)
+        database.execSQL("ALTER TABLE users_temp RENAME TO users")
+    }
+}
+```
+
+---
+
+## Rename Column (Pre-API 29)
+
+```kotlin
+// SQLite supports RENAME COLUMN only from API 29 / SQLite 3.25.0
+// For older support — recreate table
+
+val MIGRATION_RENAME = object : Migration(5, 6) {
+    override fun migrate(database: SupportSQLiteDatabase) {
+        // 1. Create new table with correct schema
+        database.execSQL("""
+            CREATE TABLE users_new (
+                id TEXT NOT NULL PRIMARY KEY,
+                full_name TEXT NOT NULL,   -- renamed from 'name'
+                email TEXT NOT NULL,
+                created_at INTEGER NOT NULL
+            )
+        """)
+        // 2. Copy data
+        database.execSQL("""
+            INSERT INTO users_new (id, full_name, email, created_at)
+            SELECT id, name, email, created_at FROM users
+        """)
+        // 3. Drop old table
+        database.execSQL("DROP TABLE users")
+        // 4. Rename new table
+        database.execSQL("ALTER TABLE users_new RENAME TO users")
+        // 5. Recreate indices
+        database.execSQL("CREATE INDEX index_users_email ON users(email)")
+    }
+}
+```
+
+---
+
+## Transactions for Performance
+
+```kotlin
+// ✅ Wrap bulk inserts in a transaction — dramatically faster
+val MIGRATION_BULK = object : Migration(6, 7) {
+    override fun migrate(database: SupportSQLiteDatabase) {
+        database.beginTransaction()
+        try {
+            database.execSQL("ALTER TABLE orders ADD COLUMN tax INTEGER NOT NULL DEFAULT 0")
+            // backfill
+            database.execSQL("UPDATE orders SET tax = CAST(total * 0.09 AS INTEGER)")
+            database.setTransactionSuccessful()
+        } finally {
+            database.endTransaction()
+        }
+    }
+}
+
+// ✅ Room handles transactions via @Transaction in DAOs
+// Use raw transactions only in migrations or SupportSQLiteDatabase contexts
+```
+
+---
+
+## Useful PRAGMA Commands
+
+```sql
+-- Check schema integrity
+PRAGMA integrity_check;
+
+-- Get table info (columns, types, constraints)
+PRAGMA table_info(users);
+
+-- List all tables
+SELECT name FROM sqlite_master WHERE type='table';
+
+-- List all indices
+SELECT name FROM sqlite_master WHERE type='index';
+
+-- Get foreign key list for a table
+PRAGMA foreign_key_list(orders);
+
+-- Check foreign key violations
+PRAGMA foreign_key_check;
+
+-- Get current database version (Room version)
+PRAGMA user_version;
+
+-- WAL mode — better concurrent read performance
+PRAGMA journal_mode = WAL;
+```
+
+---
+
+## WAL Mode
+
+```kotlin
+// ✅ Enable WAL (Write-Ahead Logging) for better read concurrency
+Room.databaseBuilder(context, AppDatabase::class.java, "app_database")
+    .setJournalMode(RoomDatabase.JournalMode.WRITE_AHEAD_LOGGING)
+    .build()
+
+// WAL benefits:
+// - Readers don't block writers
+// - Writers don't block readers
+// - Better performance for concurrent access patterns
+// Default in Room — explicitly set if needed
+```
+
+---
+
+## Querying System Tables
+
+```kotlin
+// ✅ Check if a table exists (useful in migrations)
+fun SupportSQLiteDatabase.tableExists(tableName: String): Boolean {
+    val cursor = query(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name=?",
+        arrayOf(tableName)
+    )
+    return cursor.use { it.count > 0 }
+}
+
+// ✅ Check if a column exists (useful in migrations)
+fun SupportSQLiteDatabase.columnExists(tableName: String, columnName: String): Boolean {
+    val cursor = query("PRAGMA table_info($tableName)", null)
+    return cursor.use { c ->
+        while (c.moveToNext()) {
+            if (c.getString(c.getColumnIndex("name")) == columnName) return true
+        }
+        false
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Raw SQLite without Room — loses type safety, compile-time checks, and Flow support
+- Not enabling foreign keys (`PRAGMA foreign_keys = ON`) — constraints silently ignored
+- String concatenation in SQL — use parameterized queries to prevent SQL injection
+- Bulk operations outside transactions — orders of magnitude slower
+- Using `AUTOINCREMENT` keyword — use `INTEGER PRIMARY KEY` instead (simpler, faster)
+- Assuming column order is stable — always use column names, not positions
+
+---
+
+## Related Skills
+- `room` — Room as the primary SQLite abstraction
+- `dao` — Room DAO for type-safe queries
+- `migration` — using SupportSQLiteDatabase in migrations
+- `indexing` — index creation and management