android-sdd 1.0.0

package/skills/Data Layer/File Storage/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: file-storage
+description: >
+  File storage patterns for Android — saving, reading, and managing files
+  across internal storage, external storage, and cache.
+  Load this skill when persisting files (images, PDFs, exports, downloads),
+  choosing storage location, or managing file lifecycle.
+---
+
+# File Storage
+
+## Overview
+
+File storage is used when data doesn't fit neatly into a database or key-value store — images, documents, exports, downloaded content, and binary files. Android provides several storage locations with different visibility, permission, and persistence characteristics.
+
+---
+
+## Core Principles
+
+- Choose the **right storage location** for the file's purpose and visibility
+- Always perform file I/O on **Dispatchers.IO** — never main thread
+- Use **FileProvider** to share files with other apps — never expose raw paths
+- Cache files are **not guaranteed** — don't use for critical data
+- Clean up files when they're no longer needed — storage is finite
+
+---
+
+## Storage Location Decision
+
+```
+Is the file private to the app?
+    YES → Does the system need to delete it automatically?
+        YES → cacheDir (temporary)
+        NO  → filesDir (permanent internal)
+    NO  → Is it app-specific but user-visible?
+        YES → getExternalFilesDir() (no permission needed)
+        NO  → MediaStore (shared media) or Downloads
+```
+
+---
+
+## Writing Files
+
+```kotlin
+// ✅ Internal storage — private, permanent
+suspend fun saveReport(context: Context, fileName: String, content: ByteArray) {
+    withContext(Dispatchers.IO) {
+        val file = File(context.filesDir, fileName)
+        file.writeBytes(content)
+    }
+}
+
+// ✅ Subdirectory in internal storage
+suspend fun saveInSubdir(context: Context, subdir: String, fileName: String, content: String) {
+    withContext(Dispatchers.IO) {
+        val dir = File(context.filesDir, subdir).also { it.mkdirs() }
+        File(dir, fileName).writeText(content)
+    }
+}
+
+// ✅ Cache — temporary, system may delete
+suspend fun cacheDownload(context: Context, fileName: String, content: ByteArray) {
+    withContext(Dispatchers.IO) {
+        File(context.cacheDir, fileName).writeBytes(content)
+    }
+}
+
+// ✅ External app-specific — user-visible, no permission needed
+suspend fun saveToExternalDocs(context: Context, fileName: String, content: ByteArray) {
+    withContext(Dispatchers.IO) {
+        val dir = context.getExternalFilesDir(Environment.DIRECTORY_DOCUMENTS)
+            ?: return@withContext
+        File(dir, fileName).writeBytes(content)
+    }
+}
+```
+
+---
+
+## Reading Files
+
+```kotlin
+// ✅ Read with existence check
+suspend fun readFile(context: Context, fileName: String): ByteArray? {
+    return withContext(Dispatchers.IO) {
+        val file = File(context.filesDir, fileName)
+        if (file.exists()) file.readBytes() else null
+    }
+}
+
+// ✅ Read as stream (large files)
+suspend fun readLargeFile(context: Context, fileName: String): Flow<ByteArray> = flow {
+    withContext(Dispatchers.IO) {
+        val file = File(context.filesDir, fileName)
+        file.inputStream().buffered().use { stream ->
+            val buffer = ByteArray(8192)
+            var bytesRead: Int
+            while (stream.read(buffer).also { bytesRead = it } != -1) {
+                emit(buffer.copyOf(bytesRead))
+            }
+        }
+    }
+}
+```
+
+---
+
+## File Management
+
+```kotlin
+// ✅ Delete file
+suspend fun deleteFile(context: Context, fileName: String): Boolean {
+    return withContext(Dispatchers.IO) {
+        File(context.filesDir, fileName).delete()
+    }
+}
+
+// ✅ List files in directory
+suspend fun listFiles(context: Context, subdir: String): List<String> {
+    return withContext(Dispatchers.IO) {
+        File(context.filesDir, subdir)
+            .listFiles()
+            ?.map { it.name }
+            ?: emptyList()
+    }
+}
+
+// ✅ Get file size
+fun getFileSize(context: Context, fileName: String): Long {
+    return File(context.filesDir, fileName).length()
+}
+
+// ✅ Check if file exists
+fun fileExists(context: Context, fileName: String): Boolean {
+    return File(context.filesDir, fileName).exists()
+}
+```
+
+---
+
+## Saving Bitmaps
+
+```kotlin
+// ✅ Save bitmap to internal storage
+suspend fun saveBitmap(context: Context, bitmap: Bitmap, fileName: String) {
+    withContext(Dispatchers.IO) {
+        val file = File(context.filesDir, fileName)
+        file.outputStream().use { out ->
+            bitmap.compress(Bitmap.CompressFormat.JPEG, 90, out)
+        }
+    }
+}
+
+// ✅ Load bitmap
+suspend fun loadBitmap(context: Context, fileName: String): Bitmap? {
+    return withContext(Dispatchers.IO) {
+        val file = File(context.filesDir, fileName)
+        if (file.exists()) BitmapFactory.decodeFile(file.absolutePath) else null
+    }
+}
+```
+
+---
+
+## Sharing Files via FileProvider
+
+```kotlin
+// ✅ Get shareable URI — never expose raw file:// URI
+fun getShareableUri(context: Context, file: File): Uri {
+    return FileProvider.getUriForFile(
+        context,
+        "${context.packageName}.fileprovider",
+        file
+    )
+}
+
+// ✅ Share file
+fun shareFile(context: Context, file: File, mimeType: String) {
+    val uri = getShareableUri(context, file)
+    val intent = Intent(Intent.ACTION_SEND).apply {
+        type = mimeType
+        putExtra(Intent.EXTRA_STREAM, uri)
+        addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
+    }
+    context.startActivity(Intent.createChooser(intent, null))
+}
+```
+
+---
+
+## Cache Management
+
+```kotlin
+// ✅ Calculate cache size
+suspend fun getCacheSizeBytes(context: Context): Long {
+    return withContext(Dispatchers.IO) {
+        context.cacheDir.walkTopDown().sumOf { it.length() }
+    }
+}
+
+// ✅ Clear cache
+suspend fun clearCache(context: Context) {
+    withContext(Dispatchers.IO) {
+        context.cacheDir.deleteRecursively()
+    }
+}
+
+// ✅ Trim cache to max size (LRU — delete oldest first)
+suspend fun trimCache(context: Context, maxBytes: Long) {
+    withContext(Dispatchers.IO) {
+        val files = context.cacheDir
+            .walkTopDown()
+            .filter { it.isFile }
+            .sortedBy { it.lastModified() }
+            .toMutableList()
+
+        var totalSize = files.sumOf { it.length() }
+        for (file in files) {
+            if (totalSize <= maxBytes) break
+            totalSize -= file.length()
+            file.delete()
+        }
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- File I/O on the main thread — causes ANR
+- Storing files in external storage without checking availability
+- Using `file://` URI directly with other apps — crashes on API 24+
+- Not cleaning up temp files — accumulates storage over time
+- Storing sensitive data in external storage — accessible to other apps
+- Not checking `file.exists()` before reading — `FileNotFoundException`
+- Recursive directory listing on large directories on main thread
+
+---
+
+## Related Skills
+
+- `filesystem` — Android filesystem fundamentals
+- `binary-storage` — storing binary/media data
+- `encrypted-database` — encrypting sensitive files
+- `cache-strategy` — cache invalidation and management
+- `workmanager` — background file operations

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

@@ -0,0 +1,184 @@
+---
+name: indexing
+description: >
+  SQLite/Room database indexing strategy for Android.
+  Load this skill when defining indices on entities, diagnosing slow queries,
+  or deciding which columns need indexing for query performance.
+---
+
+# Indexing
+
+## Overview
+
+A database index is a data structure that speeds up query lookups at the cost of extra storage and slower writes. Without proper indices, queries perform a full table scan — acceptable for small tables, catastrophic for large ones. In Room, indices are declared on `@Entity`.
+
+---
+
+## Core Principles
+
+- Index columns used in **WHERE**, **JOIN ON**, and **ORDER BY** clauses
+- Index foreign key columns — Room/SQLite does not do this automatically
+- **Don't over-index** — every index slows down INSERT/UPDATE/DELETE
+- Unique indices enforce data integrity at the DB level
+- Composite indices cover multi-column WHERE clauses
+
+---
+
+## Declaring Indices in Room
+
+```kotlin
+// ✅ Single column index
+@Entity(
+    tableName = "users",
+    indices = [
+        Index(value = ["email"], unique = true),  // unique constraint
+        Index(value = ["status"]),                 // for filtering
+        Index(value = ["created_at"])              // for sorting
+    ]
+)
+data class UserEntity(
+    @PrimaryKey val id: String,
+    val email: String,
+    val status: String,
+    @ColumnInfo(name = "created_at") val createdAt: Long
+)
+
+// ✅ Composite index — covers multi-column queries
+@Entity(
+    tableName = "orders",
+    indices = [
+        Index(value = ["user_id", "status"]),  // WHERE user_id = ? AND status = ?
+        Index(value = ["user_id"])              // WHERE user_id = ? alone also uses this
+    ]
+)
+data class OrderEntity(
+    @PrimaryKey val id: String,
+    @ColumnInfo(name = "user_id") val userId: String,
+    val status: String,
+    val total: Int
+)
+```
+
+---
+
+## When to Add an Index
+
+```kotlin
+// ✅ Index needed — WHERE on non-primary-key column
+@Query("SELECT * FROM users WHERE status = :status")
+// → index on status
+
+// ✅ Index needed — ORDER BY on non-primary-key column
+@Query("SELECT * FROM users ORDER BY created_at DESC")
+// → index on created_at
+
+// ✅ Index needed — JOIN condition
+@Query("SELECT * FROM orders o JOIN users u ON o.user_id = u.id")
+// → index on orders.user_id (foreign key)
+
+// ✅ Index needed — LIKE prefix search
+@Query("SELECT * FROM users WHERE full_name LIKE :prefix || '%'")
+// → index on full_name (helps prefix search, not suffix)
+
+// ❌ Index NOT needed — primary key is already indexed
+@Query("SELECT * FROM users WHERE id = :id")
+// → no extra index needed
+```
+
+---
+
+## Index Decision Matrix
+
+| Query Pattern                  | Index Type                     |
+| ------------------------------ | ------------------------------ |
+| `WHERE col = ?`                | Single index on `col`          |
+| `WHERE col1 = ? AND col2 = ?`  | Composite index `(col1, col2)` |
+| `ORDER BY col`                 | Single index on `col`          |
+| `WHERE col1 = ? ORDER BY col2` | Composite index `(col1, col2)` |
+| `LIKE 'prefix%'`               | Single index on `col`          |
+| Foreign key column             | Single index (always)          |
+| Unique constraint              | Unique index                   |
+
+---
+
+## Foreign Key Indices
+
+```kotlin
+// ✅ Always index foreign key columns — SQLite doesn't auto-index them
+@Entity(
+    tableName = "orders",
+    foreignKeys = [
+        ForeignKey(
+            entity = UserEntity::class,
+            parentColumns = ["id"],
+            childColumns = ["user_id"],
+            onDelete = ForeignKey.CASCADE
+        )
+    ],
+    indices = [
+        Index(value = ["user_id"])  // ✅ required — without this, cascades are slow
+    ]
+)
+data class OrderEntity(
+    @PrimaryKey val id: String,
+    @ColumnInfo(name = "user_id") val userId: String
+)
+```
+
+---
+
+## Diagnosing Missing Indices
+
+```kotlin
+// ✅ Enable Room query logging in debug
+Room.databaseBuilder(context, AppDatabase::class.java, "app_database")
+    .setQueryCallback(
+        queryCallback = { sqlQuery, bindArgs ->
+            Log.d("RoomQuery", "Query: $sqlQuery Args: $bindArgs")
+        },
+        executor = Executors.newSingleThreadExecutor()
+    )
+    .build()
+
+// ✅ Use EXPLAIN QUERY PLAN to check index usage
+// Run in a test or via ADB:
+// EXPLAIN QUERY PLAN SELECT * FROM users WHERE status = 'active'
+// Look for "SCAN TABLE" (no index) vs "SEARCH TABLE USING INDEX" (indexed)
+```
+
+---
+
+## Composite Index Column Order
+
+```kotlin
+// ✅ Put the most selective / most frequently filtered column FIRST
+Index(value = ["user_id", "status"])
+// Best for: WHERE user_id = ? AND status = ?
+// Also good for: WHERE user_id = ?
+// NOT useful for: WHERE status = ? alone
+
+// ✅ For range queries, range column goes LAST
+Index(value = ["user_id", "created_at"])
+// Good for: WHERE user_id = ? AND created_at > ?
+// Not for: WHERE created_at > ? alone
+```
+
+---
+
+## Anti-Patterns
+
+- No index on foreign key columns — DELETE/CASCADE operations become full table scans
+- Index on every column — slows writes, wastes storage, rarely helps queries
+- Composite index with wrong column order — first column must be used in WHERE
+- Index on low-cardinality columns alone (e.g., boolean) — rarely helps (only 2 values)
+- Missing index on ORDER BY column in large tables — full sort every query
+- Unique index as a substitute for proper validation — validate in app layer too
+
+---
+
+## Related Skills
+
+- `room` — Room entity and database setup
+- `dao` — queries that benefit from indices
+- `sqlite` — raw SQLite index management
+- `database-versioning-strategy` — adding indices via migration

package/skills/Data Layer/Key-Value Store Strategy/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: key-value-store-strategy
+description: >
+  Choosing the right key-value storage for Android — DataStore, SharedPreferences,
+  EncryptedSharedPreferences, or in-memory. Load this skill when deciding where
+  to store simple values, flags, tokens, or settings.
+---
+
+# Key-Value Store Strategy
+
+## Overview
+
+Android provides several key-value storage options. Choosing the wrong one leads to security issues, data loss, or unnecessary complexity. This skill defines which store to use for each type of data.
+
+---
+
+## Decision Matrix
+
+| Data Type                      | Storage                         | Reason                             |
+| ------------------------------ | ------------------------------- | ---------------------------------- |
+| User settings, preferences     | DataStore (Preferences)         | Async, type-safe, coroutine-native |
+| Structured settings object     | DataStore (Proto)               | Schema-safe, evolves cleanly       |
+| Auth token, sensitive value    | EncryptedSharedPreferences      | Encrypted at rest                  |
+| Session flags (in-memory only) | In-memory (ViewModel/singleton) | No persistence needed              |
+| Feature flags from server      | DataStore + remote config       | Persisted, refreshable             |
+| Legacy migration source        | SharedPreferences → DataStore   | Migrate away from SP               |
+
+---
+
+## DataStore (Preferences) — Default Choice
+
+```kotlin
+// ✅ Use for: app settings, UI preferences, onboarding state, feature flags
+val IS_ONBOARDING_DONE = booleanPreferencesKey("onboarding_done")
+val SELECTED_LANGUAGE  = stringPreferencesKey("language")
+val LAST_SYNC_TIME     = longPreferencesKey("last_sync")
+
+// Read
+val isDone: Flow<Boolean> = dataStore.data.map { it[IS_ONBOARDING_DONE] ?: false }
+
+// Write
+suspend fun markOnboardingDone() {
+    dataStore.edit { it[IS_ONBOARDING_DONE] = true }
+}
+```
+
+---
+
+## EncryptedSharedPreferences — Sensitive Data
+
+```kotlin
+// ✅ Use for: auth tokens, refresh tokens, PII, secrets
+// Never store tokens in plain DataStore or SharedPreferences
+
+dependencies {
+    implementation(libs.security.crypto)
+}
+
+fun createEncryptedPrefs(context: Context): SharedPreferences {
+    val masterKey = MasterKey.Builder(context)
+        .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
+        .build()
+
+    return EncryptedSharedPreferences.create(
+        context,
+        "secure_prefs",
+        masterKey,
+        EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
+        EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
+    )
+}
+
+// ✅ Provide via Hilt
+@Provides
+@Singleton
+fun provideEncryptedPrefs(@ApplicationContext context: Context): SharedPreferences =
+    createEncryptedPrefs(context)
+
+// ✅ Repository wrapping encrypted prefs
+class TokenRepository @Inject constructor(
+    private val encryptedPrefs: SharedPreferences
+) {
+    companion object {
+        private const val KEY_ACCESS_TOKEN = "access_token"
+        private const val KEY_REFRESH_TOKEN = "refresh_token"
+    }
+
+    fun getAccessToken(): String? = encryptedPrefs.getString(KEY_ACCESS_TOKEN, null)
+    fun getRefreshToken(): String? = encryptedPrefs.getString(KEY_REFRESH_TOKEN, null)
+
+    fun saveTokens(accessToken: String, refreshToken: String) {
+        encryptedPrefs.edit()
+            .putString(KEY_ACCESS_TOKEN, accessToken)
+            .putString(KEY_REFRESH_TOKEN, refreshToken)
+            .apply()
+    }
+
+    fun clearTokens() {
+        encryptedPrefs.edit()
+            .remove(KEY_ACCESS_TOKEN)
+            .remove(KEY_REFRESH_TOKEN)
+            .apply()
+    }
+}
+```
+
+---
+
+## In-Memory Store — Session-Only Data
+
+```kotlin
+// ✅ Use for: data that only lives for the current session
+// Examples: current user object after login, selected items, temp state
+
+// ✅ In ViewModel — scoped to screen
+@HiltViewModel
+class CheckoutViewModel @Inject constructor() : ViewModel() {
+    private val _selectedItems = MutableStateFlow<List<Item>>(emptyList())
+    val selectedItems = _selectedItems.asStateFlow()
+}
+
+// ✅ In singleton — scoped to app session
+@Singleton
+class SessionStore @Inject constructor() {
+    private var _currentUser: User? = null
+    val currentUser: User? get() = _currentUser
+
+    fun setUser(user: User) { _currentUser = user }
+    fun clearUser() { _currentUser = null }
+}
+```
+
+---
+
+## SharedPreferences — Legacy Only
+
+```kotlin
+// ❌ Don't use in new code — use DataStore instead
+// ✅ Only acceptable when:
+//   - Migrating existing code incrementally
+//   - A third-party library requires SharedPreferences
+
+// ✅ If you must use it, apply() not commit()
+prefs.edit().putString("key", "value").apply()  // async
+// NOT:
+prefs.edit().putString("key", "value").commit()  // blocks main thread
+```
+
+---
+
+## Migration: SharedPreferences → DataStore
+
+```kotlin
+// ✅ Migrate automatically on first DataStore access
+val dataStore = context.createDataStore(
+    name = "app_prefs",
+    migrations = listOf(
+        SharedPreferencesMigration(
+            context = context,
+            sharedPreferencesName = "legacy_prefs",
+            keysToMigrate = setOf("language", "is_dark_mode")  // migrate only needed keys
+        )
+    )
+)
+```
+
+---
+
+## Anti-Patterns
+
+- Storing auth tokens in plain DataStore or SharedPreferences — readable without encryption
+- Using SharedPreferences in new code — use DataStore instead
+- Storing large objects as JSON strings in key-value store — use Room
+- Multiple instances of DataStore for the same file — data corruption
+- Using `commit()` on SharedPreferences — blocks main thread
+- Storing user PII (name, email) in plain storage — security and compliance risk
+
+---
+
+## Related Skills
+
+- `datastore` — Preferences DataStore implementation
+- `proto-datastore` — typed object storage
+- `encrypted-storage` — Android Keystore and EncryptedSharedPreferences
+- `cache-strategy` — caching with key-value stores