android-sdd 1.0.0

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

@@ -0,0 +1,264 @@
+---
+name: datastore
+description: >
+  Jetpack DataStore (Preferences) setup and usage for Android.
+  Load this skill when storing simple key-value settings, user preferences,
+  feature flags, or any small structured data that doesn't need a full database.
+---
+
+# DataStore (Preferences)
+
+## Overview
+Jetpack DataStore is the modern replacement for SharedPreferences. It stores key-value pairs (Preferences DataStore) or typed objects (Proto DataStore) asynchronously using coroutines and Flow. It is safe to call from the main thread and handles concurrent access correctly.
+
+---
+
+## Core Principles
+
+- Use DataStore for **small, simple data** — user settings, session state, feature flags
+- Use Room for **structured, queryable data** — DataStore is not a database
+- **Never block** to read DataStore — always collect as Flow
+- Create **one DataStore instance** per file — never multiple instances for the same file
+- Inject DataStore via **Hilt** — never create it in a ViewModel or Repository directly
+
+---
+
+## Setup
+
+```toml
+# libs.versions.toml
+[versions]
+datastore = "1.1.1"
+
+[libraries]
+datastore-preferences = { module = "androidx.datastore:datastore-preferences", version.ref = "datastore" }
+```
+
+```kotlin
+// build.gradle.kts
+dependencies {
+    implementation(libs.datastore.preferences)
+}
+```
+
+---
+
+## Creating DataStore
+
+```kotlin
+// ✅ Create via extension — one instance per file
+val Context.userPreferencesDataStore: DataStore<Preferences> by preferencesDataStore(
+    name = "user_preferences"
+)
+
+// ✅ Provide via Hilt — singleton
+@Module
+@InstallIn(SingletonComponent::class)
+object DataStoreModule {
+
+    @Provides
+    @Singleton
+    fun provideUserPreferencesDataStore(
+        @ApplicationContext context: Context
+    ): DataStore<Preferences> = context.userPreferencesDataStore
+}
+```
+
+---
+
+## Defining Keys
+
+```kotlin
+// ✅ Define all keys in a companion object or object
+object UserPreferencesKeys {
+    val IS_DARK_MODE = booleanPreferencesKey("is_dark_mode")
+    val LANGUAGE = stringPreferencesKey("language")
+    val FONT_SIZE = intPreferencesKey("font_size")
+    val LAST_SYNC = longPreferencesKey("last_sync_timestamp")
+    val ONBOARDING_COMPLETE = booleanPreferencesKey("onboarding_complete")
+}
+```
+
+---
+
+## Repository Pattern
+
+```kotlin
+// ✅ Wrap DataStore in a Repository — don't access it directly from ViewModel
+class UserPreferencesRepository @Inject constructor(
+    private val dataStore: DataStore<Preferences>
+) {
+
+    // ✅ Read — expose as Flow
+    val isDarkMode: Flow<Boolean> = dataStore.data
+        .catch { e ->
+            if (e is IOException) emit(emptyPreferences())
+            else throw e
+        }
+        .map { prefs -> prefs[UserPreferencesKeys.IS_DARK_MODE] ?: false }
+
+    val language: Flow<String> = dataStore.data
+        .catch { e ->
+            if (e is IOException) emit(emptyPreferences())
+            else throw e
+        }
+        .map { prefs -> prefs[UserPreferencesKeys.LANGUAGE] ?: "en" }
+
+    // ✅ Read all at once — single object
+    val userPreferences: Flow<UserPreferences> = dataStore.data
+        .catch { e ->
+            if (e is IOException) emit(emptyPreferences())
+            else throw e
+        }
+        .map { prefs ->
+            UserPreferences(
+                isDarkMode = prefs[UserPreferencesKeys.IS_DARK_MODE] ?: false,
+                language = prefs[UserPreferencesKeys.LANGUAGE] ?: "en",
+                fontSize = prefs[UserPreferencesKeys.FONT_SIZE] ?: 14
+            )
+        }
+
+    // ✅ Write — suspend function
+    suspend fun setDarkMode(enabled: Boolean) {
+        dataStore.edit { prefs ->
+            prefs[UserPreferencesKeys.IS_DARK_MODE] = enabled
+        }
+    }
+
+    suspend fun setLanguage(language: String) {
+        dataStore.edit { prefs ->
+            prefs[UserPreferencesKeys.LANGUAGE] = language
+        }
+    }
+
+    // ✅ Clear all preferences
+    suspend fun clearAll() {
+        dataStore.edit { it.clear() }
+    }
+}
+
+// ✅ Domain model for preferences
+data class UserPreferences(
+    val isDarkMode: Boolean,
+    val language: String,
+    val fontSize: Int
+)
+```
+
+---
+
+## Usage in ViewModel
+
+```kotlin
+@HiltViewModel
+class SettingsViewModel @Inject constructor(
+    private val preferencesRepository: UserPreferencesRepository
+) : ViewModel() {
+
+    val preferences: StateFlow<UserPreferences> = preferencesRepository.userPreferences
+        .stateIn(
+            scope = viewModelScope,
+            started = SharingStarted.WhileSubscribed(5_000),
+            initialValue = UserPreferences(isDarkMode = false, language = "en", fontSize = 14)
+        )
+
+    fun onDarkModeToggled(enabled: Boolean) {
+        viewModelScope.launch {
+            preferencesRepository.setDarkMode(enabled)
+        }
+    }
+
+    fun onLanguageSelected(language: String) {
+        viewModelScope.launch {
+            preferencesRepository.setLanguage(language)
+        }
+    }
+}
+```
+
+---
+
+## Atomic Updates
+
+```kotlin
+// ✅ update multiple keys atomically in one edit block
+suspend fun saveUserSession(userId: String, token: String, expiresAt: Long) {
+    dataStore.edit { prefs ->
+        prefs[USER_ID_KEY] = userId
+        prefs[TOKEN_KEY] = token
+        prefs[EXPIRES_AT_KEY] = expiresAt
+    }
+}
+
+// ✅ Conditional update
+suspend fun incrementLaunchCount() {
+    dataStore.edit { prefs ->
+        val current = prefs[LAUNCH_COUNT_KEY] ?: 0
+        prefs[LAUNCH_COUNT_KEY] = current + 1
+    }
+}
+```
+
+---
+
+## Error Handling
+
+```kotlin
+// ✅ Always handle IOException — disk read/write can fail
+val preferences: Flow<AppPreferences> = dataStore.data
+    .catch { exception ->
+        if (exception is IOException) {
+            // Emit defaults on read error
+            emit(emptyPreferences())
+        } else {
+            throw exception  // re-throw unexpected errors
+        }
+    }
+    .map { prefs -> prefs.toAppPreferences() }
+```
+
+---
+
+## DataStore vs SharedPreferences
+
+| | DataStore | SharedPreferences |
+|--|-----------|------------------|
+| Thread safety | ✅ Coroutines | ❌ Partial |
+| Main thread safe | ✅ Yes | ❌ No (apply is async, commit blocks) |
+| Strongly typed | ✅ Yes | ❌ No |
+| Error handling | ✅ Flow catch | ❌ Silent |
+| Transactions | ✅ edit {} | ❌ No |
+| Migration | ✅ SharedPreferencesMigration | — |
+
+---
+
+## Migrating from SharedPreferences
+
+```kotlin
+// ✅ Migrate existing SharedPreferences data
+val dataStore = context.createDataStore(
+    name = "user_preferences",
+    migrations = listOf(
+        SharedPreferencesMigration(context, "legacy_prefs")
+    )
+)
+```
+
+---
+
+## Anti-Patterns
+
+- Multiple DataStore instances for same file — data corruption risk
+- Calling `dataStore.data.first()` in a loop — use Flow collection instead
+- Storing large objects or lists in DataStore — use Room instead
+- Not catching `IOException` — unhandled disk errors crash the app
+- Accessing DataStore directly in ViewModel — wrap in Repository
+- Using DataStore for data that needs querying/filtering — use Room
+
+---
+
+## Related Skills
+- `proto-datastore` — typed object storage with Protobuf
+- `repository-pattern` — wrapping DataStore in a Repository
+- `hilt` — providing DataStore as a singleton
+- `key-value-store-strategy` — choosing the right storage for the use case

package/skills/Data Layer/Database Versioning Strategy/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: database-versioning-strategy
+description: >
+  Strategy for managing Room database version increments across releases.
+  Load this skill when planning schema changes, deciding when to increment
+  version, managing version history, or coordinating schema changes across
+  multiple developers/branches.
+---
+
+# Database Versioning Strategy
+
+## Overview
+Database versioning is the discipline of managing schema changes in a controlled, predictable way. Every schema change must be planned, versioned, documented, and tested before release. A broken migration path crashes the app on existing installs.
+
+---
+
+## Core Principles
+
+- **One version increment per release** — batch all schema changes for a release into one migration
+- **Never reuse a version number** — once a version is released, it's permanent
+- **Never modify a released migration** — write a new one instead
+- Export and commit the schema file — it's the source of truth for migration correctness
+- Plan schema changes before implementation — migrations are hard to undo
+
+---
+
+## Version Numbering
+
+```kotlin
+// ✅ Increment by 1 for each release with schema changes
+@Database(version = 5, ...)  // was 4 in previous release
+
+// ✅ Never skip version numbers
+// Bad: 1 → 3 (skipped 2) — users on v2 have no migration path to v3
+// Good: 1 → 2 → 3
+
+// ✅ During development — batch changes
+// Don't increment version for every local change during a sprint
+// Increment once when the feature/release is ready
+```
+
+---
+
+## Schema Export and Version Control
+
+```kotlin
+// ✅ Always export schema
+@Database(
+    entities = [...],
+    version = 5,
+    exportSchema = true  // generates schemas/com.example.AppDatabase/5.json
+)
+
+// build.gradle.kts
+ksp {
+    arg("room.schemaLocation", "$projectDir/schemas")
+}
+```
+
+```
+// ✅ Commit schema files to version control
+schemas/
+  com.example.AppDatabase/
+    1.json   ← version 1 schema
+    2.json   ← version 2 schema
+    3.json   ← version 3 schema
+    4.json   ← version 4 schema
+    5.json   ← version 5 schema (current)
+```
+
+---
+
+## Change Planning Checklist
+
+Before making any schema change:
+
+```
+☐ What tables/columns are affected?
+☐ Is existing data preserved? How?
+☐ Is the migration reversible? (Usually not — plan carefully)
+☐ Are there indices that need updating?
+☐ Are there related DAOs that need query updates?
+☐ Are there DTOs/mappers that need updating?
+☐ Is a data migration needed (not just schema migration)?
+☐ Is this the only schema change for this release?
+```
+
+---
+
+## Multi-Developer Coordination
+
+```
+// ✅ Strategy when multiple developers change schema simultaneously
+
+// Developer A: adds column to users table
+// Developer B: adds new orders table
+
+// On merge:
+// 1. Agree on a single version number for the combined change
+// 2. Write ONE migration that includes BOTH changes
+// 3. Never have two separate migrations with the same version increment
+
+// ✅ Use a migration registry file to coordinate
+// migrations/MIGRATION_LOG.md
+// Version 5 (Release 2.3.0):
+//   - Added phone_number to users (Developer A)
+//   - Added orders table (Developer B)
+```
+
+---
+
+## Data Migration vs Schema Migration
+
+```kotlin
+// Schema migration — changes structure
+val MIGRATION_4_5 = object : Migration(4, 5) {
+    override fun migrate(database: SupportSQLiteDatabase) {
+        database.execSQL("ALTER TABLE users ADD COLUMN tier TEXT NOT NULL DEFAULT 'free'")
+    }
+}
+
+// ✅ Data migration — backfill or transform data after schema change
+// Do NOT do complex data transformations in Migration.migrate()
+// Use a one-time WorkManager job instead
+
+class BackfillUserTierWorker(
+    context: Context,
+    params: WorkerParameters
+) : CoroutineWorker(context, params) {
+
+    override suspend fun doWork(): Result = withContext(Dispatchers.IO) {
+        try {
+            val users = userDao.getAllOnce()
+            users.forEach { user ->
+                val tier = computeTierFromHistory(user)
+                userDao.updateTier(user.id, tier)
+            }
+            Result.success()
+        } catch (e: Exception) {
+            Result.retry()
+        }
+    }
+}
+
+// Schedule after migration is complete
+fun scheduleBackfillIfNeeded(prefs: SharedPreferences) {
+    if (!prefs.getBoolean("backfill_tier_done", false)) {
+        WorkManager.getInstance(context).enqueueUniqueWork(
+            "backfill_user_tier",
+            ExistingWorkPolicy.KEEP,
+            OneTimeWorkRequestBuilder<BackfillUserTierWorker>().build()
+        )
+    }
+}
+```
+
+---
+
+## Emergency: Breaking Schema in Development
+
+```kotlin
+// ✅ During development only — if migration is too complex and data doesn't matter
+Room.databaseBuilder(context, AppDatabase::class.java, "app_database")
+    .fallbackToDestructiveMigration()  // ❌ NEVER in production release
+    .build()
+
+// ✅ Better approach in development — clear app data manually
+// adb shell pm clear com.example.app
+
+// ✅ Or use a different DB name per build type
+val dbName = if (BuildConfig.DEBUG) "app_database_debug" else "app_database"
+```
+
+---
+
+## Version History Documentation
+
+```markdown
+<!-- schemas/CHANGELOG.md — maintain alongside schema files -->
+
+## Version 5 (Release 2.3.0 — 2024-11-15)
+- Added `phone_number TEXT` to `users` table
+- Added `orders` table with foreign key to `users`
+- Added index on `orders.user_id`
+
+## Version 4 (Release 2.2.0 — 2024-09-01)
+- Added `status TEXT NOT NULL DEFAULT 'active'` to `users`
+
+## Version 3 (Release 2.0.0 — 2024-06-10)
+- Renamed column `name` → `full_name` in `users`
+
+## Version 2 (Release 1.5.0 — 2024-03-20)
+- Added `created_at INTEGER` to `users`
+
+## Version 1 (Initial release — 2024-01-10)
+- Initial schema: `users` table
+```
+
+---
+
+## Anti-Patterns
+
+- Incrementing version during development for every small change — creates unnecessary migrations
+- Not committing schema JSON files — migration tests fail, history is lost
+- Writing migration without updating the version in `@Database` — causes crash
+- Two migrations with overlapping version ranges — Room can't resolve path
+- Complex business logic inside `Migration.migrate()` — use WorkManager instead
+- Releasing without testing migration from the previous production version
+
+---
+
+## Related Skills
+- `migration` — writing individual migration objects
+- `room` — Room database configuration
+- `workmanager` — data migration jobs post-schema-change

package/skills/Data Layer/Encrypted Database/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: encrypted-database
+description: >
+  Encrypted SQLite database using SQLCipher and Room for Android.
+  Load this skill when storing sensitive user data that requires encryption
+  at rest, implementing encrypted Room database, or managing encryption keys.
+---
+
+# Encrypted Database
+
+## Overview
+
+SQLCipher provides transparent AES-256 encryption for SQLite databases. When integrated with Room, the entire database file is encrypted at rest. This is required for apps handling sensitive data — health records, financial data, private messages, or enterprise security requirements.
+
+---
+
+## Core Principles
+
+- Use SQLCipher when the database contains **sensitive user data**
+- Encryption key must be stored in **Android Keystore** — never hardcoded
+- Key derivation from user password uses PBKDF2 — never use raw password as key
+- Encrypted database has a **performance overhead** — benchmark before requiring it
+- Test encryption on real devices — emulators may behave differently
+
+---
+
+## Setup
+
+```toml
+[versions]
+sqlcipher = "4.5.4"
+security-crypto = "1.1.0-alpha06"
+
+[libraries]
+sqlcipher-android = { module = "net.zetetic:sqlcipher-android", version.ref = "sqlcipher" }
+sqlite-ktx        = { module = "androidx.sqlite:sqlite-ktx", version = "2.4.0" }
+security-crypto   = { module = "androidx.security:security-crypto", version.ref = "security-crypto" }
+```
+
+```kotlin
+dependencies {
+    implementation(libs.sqlcipher.android)
+    implementation(libs.sqlite.ktx)
+    implementation(libs.security.crypto)
+}
+```
+
+---
+
+## Key Management with Android Keystore
+
+```kotlin
+// ✅ Generate or retrieve encryption key from Keystore
+object DatabaseKeyManager {
+
+    private const val KEY_ALIAS = "db_encryption_key"
+    private const val PREFS_NAME = "db_key_prefs"
+    private const val PREFS_KEY = "encrypted_db_passphrase"
+
+    fun getOrCreateKey(context: Context): ByteArray {
+        val masterKey = MasterKey.Builder(context)
+            .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
+            .build()
+
+        val prefs = EncryptedSharedPreferences.create(
+            context,
+            PREFS_NAME,
+            masterKey,
+            EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
+            EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
+        )
+
+        val existing = prefs.getString(PREFS_KEY, null)
+        if (existing != null) {
+            return Base64.decode(existing, Base64.NO_WRAP)
+        }
+
+        // Generate new random key
+        val newKey = ByteArray(32).also { SecureRandom().nextBytes(it) }
+        prefs.edit()
+            .putString(PREFS_KEY, Base64.encodeToString(newKey, Base64.NO_WRAP))
+            .apply()
+        return newKey
+    }
+}
+```
+
+---
+
+## Room with SQLCipher
+
+```kotlin
+// ✅ Custom SupportSQLiteOpenHelper.Factory using SQLCipher
+@Module
+@InstallIn(SingletonComponent::class)
+object DatabaseModule {
+
+    @Provides
+    @Singleton
+    fun provideDatabase(@ApplicationContext context: Context): AppDatabase {
+        val passphrase = DatabaseKeyManager.getOrCreateKey(context)
+        val factory = SupportFactory(passphrase)
+
+        return Room.databaseBuilder(
+            context,
+            AppDatabase::class.java,
+            "encrypted_app_database"
+        )
+        .openHelperFactory(factory)
+        .addMigrations(MIGRATION_1_2)
+        .build()
+    }
+}
+```
+
+---
+
+## User-Password-Derived Key
+
+```kotlin
+// ✅ For apps where encryption key is derived from user's password
+object PasswordKeyDerivation {
+
+    fun deriveKey(password: CharArray, salt: ByteArray): ByteArray {
+        val spec = PBEKeySpec(
+            password,
+            salt,
+            100_000,  // iterations
+            256       // key length in bits
+        )
+        val factory = SecretKeyFactory.getInstance("PBKDF2WithHmacSHA256")
+        return factory.generateSecret(spec).encoded
+    }
+
+    fun generateSalt(): ByteArray {
+        return ByteArray(32).also { SecureRandom().nextBytes(it) }
+    }
+}
+
+// Store the salt (not the key) in EncryptedSharedPreferences
+// Re-derive the key each session from user's password
+```
+
+---
+
+## Verifying Encryption
+
+```kotlin
+// ✅ Verify database is encrypted (for debug/test)
+fun isDatabaseEncrypted(context: Context, dbName: String): Boolean {
+    val dbFile = context.getDatabasePath(dbName)
+    if (!dbFile.exists()) return false
+
+    return try {
+        val bytes = dbFile.readBytes().take(16).toByteArray()
+        val header = String(bytes)
+        !header.startsWith("SQLite format 3")  // encrypted files don't start with this
+    } catch (e: Exception) {
+        false
+    }
+}
+```
+
+---
+
+## Migration with Encrypted Database
+
+```kotlin
+// ✅ Migrations work the same way — SQLCipher handles the encryption transparently
+val MIGRATION_1_2 = object : Migration(1, 2) {
+    override fun migrate(database: SupportSQLiteDatabase) {
+        database.execSQL("ALTER TABLE users ADD COLUMN bio TEXT")
+    }
+}
+
+// No special handling needed — Room + SQLCipher = transparent
+```
+
+---
+
+## Performance Considerations
+
+```kotlin
+// ✅ SQLCipher overhead — benchmark before requiring encryption
+// Typical overhead: 5-15% slower reads, 5-20% slower writes
+// Acceptable for most use cases — unacceptable for high-frequency sensors/logs
+
+// ✅ If encryption overhead is a concern:
+// - Encrypt only the sensitive tables using separate database files
+// - Use per-row encryption for specific columns instead of full-DB encryption
+// - Profile with Macrobenchmark before deciding
+```
+
+---
+
+## Anti-Patterns
+
+- Hardcoding the encryption passphrase in code — visible in decompiled APK
+- Using the user's password directly as the DB key — weak, changes break DB
+- Not storing the salt — can't re-derive key from password
+- Not using Android Keystore to protect the DB key — key accessible on rooted devices
+- Encrypting non-sensitive data — unnecessary performance overhead
+- Sharing encrypted DB across users on the same device — key management nightmare
+
+---
+
+## Related Skills
+
+- `room` — Room database setup
+- `keystore` — Android Keystore for key storage
+- `encrypted-storage` — EncryptedSharedPreferences for key storage
+- `security` — general Android security patterns