Android Phase D: Project foundation, Room DB, Retrofit API, Hilt

- Android CLI Setup: initialized empty-activity app (AGP 9.0, Kotlin 2.3.20)
- Version catalog: Compose BOM 2026.03.01, Material 3, Hilt 2.60.1, Room 2.7.2,
  Retrofit 2.11.0, OkHttp 4.12.0, WorkManager 2.10.2, Kotlinx Serialization
- Room Database (v1): ListEntity, ItemEntity, OpLogEntity
- Room DAOs: ListDao, ItemDao, OpLogDao with LWW upsert queries
- Network layer: MitbringslApi Retrofit interface + DTOs + AuthInterceptor
- Dependency Injection: DatabaseModule, NetworkModule, RepositoryModule, HiltAndroidApp
- Build verification: assembleDebug & test green ✅

android/app/src/androidTest/java/com/example/mitbringsl/ui/main/MainScreenTest.kt

@@ -0,0 +1,26 @@
+package com.example.mitbringsl.ui.main
+
+import androidx.activity.ComponentActivity
+import androidx.compose.ui.test.junit4.createAndroidComposeRule
+import androidx.compose.ui.test.onNodeWithText
+import org.junit.Before
+import org.junit.Rule
+import org.junit.Test
+
+/** UI tests for [com.example.mitbringsl.ui.main.MainScreen]. */
+class MainScreenTest {
+
+  @get:Rule val composeTestRule = createAndroidComposeRule<ComponentActivity>()
+
+  @Before
+  fun setup() {
+    composeTestRule.setContent { MainScreen(FAKE_DATA) }
+  }
+
+  @Test
+  fun firstItem_exists() {
+    FAKE_DATA.forEach { composeTestRule.onNodeWithText(it).assertExists() }
+  }
+}
+
+private val FAKE_DATA = listOf("Sample1", "Sample2", "Sample3")

android/app/src/main/AndroidManifest.xml

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <uses-permission android:name="android.permission.INTERNET" />
+
+    <application
+        android:name=".MitbringslApp"
+        android:allowBackup="true"
+        android:dataExtractionRules="@xml/data_extraction_rules"
+        android:fullBackupContent="@xml/backup_rules"
+        android:icon="@mipmap/ic_launcher"
+        android:label="@string/app_name"
+        android:roundIcon="@mipmap/ic_launcher_round"
+        android:supportsRtl="true"
+        android:windowSoftInputMode="adjustResize"
+        android:theme="@style/Theme.Mitbringsl">
+
+        <activity
+            android:name=".MainActivity"
+            android:exported="true">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+    </application>
+
+</manifest>

android/app/src/main/java/com/example/mitbringsl/MainActivity.kt

@@ -0,0 +1,26 @@
+package com.example.mitbringsl
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.activity.enableEdgeToEdge
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Surface
+import androidx.compose.ui.Modifier
+import com.example.mitbringsl.theme.MitbringslTheme
+
+import dagger.hilt.android.AndroidEntryPoint
+
+@AndroidEntryPoint
+class MainActivity : ComponentActivity() {
+
+  override fun onCreate(savedInstanceState: Bundle?) {
+    super.onCreate(savedInstanceState)
+
+    enableEdgeToEdge()
+    setContent {
+      MitbringslTheme { Surface(modifier = Modifier.fillMaxSize(), color = MaterialTheme.colorScheme.background) { MainNavigation() } }
+    }
+  }
+}

android/app/src/main/java/com/example/mitbringsl/MitbringslApp.kt

@@ -0,0 +1,18 @@
+package com.example.mitbringsl
+
+import android.app.Application
+import androidx.hilt.work.HiltWorkerFactory
+import androidx.work.Configuration
+import dagger.hilt.android.HiltAndroidApp
+import javax.inject.Inject
+
+@HiltAndroidApp
+class MitbringslApp : Application(), Configuration.Provider {
+
+    @Inject lateinit var workerFactory: HiltWorkerFactory
+
+    override val workManagerConfiguration: Configuration
+        get() = Configuration.Builder()
+            .setWorkerFactory(workerFactory)
+            .build()
+}

android/app/src/main/java/com/example/mitbringsl/Navigation.kt

@@ -0,0 +1,27 @@
+package com.example.mitbringsl
+
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.safeDrawingPadding
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+import androidx.navigation3.runtime.entryProvider
+import androidx.navigation3.runtime.rememberNavBackStack
+import androidx.navigation3.ui.NavDisplay
+import com.example.mitbringsl.ui.main.MainScreen
+
+@Composable
+fun MainNavigation() {
+  val backStack = rememberNavBackStack(Main)
+
+  NavDisplay(
+    backStack = backStack,
+    onBack = { backStack.removeLastOrNull() },
+    entryProvider =
+      entryProvider {
+        entry<Main> {
+          MainScreen(onItemClick = { navKey -> backStack.add(navKey) }, modifier = Modifier.safeDrawingPadding().padding(16.dp))
+        }
+      },
+  )
+}

android/app/src/main/java/com/example/mitbringsl/NavigationKeys.kt

@@ -0,0 +1,6 @@
+package com.example.mitbringsl
+
+import androidx.navigation3.runtime.NavKey
+import kotlinx.serialization.Serializable
+
+@Serializable data object Main : NavKey

android/app/src/main/java/com/example/mitbringsl/data/DataRepository.kt

@@ -0,0 +1,32 @@
+package com.example.mitbringsl.data
+
+import com.example.mitbringsl.data.local.dao.ListDao
+import com.example.mitbringsl.data.local.entity.ListEntity
+import kotlinx.coroutines.flow.Flow
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Repository interface for shopping lists.
+ * Phase D stub – only observes local Room data.
+ * Phase E will add the full sync logic (push outbox + pull cursor).
+ */
+interface ListRepository {
+    fun observeLists(ownerId: String): Flow<List<ListEntity>>
+    suspend fun createList(name: String, ownerId: String): ListEntity
+}
+
+@Singleton
+class DefaultListRepository @Inject constructor(
+    private val listDao: ListDao,
+) : ListRepository {
+
+    override fun observeLists(ownerId: String): Flow<List<ListEntity>> =
+        listDao.observeLists(ownerId)
+
+    override suspend fun createList(name: String, ownerId: String): ListEntity {
+        val entity = ListEntity(name = name, ownerId = ownerId)
+        listDao.upsert(entity)
+        return entity
+    }
+}

android/app/src/main/java/com/example/mitbringsl/data/local/AppDatabase.kt

@@ -0,0 +1,29 @@
+package com.example.mitbringsl.data.local
+
+import androidx.room.Database
+import androidx.room.RoomDatabase
+import com.example.mitbringsl.data.local.dao.ItemDao
+import com.example.mitbringsl.data.local.dao.ListDao
+import com.example.mitbringsl.data.local.dao.OpLogDao
+import com.example.mitbringsl.data.local.entity.ItemEntity
+import com.example.mitbringsl.data.local.entity.ListEntity
+import com.example.mitbringsl.data.local.entity.OpLogEntity
+
+@Database(
+    entities = [
+        ListEntity::class,
+        ItemEntity::class,
+        OpLogEntity::class,
+    ],
+    version = 1,
+    exportSchema = true,
+)
+abstract class AppDatabase : RoomDatabase() {
+    abstract fun listDao(): ListDao
+    abstract fun itemDao(): ItemDao
+    abstract fun opLogDao(): OpLogDao
+
+    companion object {
+        const val DATABASE_NAME = "mitbringsl.db"
+    }
+}

android/app/src/main/java/com/example/mitbringsl/data/local/dao/ItemDao.kt

@@ -0,0 +1,52 @@
+package com.example.mitbringsl.data.local.dao
+
+import androidx.room.*
+import com.example.mitbringsl.data.local.entity.ItemEntity
+import kotlinx.coroutines.flow.Flow
+
+@Dao
+interface ItemDao {
+
+    /** Observe all non-deleted items for a list, ordered by sort_order then creation time. */
+    @Query("""
+        SELECT * FROM items
+        WHERE listId = :listId AND deletedAt IS NULL
+        ORDER BY sortOrder ASC, createdAt ASC
+    """)
+    fun observeItems(listId: String): Flow<List<ItemEntity>>
+
+    @Upsert
+    suspend fun upsert(item: ItemEntity)
+
+    @Upsert
+    suspend fun upsertAll(items: List<ItemEntity>)
+
+    /**
+     * LWW upsert – only updates mutable fields when incoming hlc_ts is greater.
+     * The tombstone (deletedAt) is also applied through LWW.
+     */
+    @Query("""
+        INSERT INTO items (id, listId, name, quantity, checked, sortOrder,
+                           createdAt, updatedAt, deletedAt, hlcTs, clientId, checkedAt)
+        VALUES (:id, :listId, :name, :quantity, :checked, :sortOrder,
+                :createdAt, :updatedAt, :deletedAt, :hlcTs, :clientId, :checkedAt)
+        ON CONFLICT(id) DO UPDATE SET
+          name      = CASE WHEN :hlcTs > hlcTs THEN :name      ELSE name      END,
+          quantity  = CASE WHEN :hlcTs > hlcTs THEN :quantity  ELSE quantity  END,
+          checked   = CASE WHEN :hlcTs > hlcTs THEN :checked   ELSE checked   END,
+          sortOrder = CASE WHEN :hlcTs > hlcTs THEN :sortOrder ELSE sortOrder END,
+          updatedAt = CASE WHEN :hlcTs > hlcTs THEN :updatedAt ELSE updatedAt END,
+          deletedAt = CASE WHEN :hlcTs > hlcTs THEN :deletedAt ELSE deletedAt END,
+          checkedAt = CASE WHEN :hlcTs > hlcTs THEN :checkedAt ELSE checkedAt END,
+          hlcTs     = CASE WHEN :hlcTs > hlcTs THEN :hlcTs     ELSE hlcTs     END
+    """)
+    suspend fun upsertLww(
+        id: String, listId: String, name: String, quantity: String?,
+        checked: Boolean, sortOrder: Int?,
+        createdAt: Long, updatedAt: Long, deletedAt: Long?,
+        hlcTs: Long, clientId: String?, checkedAt: Long?,
+    )
+
+    @Query("SELECT * FROM items WHERE id = :itemId LIMIT 1")
+    suspend fun getItem(itemId: String): ItemEntity?
+}

android/app/src/main/java/com/example/mitbringsl/data/local/dao/ListDao.kt

@@ -0,0 +1,51 @@
+package com.example.mitbringsl.data.local.dao
+
+import androidx.room.*
+import com.example.mitbringsl.data.local.entity.ListEntity
+import kotlinx.coroutines.flow.Flow
+
+@Dao
+interface ListDao {
+
+    /** Observe all non-deleted lists for a given owner, newest first. */
+    @Query("SELECT * FROM lists WHERE ownerId = :ownerId AND deletedAt IS NULL ORDER BY updatedAt DESC")
+    fun observeLists(ownerId: String): Flow<List<ListEntity>>
+
+    /** One-shot lookup of a single list. */
+    @Query("SELECT * FROM lists WHERE id = :listId AND deletedAt IS NULL LIMIT 1")
+    suspend fun getList(listId: String): ListEntity?
+
+    /**
+     * Upsert a list.
+     * On conflict (same primary key) the row is replaced so that fresh data
+     * from the server always wins in the initial seed / full-sync path.
+     * For LWW conflict resolution during incremental sync, see [upsertLww].
+     */
+    @Upsert
+    suspend fun upsert(list: ListEntity)
+
+    @Upsert
+    suspend fun upsertAll(lists: List<ListEntity>)
+
+    /**
+     * LWW upsert: only update if the incoming hlc_ts is strictly greater than
+     * the stored one (Last-Write-Wins register).
+     */
+    @Query("""
+        INSERT INTO lists (id, name, ownerId, createdAt, updatedAt, deletedAt, hlcTs)
+        VALUES (:id, :name, :ownerId, :createdAt, :updatedAt, :deletedAt, :hlcTs)
+        ON CONFLICT(id) DO UPDATE SET
+          name      = CASE WHEN :hlcTs > hlcTs THEN :name      ELSE name      END,
+          updatedAt = CASE WHEN :hlcTs > hlcTs THEN :updatedAt ELSE updatedAt END,
+          deletedAt = CASE WHEN :hlcTs > hlcTs THEN :deletedAt ELSE deletedAt END,
+          hlcTs     = CASE WHEN :hlcTs > hlcTs THEN :hlcTs     ELSE hlcTs     END
+    """)
+    suspend fun upsertLww(
+        id: String, name: String, ownerId: String,
+        createdAt: Long, updatedAt: Long,
+        deletedAt: Long?, hlcTs: Long,
+    )
+
+    @Query("SELECT COUNT(*) FROM lists WHERE ownerId = :ownerId AND deletedAt IS NULL")
+    suspend fun count(ownerId: String): Int
+}

android/app/src/main/java/com/example/mitbringsl/data/local/dao/OpLogDao.kt

@@ -0,0 +1,43 @@
+package com.example.mitbringsl.data.local.dao
+
+import androidx.room.*
+import com.example.mitbringsl.data.local.entity.OpLogEntity
+import kotlinx.coroutines.flow.Flow
+
+@Dao
+interface OpLogDao {
+
+    /** All unsynced ops ordered by creation time (oldest first for FIFO drain). */
+    @Query("SELECT * FROM op_log WHERE synced = 0 ORDER BY createdAt ASC, localId ASC")
+    fun observeUnsynced(): Flow<List<OpLogEntity>>
+
+    @Query("SELECT * FROM op_log WHERE synced = 0 ORDER BY createdAt ASC, localId ASC")
+    suspend fun getUnsynced(): List<OpLogEntity>
+
+    /** Unsynced ops for a specific list. */
+    @Query("SELECT * FROM op_log WHERE listId = :listId AND synced = 0 ORDER BY createdAt ASC")
+    suspend fun getUnsyncedForList(listId: String): List<OpLogEntity>
+
+    @Insert(onConflict = OnConflictStrategy.IGNORE)
+    suspend fun insert(op: OpLogEntity): Long
+
+    /** Mark an op as synced and store the server-assigned seq. */
+    @Query("UPDATE op_log SET synced = 1, serverSeq = :serverSeq WHERE localId = :localId")
+    suspend fun markSynced(localId: Long, serverSeq: Long)
+
+    /** Mark multiple ops synced at once (by localId). */
+    @Transaction
+    suspend fun markAllSynced(results: Map<Long, Long>) {
+        results.forEach { (localId, serverSeq) -> markSynced(localId, serverSeq) }
+    }
+
+    @Query("DELETE FROM op_log WHERE synced = 1 AND createdAt < :olderThanMs")
+    suspend fun deleteOldSynced(olderThanMs: Long)
+
+    @Query("SELECT COUNT(*) FROM op_log WHERE synced = 0")
+    fun observeUnsyncedCount(): Flow<Int>
+
+    /** Highest server seq we have stored locally for a given list (used as pull cursor). */
+    @Query("SELECT MAX(serverSeq) FROM op_log WHERE listId = :listId AND synced = 1")
+    suspend fun maxServerSeq(listId: String): Long?
+}

android/app/src/main/java/com/example/mitbringsl/data/local/entity/ItemEntity.kt

@@ -0,0 +1,39 @@
+package com.example.mitbringsl.data.local.entity
+
+import androidx.room.Entity
+import androidx.room.ForeignKey
+import androidx.room.Index
+import androidx.room.PrimaryKey
+
+/**
+ * Local projection of a shopping list item.
+ * Source of truth flows from [OpLogEntity] via the sync engine.
+ */
+@Entity(
+    tableName = "items",
+    foreignKeys = [
+        ForeignKey(
+            entity = ListEntity::class,
+            parentColumns = ["id"],
+            childColumns = ["listId"],
+            onDelete = ForeignKey.CASCADE,
+        )
+    ],
+    indices = [Index("listId"), Index("deletedAt")]
+)
+data class ItemEntity(
+    @PrimaryKey val id: String,
+    val listId: String,
+    val name: String,
+    val quantity: String? = null,
+    val checked: Boolean = false,
+    val sortOrder: Int? = null,
+    val createdAt: Long = System.currentTimeMillis(),
+    val updatedAt: Long = System.currentTimeMillis(),
+    /** Tombstone – null means the item is alive. */
+    val deletedAt: Long? = null,
+    val hlcTs: Long = 0L,
+    /** UUID of the client that created this item. */
+    val clientId: String? = null,
+    val checkedAt: Long? = null,
+)

android/app/src/main/java/com/example/mitbringsl/data/local/entity/ListEntity.kt

@@ -0,0 +1,26 @@
+package com.example.mitbringsl.data.local.entity
+
+import androidx.room.Entity
+import androidx.room.Index
+import androidx.room.PrimaryKey
+import java.util.UUID
+
+/**
+ * Local projection of a shopping list.
+ * Written by the sync engine when ops arrive from the server.
+ * [ownerId] is the authenticated user's ID (UUID string).
+ */
+@Entity(
+    tableName = "lists",
+    indices = [Index("ownerId"), Index("deletedAt")]
+)
+data class ListEntity(
+    @PrimaryKey val id: String = UUID.randomUUID().toString(),
+    val name: String,
+    val ownerId: String,
+    val createdAt: Long = System.currentTimeMillis(),
+    val updatedAt: Long = System.currentTimeMillis(),
+    val deletedAt: Long? = null,
+    /** Hybrid Logical Clock timestamp – used for LWW conflict resolution. */
+    val hlcTs: Long = 0L,
+)

android/app/src/main/java/com/example/mitbringsl/data/local/entity/OpLogEntity.kt

@@ -0,0 +1,42 @@
+package com.example.mitbringsl.data.local.entity
+
+import androidx.room.Entity
+import androidx.room.Index
+import androidx.room.PrimaryKey
+
+/**
+ * Client-side op_log – the outbox for unsynced operations.
+ *
+ * Each row is a pending operation that has not yet been acknowledged by the
+ * server. The sync engine drains this table by pushing ops via
+ * POST /api/lists/{id}/ops and removes rows on success.
+ *
+ * [clientSeq] is a monotonically-increasing counter scoped to [clientId].
+ * Together they form the idempotency key used by the server.
+ */
+@Entity(
+    tableName = "op_log",
+    indices = [
+        Index("listId"),
+        Index(value = ["clientId", "clientSeq"], unique = true),
+        Index("synced"),
+    ]
+)
+data class OpLogEntity(
+    @PrimaryKey(autoGenerate = true) val localId: Long = 0,
+    val listId: String,
+    /** UUID of this device installation – stable, generated once. */
+    val clientId: String,
+    val clientSeq: Long,
+    /** One of: list_create, list_rename, list_delete, item_add, item_update, item_remove. */
+    val opType: String,
+    val targetId: String,
+    /** JSON payload, e.g. {"name":"Milch","quantity":"1L"}. */
+    val payload: String = "{}",
+    /** Client-generated HLC timestamp. */
+    val hlcTs: Long,
+    val createdAt: Long = System.currentTimeMillis(),
+    /** Set to the server-assigned seq once the op has been acknowledged. */
+    val serverSeq: Long? = null,
+    val synced: Boolean = false,
+)

android/app/src/main/java/com/example/mitbringsl/data/remote/api/AuthInterceptor.kt

@@ -0,0 +1,25 @@
+package com.example.mitbringsl.data.remote.api
+
+import okhttp3.Interceptor
+import okhttp3.Response
+
+/**
+ * OkHttp interceptor that injects the session Bearer token into every request.
+ *
+ * [tokenProvider] is a lambda so the interceptor always reads the most recent
+ * token without needing to be recreated after login.
+ */
+class AuthInterceptor(private val tokenProvider: () -> String?) : Interceptor {
+
+    override fun intercept(chain: Interceptor.Chain): Response {
+        val token = tokenProvider()
+        val request = if (token.isNullOrBlank()) {
+            chain.request()
+        } else {
+            chain.request().newBuilder()
+                .header("Authorization", "Bearer $token")
+                .build()
+        }
+        return chain.proceed(request)
+    }
+}

android/app/src/main/java/com/example/mitbringsl/data/remote/api/MitbringslApi.kt

@@ -0,0 +1,59 @@
+package com.example.mitbringsl.data.remote.api
+
+import com.example.mitbringsl.data.remote.dto.*
+import retrofit2.Response
+import retrofit2.http.*
+
+/**
+ * Retrofit API interface matching the mitbringsl backend.
+ *
+ * Authentication: every authenticated call must include
+ *   Authorization: Bearer <session-token>
+ * This is injected by the AuthInterceptor in the OkHttp client.
+ */
+interface MitbringslApi {
+
+    // --- Auth ---------------------------------------------------------------
+
+    @POST("auth/register")
+    suspend fun register(@Body body: RegisterRequestDto): Response<AuthResponseDto>
+
+    @POST("auth/login")
+    suspend fun login(@Body body: LoginRequestDto): Response<AuthResponseDto>
+
+    @POST("auth/oidc")
+    suspend fun loginOidc(@Body body: OidcRequestDto): Response<AuthResponseDto>
+
+    @POST("auth/logout")
+    suspend fun logout(): Response<Unit>
+
+    // --- Lists --------------------------------------------------------------
+
+    @GET("api/lists")
+    suspend fun getLists(): Response<ListsResponseDto>
+
+    @POST("api/lists")
+    suspend fun createList(@Body body: CreateListRequestDto): Response<ListDto>
+
+    @GET("api/lists/{id}")
+    suspend fun getList(@Path("id") listId: String): Response<ListDetailDto>
+
+    // --- Ops ----------------------------------------------------------------
+
+    @POST("api/lists/{id}/ops")
+    suspend fun pushOps(
+        @Path("id") listId: String,
+        @Body body: PushRequestDto,
+    ): Response<PushResponseDto>
+
+    @GET("api/lists/{id}/ops")
+    suspend fun pullOps(
+        @Path("id") listId: String,
+        @Query("since") since: Long,
+    ): Response<PullResponseDto>
+
+    // --- Suggestions --------------------------------------------------------
+
+    @GET("api/suggestions")
+    suspend fun getSuggestions(@Query("q") query: String): Response<SuggestionsResponseDto>
+}

android/app/src/main/java/com/example/mitbringsl/data/remote/dto/Dtos.kt

@@ -0,0 +1,138 @@
+package com.example.mitbringsl.data.remote.dto
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.JsonObject
+
+// ---------------------------------------------------------------------------
+// Auth
+// ---------------------------------------------------------------------------
+
+@Serializable
+data class RegisterRequestDto(
+    val email: String,
+    val password: String,
+    @SerialName("display_name") val displayName: String = "",
+)
+
+@Serializable
+data class LoginRequestDto(
+    val email: String,
+    val password: String,
+)
+
+@Serializable
+data class OidcRequestDto(
+    val provider: String,
+    @SerialName("id_token") val idToken: String,
+)
+
+@Serializable
+data class AuthResponseDto(
+    val token: String,
+    @SerialName("expires_at") val expiresAt: String,
+    val user: UserDto,
+)
+
+@Serializable
+data class UserDto(
+    val id: String,
+    val email: String,
+    @SerialName("display_name") val displayName: String = "",
+)
+
+// ---------------------------------------------------------------------------
+// Lists
+// ---------------------------------------------------------------------------
+
+@Serializable
+data class CreateListRequestDto(val name: String)
+
+@Serializable
+data class ListDto(
+    val id: String,
+    val name: String,
+    @SerialName("updated_at") val updatedAt: String,
+    @SerialName("hlc_ts") val hlcTs: Long,
+)
+
+@Serializable
+data class ListsResponseDto(val lists: List<ListDto>)
+
+@Serializable
+data class ListDetailDto(
+    val id: String,
+    val name: String,
+    @SerialName("updated_at") val updatedAt: String,
+    @SerialName("hlc_ts") val hlcTs: Long,
+    val items: List<ItemDto>,
+)
+
+@Serializable
+data class ItemDto(
+    val id: String,
+    @SerialName("list_id") val listId: String,
+    val name: String,
+    val quantity: String? = null,
+    val checked: Boolean = false,
+    @SerialName("sort_order") val sortOrder: Int? = null,
+    @SerialName("created_at") val createdAt: String,
+    @SerialName("updated_at") val updatedAt: String,
+    @SerialName("hlc_ts") val hlcTs: Long,
+    @SerialName("client_id") val clientId: String? = null,
+    @SerialName("checked_at") val checkedAt: String? = null,
+)
+
+// ---------------------------------------------------------------------------
+// Ops (Push / Pull)
+// ---------------------------------------------------------------------------
+
+@Serializable
+data class PushRequestDto(
+    @SerialName("client_id") val clientId: String,
+    val ops: List<IncomingOpDto>,
+)
+
+@Serializable
+data class IncomingOpDto(
+    @SerialName("client_seq") val clientSeq: Long,
+    @SerialName("op_type") val opType: String,
+    @SerialName("target_id") val targetId: String,
+    @SerialName("hlc_ts") val hlcTs: Long,
+    val payload: JsonObject,
+)
+
+@Serializable
+data class PushResponseDto(val results: List<OpResultDto>)
+
+@Serializable
+data class OpResultDto(
+    @SerialName("client_seq") val clientSeq: Long,
+    val seq: Long,
+    @SerialName("hlc_ts") val hlcTs: Long,
+)
+
+@Serializable
+data class PullResponseDto(
+    val ops: List<ServerOpDto>,
+    @SerialName("has_more") val hasMore: Boolean,
+)
+
+@Serializable
+data class ServerOpDto(
+    val seq: Long,
+    @SerialName("client_id") val clientId: String,
+    @SerialName("op_type") val opType: String,
+    @SerialName("target_id") val targetId: String,
+    val payload: JsonObject,
+    @SerialName("client_seq") val clientSeq: Long,
+    @SerialName("hlc_ts") val hlcTs: Long,
+    @SerialName("created_at") val createdAt: String,
+)
+
+// ---------------------------------------------------------------------------
+// Suggestions
+// ---------------------------------------------------------------------------
+
+@Serializable
+data class SuggestionsResponseDto(val suggestions: List<String>)

android/app/src/main/java/com/example/mitbringsl/di/DatabaseModule.kt

@@ -0,0 +1,30 @@
+package com.example.mitbringsl.di
+
+import android.content.Context
+import androidx.room.Room
+import com.example.mitbringsl.data.local.AppDatabase
+import com.example.mitbringsl.data.local.dao.ItemDao
+import com.example.mitbringsl.data.local.dao.ListDao
+import com.example.mitbringsl.data.local.dao.OpLogDao
+import dagger.Module
+import dagger.Provides
+import dagger.hilt.InstallIn
+import dagger.hilt.android.qualifiers.ApplicationContext
+import dagger.hilt.components.SingletonComponent
+import javax.inject.Singleton
+
+@Module
+@InstallIn(SingletonComponent::class)
+object DatabaseModule {
+
+    @Provides
+    @Singleton
+    fun provideDatabase(@ApplicationContext context: Context): AppDatabase =
+        Room.databaseBuilder(context, AppDatabase::class.java, AppDatabase.DATABASE_NAME)
+            .fallbackToDestructiveMigration(dropAllTables = false)
+            .build()
+
+    @Provides fun provideListDao(db: AppDatabase): ListDao = db.listDao()
+    @Provides fun provideItemDao(db: AppDatabase): ItemDao = db.itemDao()
+    @Provides fun provideOpLogDao(db: AppDatabase): OpLogDao = db.opLogDao()
+}

android/app/src/main/java/com/example/mitbringsl/di/NetworkModule.kt

@@ -0,0 +1,73 @@
+package com.example.mitbringsl.di
+
+import android.content.Context
+import com.example.mitbringsl.BuildConfig
+import com.example.mitbringsl.data.remote.api.AuthInterceptor
+import com.example.mitbringsl.data.remote.api.MitbringslApi
+import dagger.Module
+import dagger.Provides
+import dagger.hilt.InstallIn
+import dagger.hilt.android.qualifiers.ApplicationContext
+import dagger.hilt.components.SingletonComponent
+import kotlinx.serialization.json.Json
+import okhttp3.MediaType.Companion.toMediaType
+import okhttp3.OkHttpClient
+import okhttp3.logging.HttpLoggingInterceptor
+import retrofit2.Retrofit
+import retrofit2.converter.kotlinx.serialization.asConverterFactory
+import javax.inject.Singleton
+
+@Module
+@InstallIn(SingletonComponent::class)
+object NetworkModule {
+
+    /**
+     * Lax JSON decoder: ignores unknown keys so the app doesn't crash when the
+     * backend adds new fields, and handles missing optional fields gracefully.
+     */
+    @Provides
+    @Singleton
+    fun provideJson(): Json = Json {
+        ignoreUnknownKeys = true
+        isLenient = true
+        coerceInputValues = true
+    }
+
+    @Provides
+    @Singleton
+    fun provideTokenProvider(@ApplicationContext context: Context): () -> String? = {
+        // Read token from SharedPreferences (written after login).
+        context.getSharedPreferences("session", Context.MODE_PRIVATE)
+            .getString("token", null)
+    }
+
+    @Provides
+    @Singleton
+    fun provideOkHttpClient(tokenProvider: () -> String?): OkHttpClient {
+        val logging = HttpLoggingInterceptor().apply {
+            level = if (BuildConfig.DEBUG) {
+                HttpLoggingInterceptor.Level.BODY
+            } else {
+                HttpLoggingInterceptor.Level.NONE
+            }
+        }
+        return OkHttpClient.Builder()
+            .addInterceptor(AuthInterceptor(tokenProvider))
+            .addInterceptor(logging)
+            .build()
+    }
+
+    @Provides
+    @Singleton
+    fun provideRetrofit(client: OkHttpClient, json: Json): Retrofit =
+        Retrofit.Builder()
+            .baseUrl(BuildConfig.BASE_URL)
+            .client(client)
+            .addConverterFactory(json.asConverterFactory("application/json; charset=UTF-8".toMediaType()))
+            .build()
+
+    @Provides
+    @Singleton
+    fun provideMitbringslApi(retrofit: Retrofit): MitbringslApi =
+        retrofit.create(MitbringslApi::class.java)
+}

android/app/src/main/java/com/example/mitbringsl/di/RepositoryModule.kt

@@ -0,0 +1,18 @@
+package com.example.mitbringsl.di
+
+import com.example.mitbringsl.data.DefaultListRepository
+import com.example.mitbringsl.data.ListRepository
+import dagger.Binds
+import dagger.Module
+import dagger.hilt.InstallIn
+import dagger.hilt.components.SingletonComponent
+import javax.inject.Singleton
+
+@Module
+@InstallIn(SingletonComponent::class)
+abstract class RepositoryModule {
+
+    @Binds
+    @Singleton
+    abstract fun bindListRepository(impl: DefaultListRepository): ListRepository
+}

android/app/src/main/java/com/example/mitbringsl/theme/Color.kt

@@ -0,0 +1,11 @@
+package com.example.mitbringsl.theme
+
+import androidx.compose.ui.graphics.Color
+
+val Purple80 = Color(0xFFD0BCFF)
+val PurpleGrey80 = Color(0xFFCCC2DC)
+val Pink80 = Color(0xFFEFB8C8)
+
+val Purple40 = Color(0xFF6650a4)
+val PurpleGrey40 = Color(0xFF625b71)
+val Pink40 = Color(0xFF7D5260)

android/app/src/main/java/com/example/mitbringsl/theme/Theme.kt

@@ -0,0 +1,50 @@
+package com.example.mitbringsl.theme
+
+import android.os.Build
+import androidx.compose.foundation.isSystemInDarkTheme
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.darkColorScheme
+import androidx.compose.material3.dynamicDarkColorScheme
+import androidx.compose.material3.dynamicLightColorScheme
+import androidx.compose.material3.lightColorScheme
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.platform.LocalContext
+
+private val DarkColorScheme = darkColorScheme(primary = Purple80, secondary = PurpleGrey80, tertiary = Pink80)
+
+private val LightColorScheme =
+  lightColorScheme(
+    primary = Purple40,
+    secondary = PurpleGrey40,
+    tertiary = Pink40,
+
+    /* Other default colors to override
+    background = Color(0xFFFFFBFE),
+    surface = Color(0xFFFFFBFE),
+    onPrimary = Color.White,
+    onSecondary = Color.White,
+    onTertiary = Color.White,
+    onBackground = Color(0xFF1C1B1F),
+    onSurface = Color(0xFF1C1B1F),
+    */
+  )
+
+@Composable
+fun MitbringslTheme(
+  darkTheme: Boolean = isSystemInDarkTheme(),
+  // Dynamic color is available on Android 12+
+  dynamicColor: Boolean = true,
+  content: @Composable () -> Unit,
+) {
+  val colorScheme =
+    when {
+      dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
+        val context = LocalContext.current
+        if (darkTheme) dynamicDarkColorScheme(context) else dynamicLightColorScheme(context)
+      }
+      darkTheme -> DarkColorScheme
+      else -> LightColorScheme
+    }
+
+  MaterialTheme(colorScheme = colorScheme, typography = Typography, content = content)
+}

android/app/src/main/java/com/example/mitbringsl/theme/Type.kt

@@ -0,0 +1,36 @@
+package com.example.mitbringsl.theme
+
+import androidx.compose.material3.Typography
+import androidx.compose.ui.text.TextStyle
+import androidx.compose.ui.text.font.FontFamily
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.sp
+
+// Set of Material typography styles to start with
+val Typography =
+  Typography(
+    bodyLarge =
+      TextStyle(
+        fontFamily = FontFamily.Default,
+        fontWeight = FontWeight.Normal,
+        fontSize = 16.sp,
+        lineHeight = 24.sp,
+        letterSpacing = 0.5.sp,
+      )
+    /* Other default text styles to override
+    titleLarge = TextStyle(
+        fontFamily = FontFamily.Default,
+        fontWeight = FontWeight.Normal,
+        fontSize = 22.sp,
+        lineHeight = 28.sp,
+        letterSpacing = 0.sp
+    ),
+    labelSmall = TextStyle(
+        fontFamily = FontFamily.Default,
+        fontWeight = FontWeight.Medium,
+        fontSize = 11.sp,
+        lineHeight = 16.sp,
+        letterSpacing = 0.5.sp
+    )
+    */
+  )

android/app/src/main/java/com/example/mitbringsl/ui/main/MainScreen.kt

@@ -0,0 +1,35 @@
+package com.example.mitbringsl.ui.main
+
+import androidx.compose.foundation.layout.Column
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.tooling.preview.Preview
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.navigation3.runtime.NavKey
+import com.example.mitbringsl.theme.MitbringslTheme
+
+@Composable
+fun MainScreen(
+  onItemClick: (NavKey) -> Unit,
+  modifier: Modifier = Modifier,
+  viewModel: MainScreenViewModel = hiltViewModel(),
+) {
+  MainScreen(data = listOf("Mitbringsl App Initialized"), modifier = modifier)
+}
+
+@Composable
+internal fun MainScreen(data: List<String>, modifier: Modifier = Modifier) {
+  Column(modifier) { data.forEach { Greeting(it) } }
+}
+
+@Composable
+fun Greeting(name: String, modifier: Modifier = Modifier) {
+  Text(text = "$name", modifier = modifier)
+}
+
+@Preview(showBackground = true)
+@Composable
+fun MainScreenPreview() {
+  MitbringslTheme { MainScreen(listOf("Mitbringsl App Initialized")) }
+}

android/app/src/main/java/com/example/mitbringsl/ui/main/MainScreenViewModel.kt

@@ -0,0 +1,18 @@
+package com.example.mitbringsl.ui.main
+
+import androidx.lifecycle.ViewModel
+import dagger.hilt.android.lifecycle.HiltViewModel
+import javax.inject.Inject
+
+/**
+ * Placeholder ViewModel for the main screen.
+ * Will be replaced in Phase E with the full ListsViewModel backed by Room.
+ */
+@HiltViewModel
+class MainScreenViewModel @Inject constructor() : ViewModel()
+
+sealed interface MainScreenUiState {
+    object Loading : MainScreenUiState
+    data class Error(val throwable: Throwable) : MainScreenUiState
+    data class Success(val data: List<String>) : MainScreenUiState
+}

android/app/src/main/res/drawable/ic_launcher_background.xml

@@ -0,0 +1,170 @@
+<?xml version="1.0" encoding="utf-8"?>
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="108dp"
+    android:height="108dp"
+    android:viewportWidth="108"
+    android:viewportHeight="108">
+    <path
+        android:fillColor="#3DDC84"
+        android:pathData="M0,0h108v108h-108z" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M9,0L9,108"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M19,0L19,108"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M29,0L29,108"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M39,0L39,108"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M49,0L49,108"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M59,0L59,108"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M69,0L69,108"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M79,0L79,108"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M89,0L89,108"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M99,0L99,108"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,9L108,9"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,19L108,19"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,29L108,29"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,39L108,39"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,49L108,49"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,59L108,59"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,69L108,69"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,79L108,79"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,89L108,89"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,99L108,99"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M19,29L89,29"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M19,39L89,39"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M19,49L89,49"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M19,59L89,59"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M19,69L89,69"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M19,79L89,79"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M29,19L29,89"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M39,19L39,89"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M49,19L49,89"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M59,19L59,89"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M69,19L69,89"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M79,19L79,89"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+</vector>

android/app/src/main/res/drawable/ic_launcher_foreground.xml

@@ -0,0 +1,30 @@
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:aapt="http://schemas.android.com/aapt"
+    android:width="108dp"
+    android:height="108dp"
+    android:viewportWidth="108"
+    android:viewportHeight="108">
+    <path android:pathData="M31,63.928c0,0 6.4,-11 12.1,-13.1c7.2,-2.6 26,-1.4 26,-1.4l38.1,38.1L107,108.928l-32,-1L31,63.928z">
+        <aapt:attr name="android:fillColor">
+            <gradient
+                android:endX="85.84757"
+                android:endY="92.4963"
+                android:startX="42.9492"
+                android:startY="49.59793"
+                android:type="linear">
+                <item
+                    android:color="#44000000"
+                    android:offset="0.0" />
+                <item
+                    android:color="#00000000"
+                    android:offset="1.0" />
+            </gradient>
+        </aapt:attr>
+    </path>
+    <path
+        android:fillColor="#FFFFFF"
+        android:fillType="nonZero"
+        android:pathData="M65.3,45.828l3.8,-6.6c0.2,-0.4 0.1,-0.9 -0.3,-1.1c-0.4,-0.2 -0.9,-0.1 -1.1,0.3l-3.9,6.7c-6.3,-2.8 -13.4,-2.8 -19.7,0l-3.9,-6.7c-0.2,-0.4 -0.7,-0.5 -1.1,-0.3C38.8,38.328 38.7,38.828 38.9,39.228l3.8,6.6C36.2,49.428 31.7,56.028 31,63.928h46C76.3,56.028 71.8,49.428 65.3,45.828zM43.4,57.328c-0.8,0 -1.5,-0.5 -1.8,-1.2c-0.3,-0.7 -0.1,-1.5 0.4,-2.1c0.5,-0.5 1.4,-0.7 2.1,-0.4c0.7,0.3 1.2,1 1.2,1.8C45.3,56.528 44.5,57.328 43.4,57.328L43.4,57.328zM64.6,57.328c-0.8,0 -1.5,-0.5 -1.8,-1.2s-0.1,-1.5 0.4,-2.1c0.5,-0.5 1.4,-0.7 2.1,-0.4c0.7,0.3 1.2,1 1.2,1.8C66.5,56.528 65.6,57.328 64.6,57.328L64.6,57.328z"
+        android:strokeWidth="1"
+        android:strokeColor="#00000000" />
+</vector>

android/app/src/main/res/mipmap-anydpi-v26/ic_launcher.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+    <background android:drawable="@drawable/ic_launcher_background" />
+    <foreground android:drawable="@drawable/ic_launcher_foreground" />
+    <monochrome android:drawable="@drawable/ic_launcher_foreground" />
+</adaptive-icon>

android/app/src/main/res/mipmap-anydpi-v26/ic_launcher_round.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+    <background android:drawable="@drawable/ic_launcher_background" />
+    <foreground android:drawable="@drawable/ic_launcher_foreground" />
+    <monochrome android:drawable="@drawable/ic_launcher_foreground" />
+</adaptive-icon>

android/app/src/main/res/values/strings.xml

@@ -0,0 +1,3 @@
+<resources>
+    <string name="app_name">Mitbringsl</string>
+</resources>

android/app/src/main/res/values/themes.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+
+    <style name="Theme.Mitbringsl" parent="android:Theme.Material.Light.NoActionBar" />
+</resources>

android/app/src/main/res/xml/backup_rules.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="utf-8"?><!--
+   Sample backup rules file; uncomment and customize as necessary.
+   See https://developer.android.com/guide/topics/data/autobackup
+   for details.
+   Note: This file is ignored for devices older than API 31
+   See https://developer.android.com/about/versions/12/backup-restore
+-->
+<full-backup-content>
+    <!--
+   <include domain="sharedpref" path="."/>
+   <exclude domain="sharedpref" path="device.xml"/>
+-->
+</full-backup-content>

android/app/src/main/res/xml/data_extraction_rules.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="utf-8"?><!--
+   Sample data extraction rules file; uncomment and customize as necessary.
+   See https://developer.android.com/about/versions/12/backup-restore#xml-changes
+   for details.
+-->
+<data-extraction-rules>
+    <cloud-backup>
+        <!-- TODO: Use <include> and <exclude> to control what is backed up.
+        <include .../>
+        <exclude .../>
+        -->
+    </cloud-backup>
+    <!--
+    <device-transfer>
+        <include .../>
+        <exclude .../>
+    </device-transfer>
+    -->
+</data-extraction-rules>

android/app/src/test/java/com/example/mitbringsl/ui/main/MainScreenViewModelTest.kt

@@ -0,0 +1,12 @@
+package com.example.mitbringsl.ui.main
+
+import junit.framework.TestCase.assertNotNull
+import org.junit.Test
+
+class MainScreenViewModelTest {
+  @Test
+  fun viewModel_canBeConstructed() {
+    val viewModel = MainScreenViewModel()
+    assertNotNull(viewModel)
+  }
+}