android-sdd 1.0.0

package/skills/Performance/Battery Optimization/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: battery-optimization
+description: >
+  Battery usage optimization in Android apps.
+  Load this skill when reducing background battery drain, handling Doze
+  mode, batching network requests, optimizing location usage,
+  or profiling energy usage with Android Studio Energy Profiler.
+---
+
+# Battery Optimization
+
+## Overview
+Battery drain is one of the top reasons users uninstall apps. The main causes are: excessive wake locks, frequent network requests, GPS usage, and background processing that ignores Doze/App Standby. The goal is to do necessary work efficiently and batch or defer work that doesn't need to happen immediately.
+
+---
+
+## Core Principles
+
+- **Batch** network requests — fewer wakeups is better than many small ones
+- **Defer** non-urgent work to when the device is charging or on Wi-Fi (WorkManager constraints)
+- Release **WakeLocks** as quickly as possible — always in a `finally` block
+- Use **passive location** or lower accuracy when precise GPS is not needed
+- Never poll — use push (FCM) or `ContentObserver` instead
+
+---
+
+## WorkManager Constraints
+
+```kotlin
+// ✅ Defer heavy sync to favorable conditions
+val syncRequest = PeriodicWorkRequestBuilder<SyncWorker>(1, TimeUnit.HOURS)
+    .setConstraints(
+        Constraints.Builder()
+            .setRequiredNetworkType(NetworkType.UNMETERED)  // Wi-Fi only
+            .setRequiresCharging(true)                       // only when charging
+            .setRequiresBatteryNotLow(true)                  // not low battery
+            .build()
+    )
+    .build()
+```
+
+---
+
+## Batching Network Requests
+
+```kotlin
+// ❌ Individual requests — each wakes radio
+suspend fun syncAll() {
+    syncUsers()     // wakes radio
+    delay(100)
+    syncOrders()    // wakes radio again
+    delay(100)
+    syncProducts()  // wakes radio again
+}
+
+// ✅ Single batched request — one radio wakeup
+suspend fun syncAll() {
+    val batch = syncRepository.syncAll()  // one API call returning all data
+    processBatchResult(batch)
+}
+```
+
+---
+
+## Doze Mode Awareness
+
+```kotlin
+// Doze mode restricts:
+// - Network access
+// - Wake locks
+// - AlarmManager (except setAndAllowWhileIdle)
+// - JobScheduler / WorkManager (deferred)
+//
+// Exempt from Doze:
+// - FCM high-priority messages
+// - ForegroundService
+// - WorkManager with setExpedited
+
+// ✅ Expedited work for urgent tasks during Doze
+val urgentRequest = OneTimeWorkRequestBuilder<UrgentSyncWorker>()
+    .setExpedited(OutOfQuotaPolicy.RUN_AS_NON_EXPEDITED_WORK_REQUEST)
+    .build()
+```
+
+---
+
+## WakeLock — Use Sparingly
+
+```kotlin
+// ✅ Acquire and release WakeLock safely
+class WakeLockManager @Inject constructor(
+    @ApplicationContext context: Context
+) {
+    private val powerManager = context.getSystemService(PowerManager::class.java)
+    private val wakeLock = powerManager.newWakeLock(
+        PowerManager.PARTIAL_WAKE_LOCK,
+        "MyApp::SyncWakeLock"
+    )
+
+    fun withWakeLock(timeoutMs: Long = 10_000, block: () -> Unit) {
+        wakeLock.acquire(timeoutMs)  // always set timeout
+        try {
+            block()
+        } finally {
+            if (wakeLock.isHeld) wakeLock.release()  // ✅ always release
+        }
+    }
+}
+```
+
+---
+
+## Location Battery Optimization
+
+```kotlin
+// ✅ Use lowest accuracy tier that meets the need
+val locationRequest = LocationRequest.Builder(
+    Priority.PRIORITY_BALANCED_POWER_ACCURACY,  // cell tower + Wi-Fi — less battery than GPS
+    intervalMillis = 30_000                      // 30 second interval
+)
+    .setMinUpdateDistanceMeters(50f)             // only update if moved 50m
+    .build()
+
+// ✅ Use PRIORITY_PASSIVE for background — piggyback on other apps' location fixes
+val passiveRequest = LocationRequest.Builder(
+    Priority.PRIORITY_PASSIVE,
+    intervalMillis = 60_000
+).build()
+
+// ✅ Stop updates when not needed
+override fun onStop() {
+    locationClient.removeLocationUpdates(locationCallback)
+    super.onStop()
+}
+```
+
+---
+
+## Polling vs Push
+
+```kotlin
+// ❌ Polling — wakes device repeatedly
+fun startPolling() {
+    viewModelScope.launch {
+        while (true) {
+            fetchNewMessages()    // unnecessary if no new messages
+            delay(30_000)
+        }
+    }
+}
+
+// ✅ FCM push — device wakes only when there's actual data
+// Server sends FCM notification → app wakes → fetches only when needed
+class MessagingService : FirebaseMessagingService() {
+    override fun onMessageReceived(message: RemoteMessage) {
+        // Triggered only when server sends a message
+        syncMessages()
+    }
+}
+```
+
+---
+
+## Battery Profiling
+
+```
+Android Studio → Profiler → Energy:
+  - Shows CPU, network, and location wakeups over time
+  - Identify: which operations cause the most wakeups
+  - Compare before/after optimization
+
+adb shell dumpsys batterystats --reset  // reset stats
+adb shell dumpsys batterystats          // dump current stats
+```
+
+---
+
+## Anti-Patterns
+
+- Holding WakeLock without a timeout — device never sleeps
+- Polling for updates instead of using FCM or WebSocket
+- Using `PRIORITY_HIGH_ACCURACY` location for all use cases — drains GPS
+- Running WorkManager without constraints — executes even on low battery/metered network
+- Ignoring Doze mode — work silently skipped without the app knowing
+
+---
+
+## Related Skills
+- `workmanager` — scheduling work with battery-aware constraints
+- `background-processing` — choosing the right background mechanism
+- `firebase-messaging` — push notifications to replace polling
+- `foreground-service` — when continuous background work is truly needed

package/skills/Performance/Benchmark/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: benchmark
+description: >
+  Microbenchmarking with Jetpack Benchmark in Android.
+  Load this skill when measuring method-level performance, comparing
+  algorithm implementations, benchmarking serialization or data processing,
+  or setting up the benchmark module.
+---
+
+# Benchmark
+
+## Overview
+Jetpack Benchmark (microbenchmark) measures the performance of individual code units — methods, algorithms, serialization — with statistical accuracy. It handles warm-up, clock stability, and GC pauses automatically. Use it to compare implementations and catch regressions.
+
+---
+
+## Core Principles
+
+- Benchmark measures **one thing at a time** — isolate the code under test
+- Run on a **physical device** — emulator results are unreliable
+- Use `BenchmarkRule` — it handles warm-up and measurement automatically
+- Benchmark in **release mode** — debug builds are significantly slower
+- Compare relative results — absolute numbers vary by device
+
+---
+
+## Setup
+
+```toml
+# libs.versions.toml
+[libraries]
+androidx-benchmark-junit4 = { module = "androidx.benchmark:benchmark-junit4", version = "1.2.4" }
+```
+
+```kotlin
+// benchmark/build.gradle.kts (separate module)
+plugins {
+    alias(libs.plugins.android.library)
+}
+
+android {
+    defaultConfig {
+        testInstrumentationRunner = "androidx.benchmark.junit4.AndroidBenchmarkRunner"
+        testInstrumentationRunnerArguments["androidx.benchmark.suppressErrors"] = "EMULATOR,LOW-BATTERY"
+    }
+
+    buildTypes {
+        release {
+            isMinifyEnabled = true
+            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"))
+        }
+        create("benchmark") {
+            initWith(buildTypes.getByName("release"))
+            signingConfig = signingConfigs.getByName("debug")
+            matchingFallbacks += listOf("release")
+        }
+    }
+}
+
+dependencies {
+    androidTestImplementation(libs.androidx.benchmark.junit4)
+}
+```
+
+---
+
+## Writing a Benchmark
+
+```kotlin
+// ✅ Basic benchmark
+@RunWith(AndroidJUnit4::class)
+class SerializationBenchmark {
+
+    @get:Rule
+    val benchmarkRule = BenchmarkRule()
+
+    private val json = Json { ignoreUnknownKeys = true }
+    private val sampleJson = """{"id":"1","name":"John","email":"john@example.com"}"""
+
+    @Test
+    fun deserializeUser() = benchmarkRule.measureRepeated {
+        // ✅ Only the code under test inside measureRepeated
+        json.decodeFromString<UserDto>(sampleJson)
+    }
+
+    @Test
+    fun serializeUser() = benchmarkRule.measureRepeated {
+        val user = UserDto("1", "John", "john@example.com")
+        json.encodeToString(user)
+    }
+}
+```
+
+---
+
+## Comparing Implementations
+
+```kotlin
+// ✅ Compare two sorting algorithms
+@RunWith(AndroidJUnit4::class)
+class SortingBenchmark {
+
+    @get:Rule
+    val benchmarkRule = BenchmarkRule()
+
+    private val data = (1..10_000).shuffled()
+
+    @Test
+    fun sortWithSortedBy() = benchmarkRule.measureRepeated {
+        data.sortedBy { it }
+    }
+
+    @Test
+    fun sortWithSort() = benchmarkRule.measureRepeated {
+        val copy = data.toMutableList()
+        copy.sort()
+        copy
+    }
+}
+```
+
+---
+
+## Setup and Teardown
+
+```kotlin
+// ✅ runWithTimingDisabled for setup outside measurement
+@Test
+fun processLargeList() = benchmarkRule.measureRepeated {
+    val data = runWithTimingDisabled {
+        // Setup not counted in benchmark
+        generateLargeDataSet(1000)
+    }
+    // Only this is measured
+    processData(data)
+}
+```
+
+---
+
+## Running Benchmarks
+
+```bash
+# Run all benchmarks
+./gradlew :benchmark:connectedAndroidTest \
+  -Pandroid.testInstrumentationRunnerArguments.class=com.example.SerializationBenchmark
+
+# Output in logcat:
+# SerializationBenchmark.deserializeUser: min=45us, median=47us, max=62us
+```
+
+---
+
+## Allocation Benchmark
+
+```kotlin
+// ✅ Measure allocations alongside time
+@Test
+fun checkAllocations() = benchmarkRule.measureRepeated {
+    // BenchmarkRule automatically tracks allocations
+    // Check "allocationCount" in results
+    val result = mapper.toDomain(userDto)
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Running benchmarks on emulator — results are not representative
+- Putting setup code inside `measureRepeated` — inflates measurement
+- Benchmarking in debug build — JIT and debug overhead skew results
+- Benchmarking with the screen on and other apps running — interference from system
+- Comparing results across different devices — only compare on same device
+
+---
+
+## Related Skills
+- `macrobenchmark` — end-to-end performance measurement
+- `baseline-profile` — using benchmark results to generate profiles
+- `allocation-optimization` — reducing allocations flagged by benchmark
+- `rendering-performance` — frame-level performance measurement

package/skills/Performance/Bitmap Optimization/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: bitmap-optimization
+description: >
+  Bitmap loading, scaling, and memory optimization in Android.
+  Load this skill when loading images efficiently, scaling bitmaps
+  to required dimensions, using inSampleSize, managing Bitmap recycling,
+  or reducing native heap usage from image decoding.
+---
+
+# Bitmap Optimization
+
+## Overview
+Bitmaps are the largest consumers of native heap on Android. A single 12MP photo decoded as ARGB_8888 uses ~48MB. Proper bitmap optimization involves decoding at the required size, choosing the right pixel format, and using a caching library (Coil, Glide) rather than manual management.
+
+---
+
+## Core Principles
+
+- Never decode full-resolution bitmaps for thumbnail display — use `inSampleSize`
+- Use **Coil** (or Glide) for image loading — they handle caching, sampling, and lifecycle
+- Prefer `RGB_565` for images that don't need transparency — half the memory of `ARGB_8888`
+- Recycle bitmaps manually only if not using a caching library
+- Load bitmaps on a background thread — never on the main thread
+
+---
+
+## Coil — Recommended Image Loader
+
+```toml
+# libs.versions.toml
+[libraries]
+coil = { module = "io.coil-kt:coil-compose", version = "2.7.0" }
+```
+
+```kotlin
+// ✅ Load image in Compose with Coil
+@Composable
+fun UserAvatar(imageUrl: String?, modifier: Modifier = Modifier) {
+    AsyncImage(
+        model = ImageRequest.Builder(LocalContext.current)
+            .data(imageUrl)
+            .crossfade(true)
+            .size(64, 64)           // ✅ decode at display size — not full res
+            .build(),
+        contentDescription = null,
+        contentScale = ContentScale.Crop,
+        placeholder = painterResource(R.drawable.avatar_placeholder),
+        error = painterResource(R.drawable.avatar_error),
+        modifier = modifier
+            .size(64.dp)
+            .clip(CircleShape)
+    )
+}
+```
+
+---
+
+## Manual Bitmap Sampling (inSampleSize)
+
+```kotlin
+// ✅ Decode at required size without loading full bitmap
+fun decodeSampledBitmap(filePath: String, reqWidth: Int, reqHeight: Int): Bitmap {
+    // First pass: get dimensions only
+    val options = BitmapFactory.Options().apply {
+        inJustDecodeBounds = true
+    }
+    BitmapFactory.decodeFile(filePath, options)
+
+    // Calculate sample size
+    options.inSampleSize = calculateInSampleSize(options, reqWidth, reqHeight)
+    options.inJustDecodeBounds = false
+
+    return BitmapFactory.decodeFile(filePath, options)
+}
+
+fun calculateInSampleSize(options: BitmapFactory.Options, reqWidth: Int, reqHeight: Int): Int {
+    val height = options.outHeight
+    val width = options.outWidth
+    var inSampleSize = 1
+
+    if (height > reqHeight || width > reqWidth) {
+        val halfHeight = height / 2
+        val halfWidth = width / 2
+        while (halfHeight / inSampleSize >= reqHeight && halfWidth / inSampleSize >= reqWidth) {
+            inSampleSize *= 2
+        }
+    }
+    return inSampleSize
+}
+```
+
+---
+
+## Pixel Format Selection
+
+```kotlin
+// ✅ RGB_565 — half memory, no transparency
+val options = BitmapFactory.Options().apply {
+    inPreferredConfig = Bitmap.Config.RGB_565  // 2 bytes/pixel vs 4 bytes for ARGB_8888
+}
+val bitmap = BitmapFactory.decodeResource(resources, R.drawable.background, options)
+
+// ✅ ARGB_8888 — full quality with alpha
+val options = BitmapFactory.Options().apply {
+    inPreferredConfig = Bitmap.Config.ARGB_8888
+}
+
+// Memory comparison for 1920x1080 image:
+// ARGB_8888 = 1920 * 1080 * 4 = ~8MB
+// RGB_565   = 1920 * 1080 * 2 = ~4MB
+```
+
+---
+
+## Bitmap Reuse (inBitmap)
+
+```kotlin
+// ✅ Reuse existing bitmap memory — avoids new allocation
+val reusableBitmap = Bitmap.createBitmap(width, height, Bitmap.Config.ARGB_8888)
+
+val options = BitmapFactory.Options().apply {
+    inMutable = true
+    inBitmap = reusableBitmap  // reuse existing allocation
+}
+val newBitmap = BitmapFactory.decodeFile(filePath, options)
+// newBitmap === reusableBitmap — same memory, new content
+```
+
+---
+
+## Compress Before Upload
+
+```kotlin
+// ✅ Compress bitmap before sending to server
+fun Bitmap.toCompressedByteArray(
+    format: Bitmap.CompressFormat = Bitmap.CompressFormat.JPEG,
+    quality: Int = 85
+): ByteArray {
+    return ByteArrayOutputStream().use { out ->
+        compress(format, quality, out)
+        out.toByteArray()
+    }
+}
+
+// ✅ Scale down before compressing
+fun Uri.toScaledBitmap(context: Context, maxDimension: Int = 1024): Bitmap {
+    val original = BitmapFactory.decodeStream(context.contentResolver.openInputStream(this))
+    val scale = maxDimension.toFloat() / maxOf(original.width, original.height)
+    return if (scale < 1f) {
+        Bitmap.createScaledBitmap(
+            original,
+            (original.width * scale).toInt(),
+            (original.height * scale).toInt(),
+            true
+        ).also { original.recycle() }
+    } else {
+        original
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Loading full-resolution images for small thumbnails — massive memory waste
+- Decoding bitmaps on the main thread — ANR risk
+- Not recycling bitmaps when done (if managing manually) — native heap leak
+- Using `ARGB_8888` for all images including opaque backgrounds — unnecessary memory
+- Storing decoded bitmaps in static fields — never GC'd
+
+---
+
+## Related Skills
+- `heap-management` — overall heap and memory pressure management
+- `memory-leak-prevention` — preventing bitmap reference leaks
+- `loading-strategy` — showing placeholders while images load
+- `allocation-optimization` — reducing GC pressure from bitmap operations