android-sdd 1.0.0

package/skills/Data Layer/Sync Engine/SKILL.md

@@ -0,0 +1,268 @@
+---
+name: sync-engine
+description: >
+  Data synchronization engine design for Android offline-first apps.
+  Load this skill when designing how local data syncs with a remote server,
+  handling bidirectional sync, managing sync state, or scheduling background sync.
+---
+
+# Sync Engine
+
+## Overview
+A sync engine coordinates the flow of data between local storage (Room) and a remote server. In offline-first apps, local data is always the source of truth for the UI — the sync engine ensures local and remote stay consistent. It handles connectivity awareness, retry logic, conflict resolution, and sync state tracking.
+
+---
+
+## Core Principles
+
+- **Local first, sync second** — UI reads from Room, sync runs in background
+- Sync is **idempotent** — running it twice produces the same result
+- Track sync state explicitly — show sync status in UI where relevant
+- Use **WorkManager** for background sync — survives process death and reboots
+- Handle conflicts explicitly — don't silently overwrite data
+
+---
+
+## Sync Architecture
+
+```
+UI → ViewModel → Repository (Room) ← Sync Engine → Remote API
+                      ↑
+              [Source of Truth]
+```
+
+---
+
+## Sync State Tracking
+
+```kotlin
+// ✅ Track sync state per entity or globally
+enum class SyncStatus {
+    IDLE,
+    SYNCING,
+    SUCCESS,
+    FAILED
+}
+
+data class SyncState(
+    val status: SyncStatus = SyncStatus.IDLE,
+    val lastSyncTime: Instant? = null,
+    val error: String? = null
+)
+
+// ✅ Persist sync metadata
+@Entity(tableName = "sync_metadata")
+data class SyncMetadataEntity(
+    @PrimaryKey val entityType: String,  // "users", "orders", etc.
+    val lastSyncTime: Long,
+    val lastSyncSuccess: Boolean,
+    val pendingChanges: Int = 0
+)
+```
+
+---
+
+## Sync Engine Implementation
+
+```kotlin
+class UserSyncEngine @Inject constructor(
+    private val userApi: UserApi,
+    private val userDao: UserDao,
+    private val syncMetadataDao: SyncMetadataDao,
+    private val mapper: UserMapper,
+    private val clock: Clock = Clock.systemUTC()
+) {
+    companion object {
+        const val ENTITY_TYPE = "users"
+    }
+
+    // ✅ Pull sync — fetch remote, update local
+    suspend fun syncFromRemote(): SyncResult {
+        return try {
+            val lastSync = syncMetadataDao.getLastSyncTime(ENTITY_TYPE)
+            val remoteUsers = if (lastSync != null) {
+                userApi.getUsersModifiedSince(lastSync)  // delta sync
+            } else {
+                userApi.getAllUsers()  // full sync on first run
+            }
+
+            userDao.upsertAll(remoteUsers.map(mapper::toEntity))
+
+            val deletedIds = userApi.getDeletedSince(lastSync)
+            userDao.deleteByIds(deletedIds)
+
+            syncMetadataDao.updateSyncTime(ENTITY_TYPE, clock.instant().toEpochMilli())
+            SyncResult.Success(remoteUsers.size)
+        } catch (e: IOException) {
+            SyncResult.NetworkError(e)
+        } catch (e: Exception) {
+            SyncResult.UnknownError(e)
+        }
+    }
+
+    // ✅ Push sync — send local changes to remote
+    suspend fun syncToRemote(): SyncResult {
+        return try {
+            val pendingChanges = userDao.getPendingSync()
+
+            pendingChanges.forEach { entity ->
+                when (entity.syncState) {
+                    SyncState.CREATED -> userApi.createUser(mapper.toDto(entity))
+                    SyncState.UPDATED -> userApi.updateUser(entity.id, mapper.toDto(entity))
+                    SyncState.DELETED -> userApi.deleteUser(entity.id)
+                }
+                userDao.markSynced(entity.id)
+            }
+
+            SyncResult.Success(pendingChanges.size)
+        } catch (e: Exception) {
+            SyncResult.UnknownError(e)
+        }
+    }
+}
+
+sealed class SyncResult {
+    data class Success(val count: Int) : SyncResult()
+    data class NetworkError(val cause: IOException) : SyncResult()
+    data class UnknownError(val cause: Exception) : SyncResult()
+}
+```
+
+---
+
+## Tracking Local Changes
+
+```kotlin
+// ✅ Add sync state column to entity
+@Entity(tableName = "users")
+data class UserEntity(
+    @PrimaryKey val id: String,
+    val name: String,
+    val email: String,
+    @ColumnInfo(name = "sync_state") val syncState: String = "SYNCED"
+)
+
+enum class SyncState { SYNCED, CREATED, UPDATED, DELETED }
+
+// ✅ Mark as pending on local write
+@Dao
+interface UserDao {
+    @Query("UPDATE users SET sync_state = 'UPDATED' WHERE id = :id")
+    suspend fun markPendingUpdate(id: String)
+
+    @Query("UPDATE users SET sync_state = 'DELETED' WHERE id = :id")
+    suspend fun markPendingDelete(id: String)
+
+    @Query("SELECT * FROM users WHERE sync_state != 'SYNCED'")
+    suspend fun getPendingSync(): List<UserEntity>
+
+    @Query("UPDATE users SET sync_state = 'SYNCED' WHERE id = :id")
+    suspend fun markSynced(id: String)
+}
+```
+
+---
+
+## Background Sync with WorkManager
+
+```kotlin
+// ✅ Periodic background sync
+class SyncWorker(
+    context: Context,
+    params: WorkerParameters
+) : CoroutineWorker(context, params) {
+
+    @Inject lateinit var syncEngine: UserSyncEngine
+
+    override suspend fun doWork(): Result {
+        return try {
+            syncEngine.syncFromRemote()
+            syncEngine.syncToRemote()
+            Result.success()
+        } catch (e: Exception) {
+            if (runAttemptCount < 3) Result.retry() else Result.failure()
+        }
+    }
+}
+
+// ✅ Schedule periodic sync
+fun schedulePeriodic(context: Context) {
+    WorkManager.getInstance(context).enqueueUniquePeriodicWork(
+        "periodic_sync",
+        ExistingPeriodicWorkPolicy.KEEP,
+        PeriodicWorkRequestBuilder<SyncWorker>(15, TimeUnit.MINUTES)
+            .setConstraints(
+                Constraints.Builder()
+                    .setRequiredNetworkType(NetworkType.CONNECTED)
+                    .build()
+            )
+            .setBackoffCriteria(BackoffPolicy.EXPONENTIAL, 1, TimeUnit.MINUTES)
+            .build()
+    )
+}
+
+// ✅ Trigger immediate sync on app foreground
+fun scheduleImmediateSync(context: Context) {
+    WorkManager.getInstance(context).enqueueUniqueWork(
+        "immediate_sync",
+        ExistingWorkPolicy.REPLACE,
+        OneTimeWorkRequestBuilder<SyncWorker>()
+            .setConstraints(
+                Constraints.Builder()
+                    .setRequiredNetworkType(NetworkType.CONNECTED)
+                    .build()
+            )
+            .build()
+    )
+}
+```
+
+---
+
+## Connectivity-Aware Sync
+
+```kotlin
+// ✅ Observe connectivity and trigger sync when online
+class ConnectivitySyncTrigger @Inject constructor(
+    private val context: Context,
+    private val workManager: WorkManager
+) {
+    fun observe(): Flow<Boolean> = callbackFlow {
+        val cm = context.getSystemService(ConnectivityManager::class.java)
+        val callback = object : ConnectivityManager.NetworkCallback() {
+            override fun onAvailable(network: Network) {
+                trySend(true)
+                workManager.enqueueUniqueWork(
+                    "connectivity_sync",
+                    ExistingWorkPolicy.REPLACE,
+                    OneTimeWorkRequestBuilder<SyncWorker>().build()
+                )
+            }
+            override fun onLost(network: Network) { trySend(false) }
+        }
+        cm.registerDefaultNetworkCallback(callback)
+        awaitClose { cm.unregisterNetworkCallback(callback) }
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Syncing on the main thread — causes ANR
+- No retry logic — transient network errors permanently break sync
+- Overwriting local changes with remote on every sync — data loss
+- No sync state tracking — UI can't show sync status or errors
+- Not handling delete propagation — deleted items reappear after sync
+- Full sync every time — use delta sync (modified_since) for large datasets
+
+---
+
+## Related Skills
+- `conflict-resolution` — handling data conflicts during sync
+- `merge-strategy` — merging local and remote changes
+- `workmanager` — durable background sync scheduling
+- `room` — local data source for offline-first
+- `offline-first` — full offline-first architecture
+- `repository-pattern` — sync engine integration in repository

package/skills/Dependency Injection/Dagger/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: dagger
+description: >
+  Dagger 2 dependency injection for Android without Hilt.
+  Load this skill when working on a project that uses raw Dagger (not Hilt),
+  understanding Hilt's internals, building custom components/subcomponents,
+  or migrating from Dagger to Hilt.
+---
+
+# Dagger 2
+
+## Overview
+Dagger 2 is a compile-time DI framework that generates Java code for dependency injection. Hilt is built on top of Dagger and covers most Android use cases. Use raw Dagger when you need custom component hierarchies, non-standard scopes, or are working on a project that predates Hilt.
+
+---
+
+## Core Principles
+
+- Dagger generates all DI code at **compile time** — no reflection
+- **Components** are the bridge between the object graph and the consumer
+- **Modules** provide dependencies the constructor can't supply
+- **Subcomponents** inherit the parent's bindings and add their own scope
+- Prefer Hilt for new Android projects — raw Dagger only when needed
+
+---
+
+## Basic Setup
+
+```toml
+[versions]
+dagger = "2.51.1"
+
+[libraries]
+dagger         = { module = "com.google.dagger:dagger", version.ref = "dagger" }
+dagger-compiler = { module = "com.google.dagger:dagger-compiler", version.ref = "dagger" }
+```
+
+```kotlin
+dependencies {
+    implementation(libs.dagger)
+    ksp(libs.dagger.compiler)
+}
+```
+
+---
+
+## Component
+
+```kotlin
+// ✅ Application-level component
+@Singleton
+@Component(modules = [
+    NetworkModule::class,
+    DatabaseModule::class,
+    RepositoryModule::class
+])
+interface AppComponent {
+
+    // Expose for injection into Application
+    fun inject(app: MyApplication)
+
+    // Factory — preferred over Builder for constructor params
+    @Component.Factory
+    interface Factory {
+        fun create(@BindsInstance @ApplicationContext context: Context): AppComponent
+    }
+}
+
+// ✅ Initialize in Application
+class MyApplication : Application() {
+    val appComponent: AppComponent by lazy {
+        DaggerAppComponent.factory().create(this)
+    }
+
+    override fun onCreate() {
+        super.onCreate()
+        appComponent.inject(this)
+    }
+}
+```
+
+---
+
+## Modules
+
+```kotlin
+// ✅ @Module — provides dependencies
+@Module
+object NetworkModule {
+
+    @Provides
+    @Singleton
+    fun provideOkHttpClient(): OkHttpClient =
+        OkHttpClient.Builder().build()
+
+    @Provides
+    @Singleton
+    fun provideRetrofit(client: OkHttpClient): Retrofit =
+        Retrofit.Builder()
+            .baseUrl("https://api.example.com/")
+            .client(client)
+            .build()
+
+    @Provides
+    @Singleton
+    fun provideUserApi(retrofit: Retrofit): UserApi =
+        retrofit.create(UserApi::class.java)
+}
+
+// ✅ @Binds — for interface → implementation binding (abstract module)
+@Module
+abstract class RepositoryModule {
+
+    @Binds
+    @Singleton
+    abstract fun bindUserRepository(impl: UserRepositoryImpl): UserRepository
+}
+```
+
+---
+
+## Scopes
+
+```kotlin
+// ✅ Define custom scopes
+@Scope
+@Retention(AnnotationRetention.RUNTIME)
+annotation class ActivityScope
+
+@Scope
+@Retention(AnnotationRetention.RUNTIME)
+annotation class FragmentScope
+
+// ✅ Use on component and provided dependency
+@ActivityScope
+@Subcomponent(modules = [ActivityModule::class])
+interface ActivityComponent {
+    fun inject(activity: MainActivity)
+
+    @Subcomponent.Factory
+    interface Factory {
+        fun create(): ActivityComponent
+    }
+}
+```
+
+---
+
+## Subcomponents
+
+```kotlin
+// ✅ Subcomponent inherits parent bindings, adds its own scope
+@ActivityScope
+@Subcomponent(modules = [ActivityModule::class])
+interface ActivityComponent {
+    fun inject(activity: MainActivity)
+
+    @Subcomponent.Factory
+    interface Factory {
+        fun create(): ActivityComponent
+    }
+}
+
+// ✅ Register subcomponent in parent
+@Module(subcomponents = [ActivityComponent::class])
+object AppSubcomponents
+
+// ✅ Create subcomponent from parent
+class MainActivity : AppCompatActivity() {
+    private lateinit var activityComponent: ActivityComponent
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        activityComponent = (application as MyApplication)
+            .appComponent
+            .activityComponentFactory()
+            .create()
+        activityComponent.inject(this)
+        super.onCreate(savedInstanceState)
+    }
+}
+```
+
+---
+
+## Constructor Injection
+
+```kotlin
+// ✅ Same as Hilt — @Inject on constructor
+class UserRepository @Inject constructor(
+    private val userDao: UserDao,
+    private val userApi: UserApi
+)
+
+class UserMapper @Inject constructor()
+```
+
+---
+
+## Qualifiers
+
+```kotlin
+// ✅ Distinguish multiple bindings of the same type
+@Qualifier
+@Retention(AnnotationRetention.BINARY)
+annotation class BaseUrl
+
+@Module
+object NetworkModule {
+
+    @Provides
+    @Singleton
+    @BaseUrl
+    fun provideBaseUrl(): String = "https://api.example.com/"
+
+    @Provides
+    @Singleton
+    fun provideRetrofit(@BaseUrl baseUrl: String): Retrofit =
+        Retrofit.Builder().baseUrl(baseUrl).build()
+}
+```
+
+---
+
+## Lazy and Provider Injection
+
+```kotlin
+// ✅ Lazy<T> — defer initialization until first use
+class HeavyFeature @Inject constructor(
+    private val heavyDep: Lazy<HeavyDependency>
+) {
+    fun use() {
+        heavyDep.get().doWork()  // initialized on first call
+    }
+}
+
+// ✅ Provider<T> — get a new instance each time
+class RequestFactory @Inject constructor(
+    private val requestProvider: Provider<NetworkRequest>
+) {
+    fun createRequest(): NetworkRequest = requestProvider.get()
+}
+```
+
+---
+
+## Migration to Hilt
+
+```kotlin
+// Hilt replaces most Dagger boilerplate:
+
+// Dagger → Hilt equivalents
+@Component(modules = [...])
+interface AppComponent              →  @HiltAndroidApp on Application
+
+@ActivityScope @Subcomponent(...)
+interface ActivityComponent         →  @AndroidEntryPoint on Activity
+
+appComponent.inject(this)           →  Removed (automatic)
+
+@Component.Factory / @Component.Builder →  Removed (Hilt manages)
+
+// Keep raw Dagger when:
+// - Custom component hierarchy beyond what Hilt provides
+// - Non-Android modules (pure Kotlin/Java libraries)
+// - Existing codebase that's too large to migrate at once
+```
+
+---
+
+## Anti-Patterns
+
+- Field injection in non-Android classes — use constructor injection
+- Creating components outside of Application — breaks the object graph
+- Providing mutable singletons — hidden shared state causes bugs
+- Deep subcomponent hierarchies — prefer Hilt's flat component model
+- Not using `@Binds` for interface bindings — `@Provides` works but is less efficient
+
+---
+
+## Related Skills
+- `hilt` — Hilt (recommended for Android)
+- `koin` — alternative runtime DI
+- `annotation-processing` — KSP for Dagger code generation