android-sdd 1.0.0

package/skills/Networking/Fallback Strategy/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: fallback-strategy
+description: >
+  Fallback strategies for handling network and data failures in Android.
+  Load this skill when deciding what to show after all retries are exhausted,
+  serving stale cache on network failure, implementing graceful degradation,
+  or building resilient offline-capable features.
+---
+
+# Fallback Strategy
+
+## Overview
+A fallback strategy defines what the app does when the primary data source fails. Instead of showing an error and stopping, the app degrades gracefully — serving cached data, a default value, or a reduced-functionality state. The goal is to keep the user productive even when connectivity or the server is unavailable.
+
+---
+
+## Core Principles
+
+- Always try the **fastest/most reliable source first** — then fall back in order
+- Serve **stale data with a staleness indicator** rather than a hard error when possible
+- Fallback order: memory cache → disk cache → network → default/empty
+- Never silently serve stale data without indicating it to the user
+- Fallback behavior must be **explicit in the repository** — not implicit
+
+---
+
+## Fallback Chain Pattern
+
+```kotlin
+// ✅ Explicit fallback chain in repository
+class UserRepositoryImpl @Inject constructor(
+    private val remoteSource: UserRemoteDataSource,
+    private val localSource: UserLocalDataSource,
+    private val memoryCache: UserMemoryCache
+) : UserRepository {
+
+    override suspend fun getUser(id: String): Result<User> {
+        // 1. Memory cache
+        memoryCache.get(id)?.let { return Result.success(it) }
+
+        // 2. Network
+        val networkResult = runCatching { remoteSource.getUser(id) }
+        if (networkResult.isSuccess) {
+            val user = networkResult.getOrThrow()
+            memoryCache.put(id, user)
+            localSource.saveUser(user)
+            return Result.success(user)
+        }
+
+        // 3. Disk cache fallback
+        val cached = localSource.getUser(id)
+        if (cached != null) {
+            return Result.success(cached.copy(isStale = true))
+        }
+
+        // 4. All sources failed
+        return networkResult  // propagate original error
+    }
+}
+```
+
+---
+
+## Stale Data Model
+
+```kotlin
+// ✅ Domain model carries staleness flag
+data class User(
+    val id: String,
+    val name: String,
+    val email: String,
+    val isStale: Boolean = false  // true when served from cache after network failure
+)
+
+// ✅ UI shows staleness indicator
+@Composable
+fun UserDetailScreen(state: UserDetailUiState) {
+    if (state is UserDetailUiState.Success) {
+        if (state.user.isStale) {
+            StaleBanner(message = "Showing cached data — pull to refresh")
+        }
+        UserContent(state.user)
+    }
+}
+```
+
+---
+
+## Network-First with Cache Fallback (Flow)
+
+```kotlin
+// ✅ Emit cached data immediately, then update with network
+override fun getUserStream(id: String): Flow<Result<User>> = flow {
+    // Emit cached immediately
+    val cached = localSource.getUser(id)
+    if (cached != null) emit(Result.success(cached.copy(isStale = true)))
+
+    // Fetch fresh from network
+    runCatching { remoteSource.getUser(id) }
+        .onSuccess { fresh ->
+            localSource.saveUser(fresh)
+            emit(Result.success(fresh))
+        }
+        .onFailure { error ->
+            if (cached == null) emit(Result.failure(error))
+            // else already emitted stale — don't emit error
+        }
+}
+```
+
+---
+
+## Default Value Fallback
+
+```kotlin
+// ✅ Return sensible defaults when data is unavailable
+override suspend fun getAppConfig(): AppConfig {
+    return runCatching { remoteSource.getConfig() }
+        .getOrElse {
+            localSource.getConfig() ?: AppConfig.default()
+        }
+}
+
+// ✅ Default config
+data class AppConfig(
+    val featureFlags: Map<String, Boolean> = emptyMap(),
+    val maxUploadSize: Long = 10 * 1024 * 1024L  // 10MB
+) {
+    companion object {
+        fun default() = AppConfig()
+    }
+}
+```
+
+---
+
+## Partial Fallback (Feature Degradation)
+
+```kotlin
+// ✅ Load what's available — degrade features that can't load
+data class DashboardData(
+    val user: User,
+    val recentOrders: List<Order> = emptyList(),  // empty = orders unavailable
+    val notifications: List<Notification> = emptyList(),
+    val ordersError: Boolean = false,
+    val notificationsError: Boolean = false
+)
+
+suspend fun loadDashboard(userId: String): DashboardData {
+    val user = userRepository.getUser(userId).getOrThrow()  // required — throw if fails
+
+    val orders = orderRepository.getRecentOrders(userId)
+    val notifications = notificationRepository.getUnread(userId)
+
+    return DashboardData(
+        user = user,
+        recentOrders = orders.getOrDefault(emptyList()),
+        notifications = notifications.getOrDefault(emptyList()),
+        ordersError = orders.isFailure,
+        notificationsError = notifications.isFailure
+    )
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Showing a hard error screen when cached data is available — use stale data instead
+- Silently serving stale data without any indicator — user doesn't know data may be old
+- Retrying indefinitely before falling back — set a max retry then fall back
+- Treating all fallback data the same as fresh data — mark staleness explicitly
+- Fallback logic scattered across ViewModel and Repository — keep it in the repository
+
+---
+
+## Related Skills
+- `retry-backoff` — exhausting retries before triggering fallback
+- `cache-strategy` — cache implementation details
+- `offline-first` — building apps that work without connectivity
+- `error-handling` — propagating errors when all fallbacks fail
+- `loading-strategy` — showing appropriate loading states during fallback

package/skills/Networking/Ktor/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: ktor
+description: >
+  Ktor HTTP client setup and usage for Android and KMP projects.
+  Load this skill when using Ktor as the HTTP client, configuring
+  plugins, defining typed API calls, handling responses, or building
+  a shared networking layer in a Kotlin Multiplatform project.
+---
+
+# Ktor
+
+## Overview
+Ktor Client is a multiplatform HTTP client built on coroutines. It is the preferred choice for KMP projects where the networking layer is shared between Android and iOS. It uses a plugin-based architecture for features like serialization, auth, logging, and retry.
+
+---
+
+## Core Principles
+
+- Use Ktor when the networking layer must be shared across platforms (KMP)
+- Use Retrofit for Android-only projects — Ktor for KMP
+- Configure one `HttpClient` instance per app — provide via DI
+- All requests are `suspend` functions — no callbacks
+- Handle errors at the repository level — wrap in `Result`
+
+---
+
+## Setup
+
+```toml
+# libs.versions.toml
+[versions]
+ktor = "2.3.12"
+
+[libraries]
+ktor-client-core         = { module = "io.ktor:ktor-client-core", version.ref = "ktor" }
+ktor-client-okhttp       = { module = "io.ktor:ktor-client-okhttp", version.ref = "ktor" }    # Android
+ktor-client-darwin       = { module = "io.ktor:ktor-client-darwin", version.ref = "ktor" }    # iOS
+ktor-client-content-negotiation = { module = "io.ktor:ktor-client-content-negotiation", version.ref = "ktor" }
+ktor-serialization-kotlinx-json = { module = "io.ktor:ktor-serialization-kotlinx-json", version.ref = "ktor" }
+ktor-client-logging      = { module = "io.ktor:ktor-client-logging", version.ref = "ktor" }
+ktor-client-auth         = { module = "io.ktor:ktor-client-auth", version.ref = "ktor" }
+```
+
+---
+
+## Client Configuration
+
+```kotlin
+// ✅ Shared HttpClient — configured once
+fun createHttpClient(json: Json): HttpClient {
+    return HttpClient(OkHttp) {  // use Darwin engine on iOS
+        // Serialization
+        install(ContentNegotiation) {
+            json(json)
+        }
+
+        // Logging
+        install(Logging) {
+            logger = object : Logger {
+                override fun log(message: String) {
+                    println("Ktor: $message")
+                }
+            }
+            level = if (BuildConfig.DEBUG) LogLevel.BODY else LogLevel.NONE
+        }
+
+        // Auth
+        install(Auth) {
+            bearer {
+                loadTokens {
+                    BearerTokens(
+                        accessToken = tokenStorage.getAccessToken() ?: "",
+                        refreshToken = tokenStorage.getRefreshToken() ?: ""
+                    )
+                }
+                refreshTokens {
+                    val newTokens = tokenApi.refresh(oldTokens?.refreshToken ?: "")
+                    tokenStorage.save(newTokens)
+                    BearerTokens(newTokens.accessToken, newTokens.refreshToken)
+                }
+            }
+        }
+
+        // Default request config
+        defaultRequest {
+            url(BuildConfig.BASE_URL)
+            contentType(ContentType.Application.Json)
+            header("X-Platform", "android")
+        }
+
+        // Timeouts
+        install(HttpTimeout) {
+            requestTimeoutMillis = 30_000
+            connectTimeoutMillis = 15_000
+            socketTimeoutMillis = 30_000
+        }
+    }
+}
+```
+
+---
+
+## API Calls
+
+```kotlin
+// ✅ Typed API functions using Ktor DSL
+class UserRemoteDataSource @Inject constructor(
+    private val client: HttpClient
+) {
+    suspend fun getUsers(): List<UserDto> {
+        return client.get("users").body()
+    }
+
+    suspend fun getUser(id: String): UserDto {
+        return client.get("users/$id").body()
+    }
+
+    suspend fun createUser(request: CreateUserRequest): UserDto {
+        return client.post("users") {
+            setBody(request)
+        }.body()
+    }
+
+    suspend fun updateUser(id: String, request: UpdateUserRequest): UserDto {
+        return client.put("users/$id") {
+            setBody(request)
+        }.body()
+    }
+
+    suspend fun deleteUser(id: String) {
+        client.delete("users/$id")
+    }
+
+    suspend fun searchUsers(query: String, page: Int): PagedResponse<UserDto> {
+        return client.get("users") {
+            parameter("q", query)
+            parameter("page", page)
+        }.body()
+    }
+}
+```
+
+---
+
+## Error Handling
+
+```kotlin
+// ✅ Wrap Ktor calls in runCatching at the repository level
+override suspend fun getUser(id: String): Result<User> = runCatching {
+    val dto = remoteDataSource.getUser(id)
+    mapper.toDomain(dto)
+}.recoverCatching { throwable ->
+    when (throwable) {
+        is ClientRequestException -> throw ApiException(
+            code = throwable.response.status.value,
+            message = throwable.response.bodyAsText()
+        )
+        is ServerResponseException -> throw ServerException(
+            code = throwable.response.status.value
+        )
+        is IOException -> throw NetworkException("No internet")
+        else -> throw throwable
+    }
+}
+```
+
+---
+
+## File Upload
+
+```kotlin
+// ✅ Multipart upload with Ktor
+suspend fun uploadAvatar(userId: String, file: ByteArray, fileName: String): AvatarDto {
+    return client.submitFormWithBinaryData(
+        url = "users/$userId/avatar",
+        formData = formData {
+            append("avatar", file, Headers.build {
+                append(HttpHeaders.ContentType, "image/jpeg")
+                append(HttpHeaders.ContentDisposition, "filename=$fileName")
+            })
+        }
+    ).body()
+}
+```
+
+---
+
+## KMP Engine Selection
+
+```kotlin
+// ✅ Expect/actual for engine selection in KMP
+// commonMain
+expect fun createEngine(): HttpClientEngine
+
+// androidMain
+actual fun createEngine(): HttpClientEngine = OkHttp.create()
+
+// iosMain
+actual fun createEngine(): HttpClientEngine = Darwin.create()
+```
+
+---
+
+## Anti-Patterns
+
+- Using Ktor in Android-only projects when Retrofit is simpler and more established
+- Creating a new `HttpClient` per request — expensive, use singleton
+- Not installing `HttpTimeout` — requests can hang indefinitely
+- Catching exceptions in the data source — wrap at repository level
+- Using string concatenation for URL building — use `parameter()` and path segments
+
+---
+
+## Related Skills
+- `retrofit` — alternative for Android-only projects
+- `serialization` — Kotlinx Serialization shared Json instance
+- `kmp` — KMP project structure and engine selection
+- `authentication` — token management with Ktor Auth plugin
+- `retry-backoff` — retry plugin for Ktor

package/skills/Networking/Multipart Upload/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: multipart-upload
+description: >
+  Multipart file upload in Android using Retrofit or Ktor.
+  Load this skill when uploading images, videos, or files to a server,
+  tracking upload progress, handling large file uploads, or sending
+  mixed form data with files.
+---
+
+# Multipart Upload
+
+## Overview
+
+Multipart upload sends files and form data in a single HTTP request using `multipart/form-data` encoding. On Android, files are typically picked from the gallery or camera, converted to a `MultipartBody.Part`, and sent via Retrofit or Ktor. Progress tracking requires a custom `RequestBody` wrapper.
+
+---
+
+## Core Principles
+
+- Never read the full file into memory — stream from `Uri` using `ContentResolver`
+- Track upload progress via a custom `RequestBody` wrapper — not polling
+- Run uploads in a `CoroutineWorker` for long-running or background uploads
+- Compress images before upload when size matters — respect server limits
+- Show progress in the UI via `StateFlow` — cancel is a first-class operation
+
+---
+
+## Retrofit Multipart Upload
+
+```kotlin
+// ✅ API interface
+interface MediaApi {
+    @Multipart
+    @POST("users/{id}/avatar")
+    suspend fun uploadAvatar(
+        @Path("id") userId: String,
+        @Part avatar: MultipartBody.Part
+    ): AvatarDto
+
+    @Multipart
+    @POST("posts")
+    suspend fun createPost(
+        @Part("title") title: RequestBody,
+        @Part("description") description: RequestBody,
+        @Part image: MultipartBody.Part
+    ): PostDto
+}
+
+// ✅ Build MultipartBody.Part from Uri
+fun Context.uriToMultipartPart(uri: Uri, partName: String): MultipartBody.Part {
+    val mimeType = contentResolver.getType(uri) ?: "application/octet-stream"
+    val fileName = uri.getFileName(contentResolver) ?: "upload"
+
+    val requestBody = object : RequestBody() {
+        override fun contentType() = mimeType.toMediaType()
+
+        override fun contentLength(): Long {
+            return contentResolver.openFileDescriptor(uri, "r")?.statSize ?: -1
+        }
+
+        override fun writeTo(sink: BufferedSink) {
+            contentResolver.openInputStream(uri)?.use { input ->
+                sink.writeAll(input.source())
+            }
+        }
+    }
+
+    return MultipartBody.Part.createFormData(partName, fileName, requestBody)
+}
+
+fun Uri.getFileName(contentResolver: ContentResolver): String? {
+    return contentResolver.query(this, null, null, null, null)?.use { cursor ->
+        val index = cursor.getColumnIndex(OpenableColumns.DISPLAY_NAME)
+        cursor.moveToFirst()
+        cursor.getString(index)
+    }
+}
+```
+
+---
+
+## Progress Tracking
+
+```kotlin
+// ✅ RequestBody wrapper with progress callback
+class ProgressRequestBody(
+    private val delegate: RequestBody,
+    private val onProgress: (Int) -> Unit
+) : RequestBody() {
+
+    override fun contentType() = delegate.contentType()
+    override fun contentLength() = delegate.contentLength()
+
+    override fun writeTo(sink: BufferedSink) {
+        val total = contentLength()
+        var uploaded = 0L
+
+        val progressSink = object : ForwardingSink(sink) {
+            override fun write(source: Buffer, byteCount: Long) {
+                super.write(source, byteCount)
+                uploaded += byteCount
+                val progress = if (total > 0) ((uploaded * 100) / total).toInt() else 0
+                onProgress(progress)
+            }
+        }
+
+        delegate.writeTo(progressSink.buffer())
+    }
+}
+
+// ✅ Use in ViewModel
+class UploadViewModel @Inject constructor(
+    private val mediaRepository: MediaRepository
+) : ViewModel() {
+
+    private val _progress = MutableStateFlow(0)
+    val progress: StateFlow<Int> = _progress.asStateFlow()
+
+    private val _state = MutableStateFlow<UploadState>(UploadState.Idle)
+    val state: StateFlow<UploadState> = _state.asStateFlow()
+
+    private var uploadJob: Job? = null
+
+    fun upload(uri: Uri) {
+        uploadJob = viewModelScope.launch {
+            _state.value = UploadState.Uploading
+            mediaRepository.uploadFile(uri) { progress ->
+                _progress.value = progress
+            }.fold(
+                onSuccess = { _state.value = UploadState.Success(it) },
+                onFailure = { _state.value = UploadState.Error(it.message ?: "Upload failed") }
+            )
+        }
+    }
+
+    fun cancel() {
+        uploadJob?.cancel()
+        _state.value = UploadState.Idle
+        _progress.value = 0
+    }
+}
+
+sealed interface UploadState {
+    data object Idle : UploadState
+    data object Uploading : UploadState
+    data class Success(val url: String) : UploadState
+    data class Error(val message: String) : UploadState
+}
+```
+
+---
+
+## Image Compression Before Upload
+
+```kotlin
+// ✅ Compress bitmap before upload
+fun Uri.compressToByteArray(
+    context: Context,
+    maxWidth: Int = 1024,
+    maxHeight: Int = 1024,
+    quality: Int = 85
+): ByteArray {
+    val bitmap = BitmapFactory.decodeStream(context.contentResolver.openInputStream(this))
+    val scaled = Bitmap.createScaledBitmap(
+        bitmap,
+        maxWidth.coerceAtMost(bitmap.width),
+        maxHeight.coerceAtMost(bitmap.height),
+        true
+    )
+    return ByteArrayOutputStream().also { out ->
+        scaled.compress(Bitmap.CompressFormat.JPEG, quality, out)
+    }.toByteArray()
+}
+```
+
+---
+
+## Ktor Multipart Upload
+
+```kotlin
+// ✅ Ktor multipart upload
+suspend fun uploadAvatar(userId: String, fileBytes: ByteArray, fileName: String): AvatarDto {
+    return client.submitFormWithBinaryData(
+        url = "users/$userId/avatar",
+        formData = formData {
+            append("avatar", fileBytes, Headers.build {
+                append(HttpHeaders.ContentType, "image/jpeg")
+                append(HttpHeaders.ContentDisposition, "filename=$fileName")
+            })
+        }
+    ).body()
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Loading the entire file into a `ByteArray` before upload — causes OOM for large files
+- Not showing progress for uploads over 1MB — user has no feedback
+- No cancel mechanism — user is stuck waiting
+- Not compressing images — wastes bandwidth and hits server size limits
+- Blocking the main thread during file reading — use coroutines with IO dispatcher
+
+---
+
+## Related Skills
+
+- `retrofit` — Retrofit client setup
+- `ktor` — Ktor client for KMP
+- `workmanager` — background upload for large or resumable uploads
+- `camera` — capturing images to upload
+- `filesystem` — reading files from device storage