Merge pull request 'feat(android): Phase 1 MVP app — Compose UI, Room, sync' (#2) from feature/android-frontend into main

Reviewed-on: #2

.env.example

@@ -0,0 +1,21 @@
+# Server
+NODE_ENV=development
+PORT=3000
+
+# Database
+DATABASE_URL=postgresql://user:password@localhost:5432/pantree
+
+# JWT
+JWT_SECRET=change_this_to_a_long_random_secret_at_least_64_chars
+JWT_EXPIRES_IN=24h
+
+# Google OAuth
+GOOGLE_CLIENT_ID=your_google_client_id_here
+
+# SendGrid
+SENDGRID_API_KEY=your_sendgrid_api_key_here
+SENDGRID_FROM_EMAIL=noreply@pantree.app
+
+# App
+FRONTEND_URL=https://pantree.app
+PASSWORD_RESET_URL=https://pantree.app/reset-password

.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+.env
+*.log
+coverage/
+.DS_Store

android/README.md

@@ -0,0 +1,76 @@
+# Pantree Android
+
+Android client for Pantree — the app that tells you what you can cook with what you already have.
+
+## Architecture
+
+- **MVVM** — ViewModel + StateFlow, no LiveData
+- **Hilt** — dependency injection
+- **Room** — local cache (pantry items, recipes, shopping lists)
+- **Retrofit + OkHttp** — network layer with JWT interceptor
+- **Jetpack Compose** — declarative UI, Material 3
+- **EncryptedSharedPreferences** — JWT stored at rest
+- **DataStore** — last-sync timestamp
+
+## Module Structure
+
+```
+app/src/main/java/com/pantree/app/
+├── data/
+│   ├── local/          # Room DB, DAOs, entities, TokenStore, SyncPreferences
+│   ├── model/          # API DTOs (request/response)
+│   ├── remote/         # ApiService (Retrofit), AuthInterceptor
+│   └── repository/     # AuthRepository, PantryRepository, RecipeRepository,
+│                       # ShoppingListRepository, SyncRepository
+├── di/                 # Hilt AppModule
+├── sync/               # SyncManager (lifecycle observer)
+├── ui/
+│   ├── components/     # LoadingState, ErrorState, EmptyState, OfflineBanner, PantreeTopBar
+│   ├── navigation/     # Screen sealed class, PantreeNavGraph
+│   ├── screens/
+│   │   ├── auth/       # SplashScreen, SignInScreen, SignUpScreen,
+│   │   │               # ForgotPasswordScreen, ResetPasswordScreen + AuthViewModel
+│   │   ├── pantry/     # PantryScreen + PantryViewModel
+│   │   ├── recipe/     # RecipesScreen, RecipeDetailScreen + RecipeViewModel
+│   │   ├── shopping/   # ShoppingListsScreen, ShoppingListDetailScreen + ShoppingListViewModel
+│   │   └── settings/   # SettingsScreen + SettingsViewModel
+│   └── theme/          # Color, Type, Theme
+└── util/               # Result<T>, safeApiCall, toUserMessage
+```
+
+## UI States
+
+Every screen handles all four states:
+
+| State | Implementation |
+|-------|---------------|
+| **Loading** | `LoadingState` composable — spinner + contextual message |
+| **Error** | `ErrorState` composable — emoji + message + retry button |
+| **Empty** | `EmptyState` composable — emoji + title + subtitle + optional CTA |
+| **Success** | Full content with `LazyColumn` / detail view |
+
+Offline: cached data shown read-only, `OfflineBanner` displayed.
+
+## Sync Strategy
+
+- `SyncManager` implements `DefaultLifecycleObserver` — triggers on `onStart` (app open + foreground)
+- Delta sync via `GET /sync?since=<last_timestamp>`
+- Server timestamp stored in DataStore, used as `since` on next sync
+- Room cache updated; UI observes `Flow<List<Entity>>` — updates automatically
+
+## Setup
+
+1. Set `BASE_URL` in `app/build.gradle` debug/release buildConfigFields
+2. Set `GOOGLE_WEB_CLIENT_ID` for Google Sign-In
+3. Run backend (`npm run dev` from repo root)
+4. `./gradlew assembleDebug`
+
+## Running Tests
+
+```bash
+# Unit tests
+./gradlew test
+
+# Instrumented tests (requires emulator/device)
+./gradlew connectedAndroidTest
+```

android/app/build.gradle

@@ -0,0 +1,128 @@
+plugins {
+    id 'com.android.application'
+    id 'org.jetbrains.kotlin.android'
+    id 'com.google.dagger.hilt.android'
+    id 'com.google.devtools.ksp'
+}
+
+android {
+    namespace 'com.pantree.app'
+    compileSdk 34
+
+    defaultConfig {
+        applicationId "com.pantree.app"
+        minSdk 26
+        targetSdk 34
+        versionCode 1
+        versionName "1.0.0"
+
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+        vectorDrawables {
+            useSupportLibrary true
+        }
+
+        buildConfigField "String", "BASE_URL", '"https://api.pantree.app/v1/"'
+        buildConfigField "String", "GOOGLE_WEB_CLIENT_ID", '"YOUR_GOOGLE_WEB_CLIENT_ID"'
+    }
+
+    buildTypes {
+        release {
+            minifyEnabled true
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+        }
+        debug {
+            buildConfigField "String", "BASE_URL", '"http://10.0.2.2:3000/v1/"'
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = '17'
+    }
+
+    buildFeatures {
+        compose true
+        buildConfig true
+    }
+
+    composeOptions {
+        kotlinCompilerExtensionVersion '1.5.11'
+    }
+
+    packaging {
+        resources {
+            excludes += '/META-INF/{AL2.0,LGPL2.1}'
+        }
+    }
+}
+
+dependencies {
+    // Core
+    implementation 'androidx.core:core-ktx:1.13.0'
+    implementation 'androidx.lifecycle:lifecycle-runtime-ktx:2.7.0'
+    implementation 'androidx.activity:activity-compose:1.9.0'
+
+    // Compose BOM
+    implementation platform('androidx.compose:compose-bom:2024.04.01')
+    implementation 'androidx.compose.ui:ui'
+    implementation 'androidx.compose.ui:ui-graphics'
+    implementation 'androidx.compose.ui:ui-tooling-preview'
+    implementation 'androidx.compose.material3:material3'
+    implementation 'androidx.compose.material:material-icons-extended'
+
+    // Navigation
+    implementation 'androidx.navigation:navigation-compose:2.7.7'
+
+    // Hilt DI
+    implementation 'com.google.dagger:hilt-android:2.51.1'
+    ksp 'com.google.dagger:hilt-android-compiler:2.51.1'
+    implementation 'androidx.hilt:hilt-navigation-compose:1.2.0'
+
+    // Room
+    implementation 'androidx.room:room-runtime:2.6.1'
+    implementation 'androidx.room:room-ktx:2.6.1'
+    ksp 'androidx.room:room-compiler:2.6.1'
+
+    // Retrofit + OkHttp
+    implementation 'com.squareup.retrofit2:retrofit:2.11.0'
+    implementation 'com.squareup.retrofit2:converter-gson:2.11.0'
+    implementation 'com.squareup.okhttp3:okhttp:4.12.0'
+    implementation 'com.squareup.okhttp3:logging-interceptor:4.12.0'
+
+    // Gson
+    implementation 'com.google.code.gson:gson:2.10.1'
+
+    // ViewModel + StateFlow
+    implementation 'androidx.lifecycle:lifecycle-viewmodel-compose:2.7.0'
+    implementation 'androidx.lifecycle:lifecycle-runtime-compose:2.7.0'
+
+    // EncryptedSharedPreferences
+    implementation 'androidx.security:security-crypto:1.1.0-alpha06'
+
+    // Google Identity (One Tap)
+    implementation 'com.google.android.gms:play-services-auth:21.1.1'
+
+    // Coil (image loading)
+    implementation 'io.coil-kt:coil-compose:2.6.0'
+
+    // DataStore
+    implementation 'androidx.datastore:datastore-preferences:1.1.0'
+
+    // Coroutines
+    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.0'
+
+    // Testing
+    testImplementation 'junit:junit:4.13.2'
+    testImplementation 'org.jetbrains.kotlinx:kotlinx-coroutines-test:1.8.0'
+    testImplementation 'io.mockk:mockk:1.13.10'
+    androidTestImplementation 'androidx.test.ext:junit:1.1.5'
+    androidTestImplementation 'androidx.test.espresso:espresso-core:3.5.1'
+    androidTestImplementation platform('androidx.compose:compose-bom:2024.04.01')
+    androidTestImplementation 'androidx.compose.ui:ui-test-junit4'
+    debugImplementation 'androidx.compose.ui:ui-tooling'
+    debugImplementation 'androidx.compose.ui:ui-test-manifest'
+}

android/app/src/androidTest/java/com/pantree/app/ui/screens/pantry/PantryScreenTest.kt

@@ -0,0 +1,43 @@
+package com.pantree.app.ui.screens.pantry
+
+import androidx.compose.ui.test.*
+import androidx.compose.ui.test.junit4.createComposeRule
+import com.pantree.app.data.local.entity.PantryItemEntity
+import com.pantree.app.ui.theme.PantreeTheme
+import org.junit.Rule
+import org.junit.Test
+
+class PantryScreenTest {
+
+    @get:Rule
+    val composeTestRule = createComposeRule()
+
+    @Test
+    fun emptyState_showsEmptyMessage() {
+        composeTestRule.setContent {
+            PantreeTheme {
+                EmptyState(
+                    emoji = "\uD83E\uDED9",
+                    title = "Your pantry is empty",
+                    subtitle = "Add ingredients you have on hand."
+                )
+            }
+        }
+        composeTestRule.onNodeWithText("Your pantry is empty").assertIsDisplayed()
+    }
+
+    @Test
+    fun pantryItemCard_displaysNameAndQuantity() {
+        val item = PantryItemEntity(
+            id = "1", itemName = "Flour", quantity = 3,
+            lastModified = "2024-01-01T00:00:00Z", createdAt = "2024-01-01T00:00:00Z"
+        )
+        composeTestRule.setContent {
+            PantreeTheme {
+                PantryItemCard(item = item, onEdit = {}, onDelete = {})
+            }
+        }
+        composeTestRule.onNodeWithText("Flour").assertIsDisplayed()
+        composeTestRule.onNodeWithText("Qty: 3").assertIsDisplayed()
+    }
+}

android/app/src/main/AndroidManifest.xml

@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+
+    <application
+        android:name=".PantreeApplication"
+        android:allowBackup="true"
+        android:icon="@mipmap/ic_launcher"
+        android:label="@string/app_name"
+        android:roundIcon="@mipmap/ic_launcher_round"
+        android:supportsRtl="true"
+        android:theme="@style/Theme.Pantree"
+        android:usesCleartextTraffic="false">
+
+        <activity
+            android:name=".MainActivity"
+            android:exported="true"
+            android:theme="@style/Theme.Pantree">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+
+            <!-- Deep link for password reset -->
+            <intent-filter android:autoVerify="true">
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data
+                    android:scheme="https"
+                    android:host="pantree.app"
+                    android:pathPrefix="/reset-password" />
+            </intent-filter>
+        </activity>
+    </application>
+
+</manifest>

android/app/src/main/java/com/pantree/app/MainActivity.kt

@@ -0,0 +1,27 @@
+package com.pantree.app
+
+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.Surface
+import androidx.compose.ui.Modifier
+import com.pantree.app.ui.navigation.PantreeNavGraph
+import com.pantree.app.ui.theme.PantreeTheme
+import dagger.hilt.android.AndroidEntryPoint
+
+@AndroidEntryPoint
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        enableEdgeToEdge()
+        setContent {
+            PantreeTheme {
+                Surface(modifier = Modifier.fillMaxSize()) {
+                    PantreeNavGraph()
+                }
+            }
+        }
+    }
+}

android/app/src/main/java/com/pantree/app/PantreeApplication.kt

@@ -0,0 +1,7 @@
+package com.pantree.app
+
+import android.app.Application
+import dagger.hilt.android.HiltAndroidApp
+
+@HiltAndroidApp
+class PantreeApplication : Application()

android/app/src/main/java/com/pantree/app/data/local/PantreeDatabase.kt

@@ -0,0 +1,29 @@
+package com.pantree.app.data.local
+
+import androidx.room.Database
+import androidx.room.RoomDatabase
+import com.pantree.app.data.local.dao.PantryDao
+import com.pantree.app.data.local.dao.RecipeDao
+import com.pantree.app.data.local.dao.ShoppingListDao
+import com.pantree.app.data.local.entity.PantryItemEntity
+import com.pantree.app.data.local.entity.RecipeEntity
+import com.pantree.app.data.local.entity.RecipeIngredientEntity
+import com.pantree.app.data.local.entity.ShoppingListEntity
+import com.pantree.app.data.local.entity.ShoppingListItemEntity
+
+@Database(
+    entities = [
+        PantryItemEntity::class,
+        RecipeEntity::class,
+        RecipeIngredientEntity::class,
+        ShoppingListEntity::class,
+        ShoppingListItemEntity::class
+    ],
+    version = 1,
+    exportSchema = false
+)
+abstract class PantreeDatabase : RoomDatabase() {
+    abstract fun pantryDao(): PantryDao
+    abstract fun recipeDao(): RecipeDao
+    abstract fun shoppingListDao(): ShoppingListDao
+}

android/app/src/main/java/com/pantree/app/data/local/SyncPreferences.kt

@@ -0,0 +1,32 @@
+package com.pantree.app.data.local
+
+import android.content.Context
+import androidx.datastore.core.DataStore
+import androidx.datastore.preferences.core.Preferences
+import androidx.datastore.preferences.core.edit
+import androidx.datastore.preferences.core.stringPreferencesKey
+import androidx.datastore.preferences.preferencesDataStore
+import dagger.hilt.android.qualifiers.ApplicationContext
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.map
+import javax.inject.Inject
+import javax.inject.Singleton
+
+val Context.dataStore: DataStore<Preferences> by preferencesDataStore(name = "sync_prefs")
+
+@Singleton
+class SyncPreferences @Inject constructor(
+    @ApplicationContext private val context: Context
+) {
+    private val LAST_SYNC_KEY = stringPreferencesKey("last_sync_timestamp")
+
+    val lastSyncTimestamp: Flow<String> = context.dataStore.data.map { prefs ->
+        prefs[LAST_SYNC_KEY] ?: "1970-01-01T00:00:00.000Z"
+    }
+
+    suspend fun updateLastSync(timestamp: String) {
+        context.dataStore.edit { prefs ->
+            prefs[LAST_SYNC_KEY] = timestamp
+        }
+    }
+}

android/app/src/main/java/com/pantree/app/data/local/TokenStore.kt

@@ -0,0 +1,50 @@
+package com.pantree.app.data.local
+
+import android.content.Context
+import androidx.security.crypto.EncryptedSharedPreferences
+import androidx.security.crypto.MasterKey
+import dagger.hilt.android.qualifiers.ApplicationContext
+import javax.inject.Inject
+import javax.inject.Singleton
+
+@Singleton
+class TokenStore @Inject constructor(
+    @ApplicationContext private val context: Context
+) {
+    private val masterKey = MasterKey.Builder(context)
+        .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
+        .build()
+
+    private val prefs = EncryptedSharedPreferences.create(
+        context,
+        "pantree_secure_prefs",
+        masterKey,
+        EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
+        EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
+    )
+
+    fun saveToken(token: String, expiresAt: String) {
+        prefs.edit()
+            .putString(KEY_TOKEN, token)
+            .putString(KEY_EXPIRES_AT, expiresAt)
+            .apply()
+    }
+
+    fun getToken(): String? = prefs.getString(KEY_TOKEN, null)
+
+    fun getExpiresAt(): String? = prefs.getString(KEY_EXPIRES_AT, null)
+
+    fun clearToken() {
+        prefs.edit()
+            .remove(KEY_TOKEN)
+            .remove(KEY_EXPIRES_AT)
+            .apply()
+    }
+
+    fun isLoggedIn(): Boolean = getToken() != null
+
+    companion object {
+        private const val KEY_TOKEN = "jwt_token"
+        private const val KEY_EXPIRES_AT = "jwt_expires_at"
+    }
+}

android/app/src/main/java/com/pantree/app/data/local/dao/PantryDao.kt

@@ -0,0 +1,29 @@
+package com.pantree.app.data.local.dao
+
+import androidx.room.*
+import com.pantree.app.data.local.entity.PantryItemEntity
+import kotlinx.coroutines.flow.Flow
+
+@Dao
+interface PantryDao {
+    @Query("SELECT * FROM pantry_items ORDER BY item_name ASC")
+    fun getAllItems(): Flow<List<PantryItemEntity>>
+
+    @Query("SELECT * FROM pantry_items WHERE id = :id")
+    suspend fun getItemById(id: String): PantryItemEntity?
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun insertItem(item: PantryItemEntity)
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun insertItems(items: List<PantryItemEntity>)
+
+    @Update
+    suspend fun updateItem(item: PantryItemEntity)
+
+    @Query("DELETE FROM pantry_items WHERE id = :id")
+    suspend fun deleteItemById(id: String)
+
+    @Query("DELETE FROM pantry_items")
+    suspend fun deleteAll()
+}

android/app/src/main/java/com/pantree/app/data/local/dao/RecipeDao.kt

@@ -0,0 +1,30 @@
+package com.pantree.app.data.local.dao
+
+import androidx.room.*
+import com.pantree.app.data.local.entity.RecipeEntity
+import com.pantree.app.data.local.entity.RecipeIngredientEntity
+import kotlinx.coroutines.flow.Flow
+
+@Dao
+interface RecipeDao {
+    @Query("SELECT * FROM recipes ORDER BY name ASC")
+    fun getAllRecipes(): Flow<List<RecipeEntity>>
+
+    @Query("SELECT * FROM recipes WHERE can_make = 1 ORDER BY name ASC")
+    fun getCanMakeRecipes(): Flow<List<RecipeEntity>>
+
+    @Query("SELECT * FROM recipes WHERE can_make = 0 AND available_ingredient_count > 0 ORDER BY availability_percentage DESC")
+    fun getPartialRecipes(): Flow<List<RecipeEntity>>
+
+    @Query("SELECT * FROM recipe_ingredients WHERE recipe_id = :recipeId")
+    suspend fun getIngredientsForRecipe(recipeId: String): List<RecipeIngredientEntity>
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun insertRecipes(recipes: List<RecipeEntity>)
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun insertIngredients(ingredients: List<RecipeIngredientEntity>)
+
+    @Query("DELETE FROM recipes")
+    suspend fun deleteAll()
+}

android/app/src/main/java/com/pantree/app/data/local/dao/ShoppingListDao.kt

@@ -0,0 +1,39 @@
+package com.pantree.app.data.local.dao
+
+import androidx.room.*
+import com.pantree.app.data.local.entity.ShoppingListEntity
+import com.pantree.app.data.local.entity.ShoppingListItemEntity
+import kotlinx.coroutines.flow.Flow
+
+@Dao
+interface ShoppingListDao {
+    @Query("SELECT * FROM shopping_lists ORDER BY last_modified DESC")
+    fun getAllLists(): Flow<List<ShoppingListEntity>>
+
+    @Query("SELECT * FROM shopping_list_items WHERE shopping_list_id = :listId ORDER BY item_name ASC")
+    fun getItemsForList(listId: String): Flow<List<ShoppingListItemEntity>>
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun insertList(list: ShoppingListEntity)
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun insertLists(lists: List<ShoppingListEntity>)
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun insertItem(item: ShoppingListItemEntity)
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun insertItems(items: List<ShoppingListItemEntity>)
+
+    @Query("DELETE FROM shopping_lists WHERE id = :id")
+    suspend fun deleteListById(id: String)
+
+    @Query("DELETE FROM shopping_list_items WHERE id = :id")
+    suspend fun deleteItemById(id: String)
+
+    @Query("DELETE FROM shopping_list_items WHERE shopping_list_id = :listId")
+    suspend fun deleteItemsForList(listId: String)
+
+    @Query("DELETE FROM shopping_lists")
+    suspend fun deleteAll()
+}

android/app/src/main/java/com/pantree/app/data/local/entity/Entities.kt

@@ -0,0 +1,77 @@
+package com.pantree.app.data.local.entity
+
+import androidx.room.ColumnInfo
+import androidx.room.Entity
+import androidx.room.ForeignKey
+import androidx.room.Index
+import androidx.room.PrimaryKey
+
+@Entity(tableName = "pantry_items")
+data class PantryItemEntity(
+    @PrimaryKey val id: String,
+    @ColumnInfo(name = "item_name") val itemName: String,
+    val quantity: Int,
+    @ColumnInfo(name = "last_modified") val lastModified: String,
+    @ColumnInfo(name = "created_at") val createdAt: String
+)
+
+@Entity(tableName = "recipes")
+data class RecipeEntity(
+    @PrimaryKey val id: String,
+    val name: String,
+    val servings: Int,
+    @ColumnInfo(name = "ingredient_count") val ingredientCount: Int,
+    @ColumnInfo(name = "available_ingredient_count") val availableIngredientCount: Int,
+    @ColumnInfo(name = "can_make") val canMake: Boolean,
+    @ColumnInfo(name = "availability_percentage") val availabilityPercentage: Double
+)
+
+@Entity(
+    tableName = "recipe_ingredients",
+    foreignKeys = [ForeignKey(
+        entity = RecipeEntity::class,
+        parentColumns = ["id"],
+        childColumns = ["recipe_id"],
+        onDelete = ForeignKey.CASCADE
+    )],
+    indices = [Index("recipe_id")]
+)
+data class RecipeIngredientEntity(
+    @PrimaryKey val id: String,
+    @ColumnInfo(name = "recipe_id") val recipeId: String,
+    @ColumnInfo(name = "item_name") val itemName: String,
+    val quantity: Double,
+    @ColumnInfo(name = "original_quantity") val originalQuantity: Double,
+    val unit: String,
+    @ColumnInfo(name = "in_pantry") val inPantry: Boolean
+)
+
+@Entity(tableName = "shopping_lists")
+data class ShoppingListEntity(
+    @PrimaryKey val id: String,
+    @ColumnInfo(name = "list_name") val listName: String,
+    @ColumnInfo(name = "item_count") val itemCount: Int,
+    @ColumnInfo(name = "checked_count") val checkedCount: Int,
+    @ColumnInfo(name = "last_modified") val lastModified: String,
+    @ColumnInfo(name = "created_at") val createdAt: String
+)
+
+@Entity(
+    tableName = "shopping_list_items",
+    foreignKeys = [ForeignKey(
+        entity = ShoppingListEntity::class,
+        parentColumns = ["id"],
+        childColumns = ["shopping_list_id"],
+        onDelete = ForeignKey.CASCADE
+    )],
+    indices = [Index("shopping_list_id")]
+)
+data class ShoppingListItemEntity(
+    @PrimaryKey val id: String,
+    @ColumnInfo(name = "shopping_list_id") val shoppingListId: String,
+    @ColumnInfo(name = "item_name") val itemName: String,
+    val quantity: Double,
+    val unit: String,
+    @ColumnInfo(name = "checked_off") val checkedOff: Boolean,
+    @ColumnInfo(name = "last_modified") val lastModified: String
+)

android/app/src/main/java/com/pantree/app/data/model/ApiModels.kt

@@ -0,0 +1,251 @@
+package com.pantree.app.data.model
+
+import com.google.gson.annotations.SerializedName
+
+// ── Auth ──────────────────────────────────────────────────────────────────────
+
+data class SignupRequest(
+    val email: String,
+    val password: String,
+    val name: String
+)
+
+data class SigninRequest(
+    val email: String,
+    val password: String
+)
+
+data class GoogleAuthRequest(
+    @SerializedName("id_token") val idToken: String
+)
+
+data class PasswordResetRequest(
+    val email: String
+)
+
+data class ConfirmPasswordResetRequest(
+    val token: String,
+    @SerializedName("new_password") val newPassword: String
+)
+
+data class AuthResponse(
+    val user: UserDto,
+    val token: String,
+    @SerializedName("expires_at") val expiresAt: String,
+    @SerializedName("is_new_user") val isNewUser: Boolean? = null
+)
+
+data class UserDto(
+    val id: String,
+    val email: String,
+    val name: String,
+    @SerializedName("profile_picture_url") val profilePictureUrl: String?,
+    @SerializedName("deleted_at") val deletedAt: String?,
+    @SerializedName("created_at") val createdAt: String
+)
+
+data class MessageResponse(
+    val message: String,
+    val timestamp: String
+)
+
+data class RestoreAccountResponse(
+    val user: UserDto,
+    val message: String,
+    val timestamp: String
+)
+
+data class ApiError(
+    val error: String,
+    val code: String,
+    val timestamp: String,
+    @SerializedName("deletion_scheduled_at") val deletionScheduledAt: String? = null
+)
+
+// ── Pantry ────────────────────────────────────────────────────────────────────
+
+data class AddPantryItemRequest(
+    @SerializedName("item_name") val itemName: String,
+    val quantity: Int
+)
+
+data class UpdatePantryItemRequest(
+    val quantity: Int
+)
+
+data class PantryItemDto(
+    val id: String,
+    @SerializedName("item_name") val itemName: String,
+    val quantity: Int,
+    @SerializedName("last_modified") val lastModified: String,
+    @SerializedName("created_at") val createdAt: String
+)
+
+data class PantryListResponse(
+    val items: List<PantryItemDto>,
+    @SerializedName("synced_at") val syncedAt: String
+)
+
+data class PantryItemResponse(
+    val item: PantryItemDto,
+    @SerializedName("synced_at") val syncedAt: String
+)
+
+// ── Recipes ───────────────────────────────────────────────────────────────────
+
+data class RecipeSummaryDto(
+    val id: String,
+    val name: String,
+    val servings: Int,
+    @SerializedName("ingredient_count") val ingredientCount: Int,
+    @SerializedName("available_ingredient_count") val availableIngredientCount: Int,
+    @SerializedName("can_make") val canMake: Boolean,
+    @SerializedName("availability_percentage") val availabilityPercentage: Double
+)
+
+data class RecipeIngredientDto(
+    val id: String,
+    @SerializedName("item_name") val itemName: String,
+    val quantity: Double,
+    @SerializedName("original_quantity") val originalQuantity: Double,
+    val unit: String,
+    @SerializedName("in_pantry") val inPantry: Boolean
+)
+
+data class RecipeDetailDto(
+    val id: String,
+    val name: String,
+    val servings: Int,
+    @SerializedName("scaled_servings") val scaledServings: Int,
+    @SerializedName("scale_factor") val scaleFactor: Int,
+    val instructions: String,
+    val ingredients: List<RecipeIngredientDto>,
+    @SerializedName("can_make") val canMake: Boolean,
+    @SerializedName("available_ingredient_count") val availableIngredientCount: Int,
+    @SerializedName("ingredient_count") val ingredientCount: Int
+)
+
+data class PaginationDto(
+    val page: Int,
+    val limit: Int,
+    val total: Int,
+    @SerializedName("total_pages") val totalPages: Int
+)
+
+data class RecipeListResponse(
+    val recipes: List<RecipeSummaryDto>,
+    val pagination: PaginationDto,
+    @SerializedName("synced_at") val syncedAt: String
+)
+
+data class RecipeDetailResponse(
+    val recipe: RecipeDetailDto
+)
+
+// ── Shopping Lists ────────────────────────────────────────────────────────────
+
+data class CreateShoppingListRequest(
+    @SerializedName("list_name") val listName: String
+)
+
+data class AddShoppingListItemRequest(
+    @SerializedName("item_name") val itemName: String,
+    val quantity: Double,
+    val unit: String
+)
+
+data class UpdateShoppingListItemRequest(
+    val quantity: Double? = null,
+    val unit: String? = null,
+    @SerializedName("checked_off") val checkedOff: Boolean? = null
+)
+
+data class AddRecipesToListRequest(
+    @SerializedName("recipe_ids") val recipeIds: List<String>,
+    @SerializedName("scale_factor") val scaleFactor: Int = 1
+)
+
+data class ShoppingListSummaryDto(
+    val id: String,
+    @SerializedName("list_name") val listName: String,
+    @SerializedName("item_count") val itemCount: Int,
+    @SerializedName("checked_count") val checkedCount: Int,
+    @SerializedName("last_modified") val lastModified: String,
+    @SerializedName("created_at") val createdAt: String
+)
+
+data class ShoppingListItemDto(
+    val id: String,
+    @SerializedName("item_name") val itemName: String,
+    val quantity: Double,
+    val unit: String,
+    @SerializedName("checked_off") val checkedOff: Boolean,
+    @SerializedName("last_modified") val lastModified: String,
+    val merged: Boolean? = null
+)
+
+data class ShoppingListDetailDto(
+    val id: String,
+    @SerializedName("list_name") val listName: String,
+    @SerializedName("last_modified") val lastModified: String,
+    @SerializedName("created_at") val createdAt: String,
+    val items: List<ShoppingListItemDto>
+)
+
+data class ShoppingListsResponse(
+    @SerializedName("shopping_lists") val shoppingLists: List<ShoppingListSummaryDto>,
+    @SerializedName("synced_at") val syncedAt: String
+)
+
+data class ShoppingListResponse(
+    @SerializedName("shopping_list") val shoppingList: ShoppingListSummaryDto
+)
+
+data class ShoppingListDetailResponse(
+    @SerializedName("shopping_list") val shoppingList: ShoppingListDetailDto,
+    @SerializedName("synced_at") val syncedAt: String
+)
+
+data class ShoppingListItemResponse(
+    val item: ShoppingListItemDto,
+    @SerializedName("synced_at") val syncedAt: String? = null,
+    val merged: Boolean? = null,
+    @SerializedName("previous_quantity") val previousQuantity: Double? = null
+)
+
+data class AddRecipesResponse(
+    @SerializedName("shopping_list") val shoppingList: ShoppingListDetailDto,
+    @SerializedName("recipes_added") val recipesAdded: Int,
+    @SerializedName("items_merged") val itemsMerged: Int,
+    @SerializedName("items_created") val itemsCreated: Int
+)
+
+// ── Sync ──────────────────────────────────────────────────────────────────────
+
+data class SyncPantryDto(
+    val updated: List<PantryItemDto>,
+    val deleted: List<String>
+)
+
+data class SyncListItemsDto(
+    val updated: List<ShoppingListItemDto>,
+    val deleted: List<String>
+)
+
+data class SyncShoppingListDto(
+    val id: String,
+    @SerializedName("list_name") val listName: String,
+    @SerializedName("last_modified") val lastModified: String,
+    val items: SyncListItemsDto
+)
+
+data class SyncShoppingListsDto(
+    val updated: List<SyncShoppingListDto>,
+    val deleted: List<String>
+)
+
+data class SyncResponse(
+    @SerializedName("server_timestamp") val serverTimestamp: String,
+    val pantry: SyncPantryDto,
+    @SerializedName("shopping_lists") val shoppingLists: SyncShoppingListsDto
+)

android/app/src/main/java/com/pantree/app/data/remote/ApiService.kt

@@ -0,0 +1,108 @@
+package com.pantree.app.data.remote
+
+import com.pantree.app.data.model.*
+import retrofit2.Response
+import retrofit2.http.*
+
+interface ApiService {
+
+    // ── Auth ──────────────────────────────────────────────────────────────────
+
+    @POST("auth/signup")
+    suspend fun signup(@Body request: SignupRequest): Response<AuthResponse>
+
+    @POST("auth/signin")
+    suspend fun signin(@Body request: SigninRequest): Response<AuthResponse>
+
+    @POST("auth/google")
+    suspend fun googleAuth(@Body request: GoogleAuthRequest): Response<AuthResponse>
+
+    @POST("auth/password-reset")
+    suspend fun requestPasswordReset(@Body request: PasswordResetRequest): Response<MessageResponse>
+
+    @PUT("auth/password-reset")
+    suspend fun confirmPasswordReset(@Body request: ConfirmPasswordResetRequest): Response<MessageResponse>
+
+    @DELETE("auth/account")
+    suspend fun deleteAccount(): Response<Unit>
+
+    @POST("auth/restore-account")
+    suspend fun restoreAccount(): Response<RestoreAccountResponse>
+
+    // ── Pantry ────────────────────────────────────────────────────────────────
+
+    @GET("pantry")
+    suspend fun getPantryItems(): Response<PantryListResponse>
+
+    @POST("pantry")
+    suspend fun addPantryItem(@Body request: AddPantryItemRequest): Response<PantryItemResponse>
+
+    @PUT("pantry/{itemId}")
+    suspend fun updatePantryItem(
+        @Path("itemId") itemId: String,
+        @Body request: UpdatePantryItemRequest
+    ): Response<PantryItemResponse>
+
+    @DELETE("pantry/{itemId}")
+    suspend fun deletePantryItem(@Path("itemId") itemId: String): Response<Unit>
+
+    // ── Recipes ───────────────────────────────────────────────────────────────
+
+    @GET("recipes")
+    suspend fun getRecipes(
+        @Query("filter") filter: String = "all",
+        @Query("page") page: Int = 1,
+        @Query("limit") limit: Int = 20,
+        @Query("search") search: String? = null
+    ): Response<RecipeListResponse>
+
+    @GET("recipes/{recipeId}")
+    suspend fun getRecipeById(
+        @Path("recipeId") recipeId: String,
+        @Query("scale") scale: Int = 1
+    ): Response<RecipeDetailResponse>
+
+    // ── Shopping Lists ────────────────────────────────────────────────────────
+
+    @GET("shopping-lists")
+    suspend fun getShoppingLists(): Response<ShoppingListsResponse>
+
+    @POST("shopping-lists")
+    suspend fun createShoppingList(@Body request: CreateShoppingListRequest): Response<ShoppingListResponse>
+
+    @GET("shopping-lists/{listId}")
+    suspend fun getShoppingListById(@Path("listId") listId: String): Response<ShoppingListDetailResponse>
+
+    @DELETE("shopping-lists/{listId}")
+    suspend fun deleteShoppingList(@Path("listId") listId: String): Response<Unit>
+
+    @POST("shopping-lists/{listId}/items")
+    suspend fun addShoppingListItem(
+        @Path("listId") listId: String,
+        @Body request: AddShoppingListItemRequest
+    ): Response<ShoppingListItemResponse>
+
+    @POST("shopping-lists/{listId}/add-recipes")
+    suspend fun addRecipesToShoppingList(
+        @Path("listId") listId: String,
+        @Body request: AddRecipesToListRequest
+    ): Response<AddRecipesResponse>
+
+    @PUT("shopping-lists/{listId}/items/{itemId}")
+    suspend fun updateShoppingListItem(
+        @Path("listId") listId: String,
+        @Path("itemId") itemId: String,
+        @Body request: UpdateShoppingListItemRequest
+    ): Response<ShoppingListItemResponse>
+
+    @DELETE("shopping-lists/{listId}/items/{itemId}")
+    suspend fun deleteShoppingListItem(
+        @Path("listId") listId: String,
+        @Path("itemId") itemId: String
+    ): Response<Unit>
+
+    // ── Sync ──────────────────────────────────────────────────────────────────
+
+    @GET("sync")
+    suspend fun sync(@Query("since") since: String): Response<SyncResponse>
+}

android/app/src/main/java/com/pantree/app/data/remote/AuthInterceptor.kt

@@ -0,0 +1,22 @@
+package com.pantree.app.data.remote
+
+import com.pantree.app.data.local.TokenStore
+import okhttp3.Interceptor
+import okhttp3.Response
+import javax.inject.Inject
+
+class AuthInterceptor @Inject constructor(
+    private val tokenStore: TokenStore
+) : Interceptor {
+    override fun intercept(chain: Interceptor.Chain): Response {
+        val token = tokenStore.getToken()
+        val request = if (token != null) {
+            chain.request().newBuilder()
+                .addHeader("Authorization", "Bearer $token")
+                .build()
+        } else {
+            chain.request()
+        }
+        return chain.proceed(request)
+    }
+}

android/app/src/main/java/com/pantree/app/data/repository/AuthRepository.kt

@@ -0,0 +1,64 @@
+package com.pantree.app.data.repository
+
+import com.google.gson.Gson
+import com.pantree.app.data.model.ApiError
+import com.pantree.app.data.model.AuthResponse
+import com.pantree.app.data.model.ConfirmPasswordResetRequest
+import com.pantree.app.data.model.GoogleAuthRequest
+import com.pantree.app.data.model.MessageResponse
+import com.pantree.app.data.model.PasswordResetRequest
+import com.pantree.app.data.model.RestoreAccountResponse
+import com.pantree.app.data.model.SigninRequest
+import com.pantree.app.data.model.SignupRequest
+import com.pantree.app.data.local.TokenStore
+import com.pantree.app.data.remote.ApiService
+import com.pantree.app.util.Result
+import com.pantree.app.util.safeApiCall
+import javax.inject.Inject
+import javax.inject.Singleton
+
+@Singleton
+class AuthRepository @Inject constructor(
+    private val api: ApiService,
+    private val tokenStore: TokenStore,
+    private val gson: Gson
+) {
+    suspend fun signup(email: String, password: String, name: String): Result<AuthResponse> {
+        val result = safeApiCall(gson) { api.signup(SignupRequest(email, password, name)) }
+        if (result is Result.Success) {
+            tokenStore.saveToken(result.data.token, result.data.expiresAt)
+        }
+        return result
+    }
+
+    suspend fun signin(email: String, password: String): Result<AuthResponse> {
+        val result = safeApiCall(gson) { api.signin(SigninRequest(email, password)) }
+        if (result is Result.Success) {
+            tokenStore.saveToken(result.data.token, result.data.expiresAt)
+        }
+        return result
+    }
+
+    suspend fun googleAuth(idToken: String): Result<AuthResponse> {
+        val result = safeApiCall(gson) { api.googleAuth(GoogleAuthRequest(idToken)) }
+        if (result is Result.Success) {
+            tokenStore.saveToken(result.data.token, result.data.expiresAt)
+        }
+        return result
+    }
+
+    suspend fun requestPasswordReset(email: String): Result<MessageResponse> =
+        safeApiCall(gson) { api.requestPasswordReset(PasswordResetRequest(email)) }
+
+    suspend fun confirmPasswordReset(token: String, newPassword: String): Result<MessageResponse> =
+        safeApiCall(gson) { api.confirmPasswordReset(ConfirmPasswordResetRequest(token, newPassword)) }
+
+    suspend fun deleteAccount(): Result<Unit> =
+        safeApiCall(gson) { api.deleteAccount() }
+
+    suspend fun restoreAccount(): Result<RestoreAccountResponse> =
+        safeApiCall(gson) { api.restoreAccount() }
+
+    fun logout() = tokenStore.clearToken()
+    fun isLoggedIn() = tokenStore.isLoggedIn()
+}

android/app/src/main/java/com/pantree/app/data/repository/PantryRepository.kt

@@ -0,0 +1,63 @@
+package com.pantree.app.data.repository
+
+import com.google.gson.Gson
+import com.pantree.app.data.local.dao.PantryDao
+import com.pantree.app.data.local.entity.PantryItemEntity
+import com.pantree.app.data.model.AddPantryItemRequest
+import com.pantree.app.data.model.PantryItemDto
+import com.pantree.app.data.model.PantryItemResponse
+import com.pantree.app.data.model.PantryListResponse
+import com.pantree.app.data.model.UpdatePantryItemRequest
+import com.pantree.app.data.remote.ApiService
+import com.pantree.app.util.Result
+import com.pantree.app.util.safeApiCall
+import kotlinx.coroutines.flow.Flow
+import javax.inject.Inject
+import javax.inject.Singleton
+
+@Singleton
+class PantryRepository @Inject constructor(
+    private val api: ApiService,
+    private val pantryDao: PantryDao,
+    private val gson: Gson
+) {
+    fun getLocalItems(): Flow<List<PantryItemEntity>> = pantryDao.getAllItems()
+
+    suspend fun fetchAndCacheItems(): Result<PantryListResponse> {
+        val result = safeApiCall(gson) { api.getPantryItems() }
+        if (result is Result.Success) {
+            pantryDao.deleteAll()
+            pantryDao.insertItems(result.data.items.map { it.toEntity() })
+        }
+        return result
+    }
+
+    suspend fun addItem(name: String, quantity: Int): Result<PantryItemResponse> {
+        val result = safeApiCall(gson) { api.addPantryItem(AddPantryItemRequest(name, quantity)) }
+        if (result is Result.Success) {
+            pantryDao.insertItem(result.data.item.toEntity())
+        }
+        return result
+    }
+
+    suspend fun updateItem(id: String, quantity: Int): Result<PantryItemResponse> {
+        val result = safeApiCall(gson) { api.updatePantryItem(id, UpdatePantryItemRequest(quantity)) }
+        if (result is Result.Success) {
+            pantryDao.insertItem(result.data.item.toEntity())
+        }
+        return result
+    }
+
+    suspend fun deleteItem(id: String): Result<Unit> {
+        val result = safeApiCall(gson) { api.deletePantryItem(id) }
+        if (result is Result.Success) {
+            pantryDao.deleteItemById(id)
+        }
+        return result
+    }
+
+    private fun PantryItemDto.toEntity() = PantryItemEntity(
+        id = id, itemName = itemName, quantity = quantity,
+        lastModified = lastModified, createdAt = createdAt
+    )
+}

android/app/src/main/java/com/pantree/app/data/repository/RecipeRepository.kt

@@ -0,0 +1,50 @@
+package com.pantree.app.data.repository
+
+import com.google.gson.Gson
+import com.pantree.app.data.local.dao.RecipeDao
+import com.pantree.app.data.local.entity.RecipeEntity
+import com.pantree.app.data.local.entity.RecipeIngredientEntity
+import com.pantree.app.data.model.RecipeDetailResponse
+import com.pantree.app.data.model.RecipeListResponse
+import com.pantree.app.data.model.RecipeSummaryDto
+import com.pantree.app.data.remote.ApiService
+import com.pantree.app.util.Result
+import com.pantree.app.util.safeApiCall
+import kotlinx.coroutines.flow.Flow
+import javax.inject.Inject
+import javax.inject.Singleton
+
+@Singleton
+class RecipeRepository @Inject constructor(
+    private val api: ApiService,
+    private val recipeDao: RecipeDao,
+    private val gson: Gson
+) {
+    fun getLocalRecipes(): Flow<List<RecipeEntity>> = recipeDao.getAllRecipes()
+    fun getCanMakeRecipes(): Flow<List<RecipeEntity>> = recipeDao.getCanMakeRecipes()
+    fun getPartialRecipes(): Flow<List<RecipeEntity>> = recipeDao.getPartialRecipes()
+
+    suspend fun fetchRecipes(
+        filter: String = "all",
+        page: Int = 1,
+        search: String? = null
+    ): Result<RecipeListResponse> {
+        val result = safeApiCall(gson) { api.getRecipes(filter, page, 20, search) }
+        if (result is Result.Success && page == 1) {
+            recipeDao.deleteAll()
+            recipeDao.insertRecipes(result.data.recipes.map { it.toEntity() })
+        }
+        return result
+    }
+
+    suspend fun getRecipeById(id: String, scale: Int = 1): Result<RecipeDetailResponse> =
+        safeApiCall(gson) { api.getRecipeById(id, scale) }
+
+    private fun RecipeSummaryDto.toEntity() = RecipeEntity(
+        id = id, name = name, servings = servings,
+        ingredientCount = ingredientCount,
+        availableIngredientCount = availableIngredientCount,
+        canMake = canMake,
+        availabilityPercentage = availabilityPercentage
+    )
+}

android/app/src/main/java/com/pantree/app/data/repository/ShoppingListRepository.kt

@@ -0,0 +1,93 @@
+package com.pantree.app.data.repository
+
+import com.google.gson.Gson
+import com.pantree.app.data.local.dao.ShoppingListDao
+import com.pantree.app.data.local.entity.ShoppingListEntity
+import com.pantree.app.data.local.entity.ShoppingListItemEntity
+import com.pantree.app.data.model.*
+import com.pantree.app.data.remote.ApiService
+import com.pantree.app.util.Result
+import com.pantree.app.util.safeApiCall
+import kotlinx.coroutines.flow.Flow
+import javax.inject.Inject
+import javax.inject.Singleton
+
+@Singleton
+class ShoppingListRepository @Inject constructor(
+    private val api: ApiService,
+    private val shoppingListDao: ShoppingListDao,
+    private val gson: Gson
+) {
+    fun getLocalLists(): Flow<List<ShoppingListEntity>> = shoppingListDao.getAllLists()
+    fun getLocalItems(listId: String): Flow<List<ShoppingListItemEntity>> =
+        shoppingListDao.getItemsForList(listId)
+
+    suspend fun fetchLists(): Result<ShoppingListsResponse> {
+        val result = safeApiCall(gson) { api.getShoppingLists() }
+        if (result is Result.Success) {
+            shoppingListDao.deleteAll()
+            shoppingListDao.insertLists(result.data.shoppingLists.map { it.toEntity() })
+        }
+        return result
+    }
+
+    suspend fun createList(name: String): Result<ShoppingListResponse> {
+        val result = safeApiCall(gson) { api.createShoppingList(CreateShoppingListRequest(name)) }
+        if (result is Result.Success) {
+            shoppingListDao.insertList(result.data.shoppingList.toEntity())
+        }
+        return result
+    }
+
+    suspend fun fetchListById(listId: String): Result<ShoppingListDetailResponse> {
+        val result = safeApiCall(gson) { api.getShoppingListById(listId) }
+        if (result is Result.Success) {
+            shoppingListDao.deleteItemsForList(listId)
+            shoppingListDao.insertItems(result.data.shoppingList.items.map { it.toEntity(listId) })
+        }
+        return result
+    }
+
+    suspend fun deleteList(listId: String): Result<Unit> {
+        val result = safeApiCall(gson) { api.deleteShoppingList(listId) }
+        if (result is Result.Success) shoppingListDao.deleteListById(listId)
+        return result
+    }
+
+    suspend fun addItem(listId: String, name: String, quantity: Double, unit: String): Result<ShoppingListItemResponse> {
+        val result = safeApiCall(gson) { api.addShoppingListItem(listId, AddShoppingListItemRequest(name, quantity, unit)) }
+        if (result is Result.Success) shoppingListDao.insertItem(result.data.item.toEntity(listId))
+        return result
+    }
+
+    suspend fun addRecipesToList(listId: String, recipeIds: List<String>, scaleFactor: Int): Result<AddRecipesResponse> {
+        val result = safeApiCall(gson) { api.addRecipesToShoppingList(listId, AddRecipesToListRequest(recipeIds, scaleFactor)) }
+        if (result is Result.Success) {
+            shoppingListDao.deleteItemsForList(listId)
+            shoppingListDao.insertItems(result.data.shoppingList.items.map { it.toEntity(listId) })
+        }
+        return result
+    }
+
+    suspend fun updateItem(listId: String, itemId: String, quantity: Double? = null, unit: String? = null, checkedOff: Boolean? = null): Result<ShoppingListItemResponse> {
+        val result = safeApiCall(gson) { api.updateShoppingListItem(listId, itemId, UpdateShoppingListItemRequest(quantity, unit, checkedOff)) }
+        if (result is Result.Success) shoppingListDao.insertItem(result.data.item.toEntity(listId))
+        return result
+    }
+
+    suspend fun deleteItem(listId: String, itemId: String): Result<Unit> {
+        val result = safeApiCall(gson) { api.deleteShoppingListItem(listId, itemId) }
+        if (result is Result.Success) shoppingListDao.deleteItemById(itemId)
+        return result
+    }
+
+    private fun ShoppingListSummaryDto.toEntity() = ShoppingListEntity(
+        id = id, listName = listName, itemCount = itemCount,
+        checkedCount = checkedCount, lastModified = lastModified, createdAt = createdAt
+    )
+
+    private fun ShoppingListItemDto.toEntity(listId: String) = ShoppingListItemEntity(
+        id = id, shoppingListId = listId, itemName = itemName,
+        quantity = quantity, unit = unit, checkedOff = checkedOff, lastModified = lastModified
+    )
+}

android/app/src/main/java/com/pantree/app/data/repository/SyncRepository.kt

@@ -0,0 +1,65 @@
+package com.pantree.app.data.repository
+
+import com.google.gson.Gson
+import com.pantree.app.data.local.SyncPreferences
+import com.pantree.app.data.local.dao.PantryDao
+import com.pantree.app.data.local.dao.ShoppingListDao
+import com.pantree.app.data.local.entity.PantryItemEntity
+import com.pantree.app.data.local.entity.ShoppingListEntity
+import com.pantree.app.data.local.entity.ShoppingListItemEntity
+import com.pantree.app.data.model.SyncResponse
+import com.pantree.app.data.remote.ApiService
+import com.pantree.app.util.Result
+import com.pantree.app.util.safeApiCall
+import kotlinx.coroutines.flow.first
+import javax.inject.Inject
+import javax.inject.Singleton
+
+@Singleton
+class SyncRepository @Inject constructor(
+    private val api: ApiService,
+    private val pantryDao: PantryDao,
+    private val shoppingListDao: ShoppingListDao,
+    private val syncPreferences: SyncPreferences,
+    private val gson: Gson
+) {
+    suspend fun sync(): Result<SyncResponse> {
+        val since = syncPreferences.lastSyncTimestamp.first()
+        val result = safeApiCall(gson) { api.sync(since) }
+        if (result is Result.Success) {
+            val data = result.data
+            // Apply pantry delta
+            data.pantry.updated.forEach {
+                pantryDao.insertItem(PantryItemEntity(it.id, it.itemName, it.quantity, it.lastModified, it.createdAt))
+            }
+            data.pantry.deleted.forEach { pantryDao.deleteItemById(it) }
+
+            // Apply shopping list delta
+            data.shoppingLists.updated.forEach { list ->
+                shoppingListDao.insertList(
+                    ShoppingListEntity(
+                        id = list.id, listName = list.listName,
+                        itemCount = list.items.updated.size,
+                        checkedCount = list.items.updated.count { it.checkedOff },
+                        lastModified = list.lastModified, createdAt = list.lastModified
+                    )
+                )
+                list.items.updated.forEach { item ->
+                    shoppingListDao.insertItem(
+                        ShoppingListItemEntity(
+                            id = item.id, shoppingListId = list.id,
+                            itemName = item.itemName, quantity = item.quantity,
+                            unit = item.unit, checkedOff = item.checkedOff,
+                            lastModified = item.lastModified
+                        )
+                    )
+                }
+                list.items.deleted.forEach { shoppingListDao.deleteItemById(it) }
+            }
+            data.shoppingLists.deleted.forEach { shoppingListDao.deleteListById(it) }
+
+            syncPreferences.updateLastSync(data.serverTimestamp)
+        }
+        return result
+    }
+}

android/app/src/main/java/com/pantree/app/di/AppModule.kt

@@ -0,0 +1,75 @@
+package com.pantree.app.di
+
+import android.content.Context
+import androidx.room.Room
+import com.google.gson.Gson
+import com.google.gson.GsonBuilder
+import com.pantree.app.BuildConfig
+import com.pantree.app.data.local.PantreeDatabase
+import com.pantree.app.data.local.TokenStore
+import com.pantree.app.data.local.dao.PantryDao
+import com.pantree.app.data.local.dao.RecipeDao
+import com.pantree.app.data.local.dao.ShoppingListDao
+import com.pantree.app.data.remote.ApiService
+import com.pantree.app.data.remote.AuthInterceptor
+import dagger.Module
+import dagger.Provides
+import dagger.hilt.InstallIn
+import dagger.hilt.android.qualifiers.ApplicationContext
+import dagger.hilt.components.SingletonComponent
+import okhttp3.OkHttpClient
+import okhttp3.logging.HttpLoggingInterceptor
+import retrofit2.Retrofit
+import retrofit2.converter.gson.GsonConverterFactory
+import java.util.concurrent.TimeUnit
+import javax.inject.Singleton
+
+@Module
+@InstallIn(SingletonComponent::class)
+object AppModule {
+
+    @Provides
+    @Singleton
+    fun provideGson(): Gson = GsonBuilder().create()
+
+    @Provides
+    @Singleton
+    fun provideOkHttpClient(authInterceptor: AuthInterceptor): OkHttpClient {
+        val logging = HttpLoggingInterceptor().apply {
+            level = if (BuildConfig.DEBUG) HttpLoggingInterceptor.Level.BODY
+                    else HttpLoggingInterceptor.Level.NONE
+        }
+        return OkHttpClient.Builder()
+            .addInterceptor(authInterceptor)
+            .addInterceptor(logging)
+            .connectTimeout(30, TimeUnit.SECONDS)
+            .readTimeout(30, TimeUnit.SECONDS)
+            .writeTimeout(30, TimeUnit.SECONDS)
+            .build()
+    }
+
+    @Provides
+    @Singleton
+    fun provideRetrofit(okHttpClient: OkHttpClient, gson: Gson): Retrofit =
+        Retrofit.Builder()
+            .baseUrl(BuildConfig.BASE_URL)
+            .client(okHttpClient)
+            .addConverterFactory(GsonConverterFactory.create(gson))
+            .build()
+
+    @Provides
+    @Singleton
+    fun provideApiService(retrofit: Retrofit): ApiService =
+        retrofit.create(ApiService::class.java)
+
+    @Provides
+    @Singleton
+    fun provideDatabase(@ApplicationContext context: Context): PantreeDatabase =
+        Room.databaseBuilder(context, PantreeDatabase::class.java, "pantree.db")
+            .fallbackToDestructiveMigration()
+            .build()
+
+    @Provides fun providePantryDao(db: PantreeDatabase): PantryDao = db.pantryDao()
+    @Provides fun provideRecipeDao(db: PantreeDatabase): RecipeDao = db.recipeDao()
+    @Provides fun provideShoppingListDao(db: PantreeDatabase): ShoppingListDao = db.shoppingListDao()
+}

android/app/src/main/java/com/pantree/app/sync/SyncManager.kt

@@ -0,0 +1,41 @@
+package com.pantree.app.sync
+
+import android.content.Context
+import androidx.lifecycle.DefaultLifecycleObserver
+import androidx.lifecycle.LifecycleOwner
+import com.pantree.app.data.local.TokenStore
+import com.pantree.app.data.repository.SyncRepository
+import com.pantree.app.util.Result
+import dagger.hilt.android.qualifiers.ApplicationContext
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.launch
+import javax.inject.Inject
+import javax.inject.Singleton
+
+@Singleton
+class SyncManager @Inject constructor(
+    private val syncRepository: SyncRepository,
+    private val tokenStore: TokenStore,
+    @ApplicationContext private val context: Context
+) : DefaultLifecycleObserver {
+
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
+
+    /** Called on app open (cold start) and foreground return. */
+    override fun onStart(owner: LifecycleOwner) {
+        triggerSync()
+    }
+
+    fun triggerSync() {
+        if (!tokenStore.isLoggedIn()) return
+        scope.launch {
+            when (val result = syncRepository.sync()) {
+                is Result.Success -> { /* Delta applied to Room, UI observes Flow */ }
+                is Result.Error -> { /* Log silently; cached data still shown */ }
+                is Result.NetworkError -> { /* Offline — cached data shown, offline banner visible */ }
+            }
+        }
+    }
+}

android/app/src/main/java/com/pantree/app/ui/components/CommonComponents.kt

@@ -0,0 +1,147 @@
+package com.pantree.app.ui.components
+
+import androidx.compose.foundation.layout.*
+import androidx.compose.material3.*
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.unit.dp
+
+@Composable
+fun LoadingState(
+    modifier: Modifier = Modifier,
+    message: String = "Loading..."
+) {
+    Box(
+        modifier = modifier.fillMaxSize(),
+        contentAlignment = Alignment.Center
+    ) {
+        Column(
+            horizontalAlignment = Alignment.CenterHorizontally,
+            verticalArrangement = Arrangement.spacedBy(16.dp)
+        ) {
+            CircularProgressIndicator(color = MaterialTheme.colorScheme.primary)
+            Text(
+                text = message,
+                style = MaterialTheme.typography.bodyMedium,
+                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.6f)
+            )
+        }
+    }
+}
+
+@Composable
+fun ErrorState(
+    message: String,
+    onRetry: (() -> Unit)? = null,
+    modifier: Modifier = Modifier
+) {
+    Box(
+        modifier = modifier.fillMaxSize().padding(32.dp),
+        contentAlignment = Alignment.Center
+    ) {
+        Column(
+            horizontalAlignment = Alignment.CenterHorizontally,
+            verticalArrangement = Arrangement.spacedBy(16.dp)
+        ) {
+            Text(
+                text = "\uD83D\uDE15",
+                style = MaterialTheme.typography.headlineLarge
+            )
+            Text(
+                text = message,
+                style = MaterialTheme.typography.bodyLarge,
+                textAlign = TextAlign.Center,
+                color = MaterialTheme.colorScheme.onSurface
+            )
+            if (onRetry != null) {
+                Button(onClick = onRetry) {
+                    Text("Try again")
+                }
+            }
+        }
+    }
+}
+
+@Composable
+fun EmptyState(
+    emoji: String,
+    title: String,
+    subtitle: String,
+    actionLabel: String? = null,
+    onAction: (() -> Unit)? = null,
+    modifier: Modifier = Modifier
+) {
+    Box(
+        modifier = modifier.fillMaxSize().padding(32.dp),
+        contentAlignment = Alignment.Center
+    ) {
+        Column(
+            horizontalAlignment = Alignment.CenterHorizontally,
+            verticalArrangement = Arrangement.spacedBy(12.dp)
+        ) {
+            Text(text = emoji, style = MaterialTheme.typography.headlineLarge)
+            Text(
+                text = title,
+                style = MaterialTheme.typography.titleLarge,
+                textAlign = TextAlign.Center
+            )
+            Text(
+                text = subtitle,
+                style = MaterialTheme.typography.bodyMedium,
+                textAlign = TextAlign.Center,
+                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.6f)
+            )
+            if (actionLabel != null && onAction != null) {
+                Spacer(modifier = Modifier.height(8.dp))
+                Button(onClick = onAction) {
+                    Text(actionLabel)
+                }
+            }
+        }
+    }
+}
+
+@Composable
+fun OfflineBanner(modifier: Modifier = Modifier) {
+    Surface(
+        modifier = modifier.fillMaxWidth(),
+        color = MaterialTheme.colorScheme.secondaryContainer
+    ) {
+        Text(
+            text = "\uD83D\uDCF5  You're offline. Showing cached data.",
+            style = MaterialTheme.typography.bodySmall,
+            modifier = Modifier.padding(horizontal = 16.dp, vertical = 8.dp),
+            color = MaterialTheme.colorScheme.onSecondaryContainer
+        )
+    }
+}
+
+@Composable
+fun PantreeTopBar(
+    title: String,
+    onNavigateBack: (() -> Unit)? = null,
+    actions: @Composable RowScope.() -> Unit = {}
+) {
+    TopAppBar(
+        title = { Text(title, style = MaterialTheme.typography.titleLarge) },
+        navigationIcon = {
+            if (onNavigateBack != null) {
+                IconButton(onClick = onNavigateBack) {
+                    Icon(
+                        imageVector = androidx.compose.material.icons.Icons.Default.ArrowBack,
+                        contentDescription = "Back"
+                    )
+                }
+            }
+        },
+        actions = actions,
+        colors = TopAppBarDefaults.topAppBarColors(
+            containerColor = MaterialTheme.colorScheme.primary,
+            titleContentColor = MaterialTheme.colorScheme.onPrimary,
+            navigationIconContentColor = MaterialTheme.colorScheme.onPrimary,
+            actionIconContentColor = MaterialTheme.colorScheme.onPrimary
+        )
+    )
+}

android/app/src/main/java/com/pantree/app/ui/navigation/PantreeNavGraph.kt

@@ -0,0 +1,120 @@
+package com.pantree.app.ui.navigation
+
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.getValue
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import androidx.navigation.NavType
+import androidx.navigation.compose.NavHost
+import androidx.navigation.compose.composable
+import androidx.navigation.compose.rememberNavController
+import androidx.navigation.navArgument
+import androidx.navigation.navDeepLink
+import com.pantree.app.ui.screens.auth.ForgotPasswordScreen
+import com.pantree.app.ui.screens.auth.ResetPasswordScreen
+import com.pantree.app.ui.screens.auth.SignInScreen
+import com.pantree.app.ui.screens.auth.SignUpScreen
+import com.pantree.app.ui.screens.auth.SplashScreen
+import com.pantree.app.ui.screens.pantry.PantryScreen
+import com.pantree.app.ui.screens.recipe.RecipeDetailScreen
+import com.pantree.app.ui.screens.recipe.RecipesScreen
+import com.pantree.app.ui.screens.settings.SettingsScreen
+import com.pantree.app.ui.screens.shopping.ShoppingListDetailScreen
+import com.pantree.app.ui.screens.shopping.ShoppingListsScreen
+
+@Composable
+fun PantreeNavGraph() {
+    val navController = rememberNavController()
+
+    NavHost(navController = navController, startDestination = Screen.Splash.route) {
+
+        composable(Screen.Splash.route) {
+            SplashScreen(
+                onNavigateToSignIn = { navController.navigate(Screen.SignIn.route) { popUpTo(Screen.Splash.route) { inclusive = true } } },
+                onNavigateToPantry = { navController.navigate(Screen.Pantry.route) { popUpTo(Screen.Splash.route) { inclusive = true } } }
+            )
+        }
+
+        composable(Screen.SignIn.route) {
+            SignInScreen(
+                onSignInSuccess = { navController.navigate(Screen.Pantry.route) { popUpTo(Screen.SignIn.route) { inclusive = true } } },
+                onNavigateToSignUp = { navController.navigate(Screen.SignUp.route) },
+                onNavigateToForgotPassword = { navController.navigate(Screen.ForgotPassword.route) }
+            )
+        }
+
+        composable(Screen.SignUp.route) {
+            SignUpScreen(
+                onSignUpSuccess = { navController.navigate(Screen.Pantry.route) { popUpTo(Screen.SignIn.route) { inclusive = true } } },
+                onNavigateBack = { navController.popBackStack() }
+            )
+        }
+
+        composable(Screen.ForgotPassword.route) {
+            ForgotPasswordScreen(onNavigateBack = { navController.popBackStack() })
+        }
+
+        composable(
+            route = Screen.ResetPassword.route,
+            arguments = listOf(navArgument("token") { type = NavType.StringType }),
+            deepLinks = listOf(navDeepLink { uriPattern = "https://pantree.app/reset-password?token={token}" })
+        ) { backStackEntry ->
+            ResetPasswordScreen(
+                token = backStackEntry.arguments?.getString("token") ?: "",
+                onResetSuccess = { navController.navigate(Screen.SignIn.route) { popUpTo(0) { inclusive = true } } }
+            )
+        }
+
+        composable(Screen.Pantry.route) {
+            PantryScreen(
+                onNavigateToRecipes = { navController.navigate(Screen.Recipes.route) },
+                onNavigateToShoppingLists = { navController.navigate(Screen.ShoppingLists.route) },
+                onNavigateToSettings = { navController.navigate(Screen.Settings.route) }
+            )
+        }
+
+        composable(Screen.Recipes.route) {
+            RecipesScreen(
+                onRecipeClick = { id -> navController.navigate(Screen.RecipeDetail.createRoute(id)) },
+                onNavigateBack = { navController.popBackStack() }
+            )
+        }
+
+        composable(
+            route = Screen.RecipeDetail.route,
+            arguments = listOf(navArgument("recipeId") { type = NavType.StringType })
+        ) { backStackEntry ->
+            RecipeDetailScreen(
+                recipeId = backStackEntry.arguments?.getString("recipeId") ?: "",
+                onNavigateBack = { navController.popBackStack() },
+                onAddToList = { listId -> navController.navigate(Screen.ShoppingListDetail.createRoute(listId)) }
+            )
+        }
+
+        composable(Screen.ShoppingLists.route) {
+            ShoppingListsScreen(
+                onListClick = { id -> navController.navigate(Screen.ShoppingListDetail.createRoute(id)) },
+                onNavigateBack = { navController.popBackStack() }
+            )
+        }
+
+        composable(
+            route = Screen.ShoppingListDetail.route,
+            arguments = listOf(navArgument("listId") { type = NavType.StringType })
+        ) { backStackEntry ->
+            ShoppingListDetailScreen(
+                listId = backStackEntry.arguments?.getString("listId") ?: "",
+                onNavigateBack = { navController.popBackStack() },
+                onNavigateToRecipes = { navController.navigate(Screen.Recipes.route) }
+            )
+        }
+
+        composable(Screen.Settings.route) {
+            SettingsScreen(
+                onSignOut = { navController.navigate(Screen.SignIn.route) { popUpTo(0) { inclusive = true } } },
+                onNavigateBack = { navController.popBackStack() }
+            )
+        }
+    }
+}

android/app/src/main/java/com/pantree/app/ui/navigation/Screen.kt

@@ -0,0 +1,24 @@
+package com.pantree.app.ui.navigation
+
+sealed class Screen(val route: String) {
+    // Auth
+    object Splash : Screen("splash")
+    object SignIn : Screen("signin")
+    object SignUp : Screen("signup")
+    object ForgotPassword : Screen("forgot_password")
+    object ResetPassword : Screen("reset_password/{token}") {
+        fun createRoute(token: String) = "reset_password/$token"
+    }
+
+    // Main
+    object Pantry : Screen("pantry")
+    object Recipes : Screen("recipes")
+    object RecipeDetail : Screen("recipe/{recipeId}") {
+        fun createRoute(id: String) = "recipe/$id"
+    }
+    object ShoppingLists : Screen("shopping_lists")
+    object ShoppingListDetail : Screen("shopping_list/{listId}") {
+        fun createRoute(id: String) = "shopping_list/$id"
+    }
+    object Settings : Screen("settings")
+}

android/app/src/main/java/com/pantree/app/ui/screens/auth/AuthViewModel.kt

@@ -0,0 +1,93 @@
+package com.pantree.app.ui.screens.auth
+
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewModelScope
+import com.pantree.app.data.repository.AuthRepository
+import com.pantree.app.util.Result
+import com.pantree.app.util.toUserMessage
+import dagger.hilt.android.lifecycle.HiltViewModel
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.launch
+import javax.inject.Inject
+
+data class AuthUiState(
+    val isLoading: Boolean = false,
+    val error: String? = null,
+    val success: Boolean = false,
+    val pendingDeletionDate: String? = null
+)
+
+@HiltViewModel
+class AuthViewModel @Inject constructor(
+    private val authRepository: AuthRepository
+) : ViewModel() {
+
+    private val _uiState = MutableStateFlow(AuthUiState())
+    val uiState: StateFlow<AuthUiState> = _uiState.asStateFlow()
+
+    fun signup(email: String, password: String, name: String) {
+        viewModelScope.launch {
+            _uiState.value = AuthUiState(isLoading = true)
+            when (val result = authRepository.signup(email, password, name)) {
+                is Result.Success -> _uiState.value = AuthUiState(success = true)
+                is Result.Error -> _uiState.value = AuthUiState(error = result.toUserMessage())
+                is Result.NetworkError -> _uiState.value = AuthUiState(error = "No internet connection. Please check your network.")
+            }
+        }
+    }
+
+    fun signin(email: String, password: String) {
+        viewModelScope.launch {
+            _uiState.value = AuthUiState(isLoading = true)
+            when (val result = authRepository.signin(email, password)) {
+                is Result.Success -> _uiState.value = AuthUiState(success = true)
+                is Result.Error -> {
+                    val pendingDate = if (result.code == "ACCOUNT_PENDING_DELETION") result.message else null
+                    _uiState.value = AuthUiState(error = result.toUserMessage(), pendingDeletionDate = pendingDate)
+                }
+                is Result.NetworkError -> _uiState.value = AuthUiState(error = "No internet connection. Please check your network.")
+            }
+        }
+    }
+
+    fun googleAuth(idToken: String) {
+        viewModelScope.launch {
+            _uiState.value = AuthUiState(isLoading = true)
+            when (val result = authRepository.googleAuth(idToken)) {
+                is Result.Success -> _uiState.value = AuthUiState(success = true)
+                is Result.Error -> _uiState.value = AuthUiState(error = result.toUserMessage())
+                is Result.NetworkError -> _uiState.value = AuthUiState(error = "No internet connection. Please check your network.")
+            }
+        }
+    }
+
+    fun requestPasswordReset(email: String) {
+        viewModelScope.launch {
+            _uiState.value = AuthUiState(isLoading = true)
+            when (authRepository.requestPasswordReset(email)) {
+                is Result.Success -> _uiState.value = AuthUiState(success = true)
+                is Result.Error -> _uiState.value = AuthUiState(success = true) // Always show success (anti-enumeration)
+                is Result.NetworkError -> _uiState.value = AuthUiState(error = "No internet connection. Please check your network.")
+            }
+        }
+    }
+
+    fun confirmPasswordReset(token: String, newPassword: String) {
+        viewModelScope.launch {
+            _uiState.value = AuthUiState(isLoading = true)
+            when (val result = authRepository.confirmPasswordReset(token, newPassword)) {
+                is Result.Success -> _uiState.value = AuthUiState(success = true)
+                is Result.Error -> _uiState.value = AuthUiState(error = result.toUserMessage())
+                is Result.NetworkError -> _uiState.value = AuthUiState(error = "No internet connection. Please check your network.")
+            }
+        }
+    }
+
+    fun clearError() {
+        _uiState.value = _uiState.value.copy(error = null)
+    }
+
+    fun isLoggedIn() = authRepository.isLoggedIn()
+}

android/app/src/main/java/com/pantree/app/ui/screens/auth/ForgotPasswordScreen.kt

@@ -0,0 +1,153 @@
+package com.pantree.app.ui.screens.auth
+
+import androidx.compose.foundation.layout.*
+import androidx.compose.foundation.text.KeyboardOptions
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.ArrowBack
+import androidx.compose.material3.*
+import androidx.compose.runtime.*
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.text.input.KeyboardType
+import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.unit.dp
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+
+@Composable
+fun ForgotPasswordScreen(
+    onNavigateBack: () -> Unit,
+    viewModel: AuthViewModel = hiltViewModel()
+) {
+    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
+    var email by remember { mutableStateOf("") }
+
+    Scaffold(
+        topBar = {
+            TopAppBar(
+                title = { Text("Reset password") },
+                navigationIcon = { IconButton(onClick = onNavigateBack) { Icon(Icons.Default.ArrowBack, "Back") } }
+            )
+        }
+    ) { padding ->
+        Column(
+            modifier = Modifier.fillMaxSize().padding(padding).padding(24.dp),
+            verticalArrangement = Arrangement.spacedBy(16.dp)
+        ) {
+            if (uiState.success) {
+                // Success state
+                Box(modifier = Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
+                    Column(
+                        horizontalAlignment = Alignment.CenterHorizontally,
+                        verticalArrangement = Arrangement.spacedBy(12.dp)
+                    ) {
+                        Text("📬", style = MaterialTheme.typography.headlineLarge)
+                        Text("Check your inbox", style = MaterialTheme.typography.titleLarge)
+                        Text(
+                            "If an account exists for $email, we've sent a reset link. It expires in 1 hour.",
+                            style = MaterialTheme.typography.bodyMedium,
+                            textAlign = TextAlign.Center,
+                            color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.7f)
+                        )
+                        Spacer(Modifier.height(8.dp))
+                        OutlinedButton(onClick = onNavigateBack) { Text("Back to sign in") }
+                    }
+                }
+            } else {
+                Text("Enter your email and we'll send you a reset link.", style = MaterialTheme.typography.bodyMedium)
+
+                if (uiState.error != null) {
+                    Card(
+                        colors = CardDefaults.cardColors(containerColor = MaterialTheme.colorScheme.errorContainer),
+                        modifier = Modifier.fillMaxWidth()
+                    ) {
+                        Text(uiState.error!!, modifier = Modifier.padding(12.dp), color = MaterialTheme.colorScheme.onErrorContainer)
+                    }
+                }
+
+                OutlinedTextField(
+                    value = email,
+                    onValueChange = { email = it },
+                    label = { Text("Email") },
+                    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Email),
+                    singleLine = true,
+                    modifier = Modifier.fillMaxWidth()
+                )
+                Button(
+                    onClick = { viewModel.requestPasswordReset(email.trim()) },
+                    enabled = !uiState.isLoading && email.isNotBlank(),
+                    modifier = Modifier.fillMaxWidth().height(52.dp)
+                ) {
+                    if (uiState.isLoading) {
+                        CircularProgressIndicator(modifier = Modifier.size(20.dp), color = MaterialTheme.colorScheme.onPrimary)
+                    } else {
+                        Text("Send reset link")
+                    }
+                }
+            }
+        }
+    }
+}
+
+@Composable
+fun ResetPasswordScreen(
+    token: String,
+    onResetSuccess: () -> Unit,
+    viewModel: AuthViewModel = hiltViewModel()
+) {
+    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
+    var newPassword by remember { mutableStateOf("") }
+    var confirmPassword by remember { mutableStateOf("") }
+    val passwordsMatch = newPassword == confirmPassword && newPassword.isNotEmpty()
+
+    LaunchedEffect(uiState.success) {
+        if (uiState.success) onResetSuccess()
+    }
+
+    Scaffold(topBar = { TopAppBar(title = { Text("New password") }) }) { padding ->
+        Column(
+            modifier = Modifier.fillMaxSize().padding(padding).padding(24.dp),
+            verticalArrangement = Arrangement.spacedBy(16.dp)
+        ) {
+            Text("Choose a new password for your account.", style = MaterialTheme.typography.bodyMedium)
+
+            if (uiState.error != null) {
+                Card(
+                    colors = CardDefaults.cardColors(containerColor = MaterialTheme.colorScheme.errorContainer),
+                    modifier = Modifier.fillMaxWidth()
+                ) {
+                    Text(uiState.error!!, modifier = Modifier.padding(12.dp), color = MaterialTheme.colorScheme.onErrorContainer)
+                }
+            }
+
+            OutlinedTextField(
+                value = newPassword,
+                onValueChange = { newPassword = it; viewModel.clearError() },
+                label = { Text("New password") },
+                supportingText = { Text("At least 8 characters") },
+                singleLine = true,
+                modifier = Modifier.fillMaxWidth()
+            )
+            OutlinedTextField(
+                value = confirmPassword,
+                onValueChange = { confirmPassword = it },
+                label = { Text("Confirm password") },
+                isError = confirmPassword.isNotEmpty() && !passwordsMatch,
+                supportingText = { if (confirmPassword.isNotEmpty() && !passwordsMatch) Text("Passwords don't match") },
+                singleLine = true,
+                modifier = Modifier.fillMaxWidth()
+            )
+            Button(
+                onClick = { viewModel.confirmPasswordReset(token, newPassword) },
+                enabled = !uiState.isLoading && passwordsMatch && newPassword.length >= 8,
+                modifier = Modifier.fillMaxWidth().height(52.dp)
+            ) {
+                if (uiState.isLoading) {
+                    CircularProgressIndicator(modifier = Modifier.size(20.dp), color = MaterialTheme.colorScheme.onPrimary)
+                } else {
+                    Text("Update password")
+                }
+            }
+        }
+    }
+}

android/app/src/main/java/com/pantree/app/ui/screens/auth/SignInScreen.kt

@@ -0,0 +1,133 @@
+package com.pantree.app.ui.screens.auth
+
+import androidx.compose.foundation.layout.*
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.text.KeyboardOptions
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Visibility
+import androidx.compose.material.icons.filled.VisibilityOff
+import androidx.compose.material3.*
+import androidx.compose.runtime.*
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.text.input.KeyboardType
+import androidx.compose.ui.text.input.PasswordVisualTransformation
+import androidx.compose.ui.text.input.VisualTransformation
+import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.unit.dp
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+
+@Composable
+fun SignInScreen(
+    onSignInSuccess: () -> Unit,
+    onNavigateToSignUp: () -> Unit,
+    onNavigateToForgotPassword: () -> Unit,
+    viewModel: AuthViewModel = hiltViewModel()
+) {
+    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
+    var email by remember { mutableStateOf("") }
+    var password by remember { mutableStateOf("") }
+    var passwordVisible by remember { mutableStateOf(false) }
+
+    LaunchedEffect(uiState.success) {
+        if (uiState.success) onSignInSuccess()
+    }
+
+    Scaffold { padding ->
+        Column(
+            modifier = Modifier
+                .fillMaxSize()
+                .padding(padding)
+                .padding(horizontal = 24.dp)
+                .verticalScroll(rememberScrollState()),
+            horizontalAlignment = Alignment.CenterHorizontally,
+            verticalArrangement = Arrangement.Center
+        ) {
+            Spacer(Modifier.height(48.dp))
+            Text("🌿", style = MaterialTheme.typography.headlineLarge)
+            Spacer(Modifier.height(8.dp))
+            Text("Welcome back", style = MaterialTheme.typography.headlineMedium)
+            Text(
+                "Sign in to your pantry",
+                style = MaterialTheme.typography.bodyMedium,
+                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.6f)
+            )
+            Spacer(Modifier.height(32.dp))
+
+            // Error banner
+            if (uiState.error != null) {
+                Card(
+                    colors = CardDefaults.cardColors(containerColor = MaterialTheme.colorScheme.errorContainer),
+                    modifier = Modifier.fillMaxWidth()
+                ) {
+                    Text(
+                        text = uiState.error!!,
+                        modifier = Modifier.padding(12.dp),
+                        color = MaterialTheme.colorScheme.onErrorContainer,
+                        style = MaterialTheme.typography.bodyMedium
+                    )
+                }
+                Spacer(Modifier.height(16.dp))
+            }
+
+            OutlinedTextField(
+                value = email,
+                onValueChange = { email = it; viewModel.clearError() },
+                label = { Text("Email") },
+                keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Email),
+                singleLine = true,
+                modifier = Modifier.fillMaxWidth()
+            )
+            Spacer(Modifier.height(12.dp))
+            OutlinedTextField(
+                value = password,
+                onValueChange = { password = it; viewModel.clearError() },
+                label = { Text("Password") },
+                singleLine = true,
+                visualTransformation = if (passwordVisible) VisualTransformation.None else PasswordVisualTransformation(),
+                keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password),
+                trailingIcon = {
+                    IconButton(onClick = { passwordVisible = !passwordVisible }) {
+                        Icon(
+                            imageVector = if (passwordVisible) Icons.Default.VisibilityOff else Icons.Default.Visibility,
+                            contentDescription = if (passwordVisible) "Hide password" else "Show password"
+                        )
+                    }
+                },
+                modifier = Modifier.fillMaxWidth()
+            )
+            TextButton(
+                onClick = onNavigateToForgotPassword,
+                modifier = Modifier.align(Alignment.End)
+            ) {
+                Text("Forgot password?")
+            }
+            Spacer(Modifier.height(8.dp))
+            Button(
+                onClick = { viewModel.signin(email.trim(), password) },
+                enabled = !uiState.isLoading && email.isNotBlank() && password.isNotBlank(),
+                modifier = Modifier.fillMaxWidth().height(52.dp)
+            ) {
+                if (uiState.isLoading) {
+                    CircularProgressIndicator(modifier = Modifier.size(20.dp), color = MaterialTheme.colorScheme.onPrimary)
+                } else {
+                    Text("Sign in")
+                }
+            }
+            Spacer(Modifier.height(16.dp))
+            Row(verticalAlignment = Alignment.CenterVertically) {
+                HorizontalDivider(modifier = Modifier.weight(1f))
+                Text(" or ", style = MaterialTheme.typography.bodySmall, color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.5f))
+                HorizontalDivider(modifier = Modifier.weight(1f))
+            }
+            Spacer(Modifier.height(16.dp))
+            Row(verticalAlignment = Alignment.CenterVertically) {
+                Text("Don't have an account?", style = MaterialTheme.typography.bodyMedium)
+                TextButton(onClick = onNavigateToSignUp) { Text("Sign up") }
+            }
+            Spacer(Modifier.height(48.dp))
+        }
+    }
+}

android/app/src/main/java/com/pantree/app/ui/screens/auth/SignUpScreen.kt

@@ -0,0 +1,124 @@
+package com.pantree.app.ui.screens.auth
+
+import androidx.compose.foundation.layout.*
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.text.KeyboardOptions
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.ArrowBack
+import androidx.compose.material.icons.filled.Visibility
+import androidx.compose.material.icons.filled.VisibilityOff
+import androidx.compose.material3.*
+import androidx.compose.runtime.*
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.text.input.KeyboardType
+import androidx.compose.ui.text.input.PasswordVisualTransformation
+import androidx.compose.ui.text.input.VisualTransformation
+import androidx.compose.ui.unit.dp
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+
+@Composable
+fun SignUpScreen(
+    onSignUpSuccess: () -> Unit,
+    onNavigateBack: () -> Unit,
+    viewModel: AuthViewModel = hiltViewModel()
+) {
+    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
+    var name by remember { mutableStateOf("") }
+    var email by remember { mutableStateOf("") }
+    var password by remember { mutableStateOf("") }
+    var passwordVisible by remember { mutableStateOf(false) }
+
+    LaunchedEffect(uiState.success) {
+        if (uiState.success) onSignUpSuccess()
+    }
+
+    Scaffold(
+        topBar = {
+            TopAppBar(
+                title = { Text("Create account") },
+                navigationIcon = { IconButton(onClick = onNavigateBack) { Icon(Icons.Default.ArrowBack, "Back") } }
+            )
+        }
+    ) { padding ->
+        Column(
+            modifier = Modifier
+                .fillMaxSize()
+                .padding(padding)
+                .padding(horizontal = 24.dp)
+                .verticalScroll(rememberScrollState()),
+            verticalArrangement = Arrangement.spacedBy(12.dp)
+        ) {
+            Spacer(Modifier.height(16.dp))
+            Text("Let's get you set up", style = MaterialTheme.typography.headlineSmall)
+            Text(
+                "Your pantry awaits.",
+                style = MaterialTheme.typography.bodyMedium,
+                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.6f)
+            )
+            Spacer(Modifier.height(8.dp))
+
+            if (uiState.error != null) {
+                Card(
+                    colors = CardDefaults.cardColors(containerColor = MaterialTheme.colorScheme.errorContainer),
+                    modifier = Modifier.fillMaxWidth()
+                ) {
+                    Text(
+                        text = uiState.error!!,
+                        modifier = Modifier.padding(12.dp),
+                        color = MaterialTheme.colorScheme.onErrorContainer,
+                        style = MaterialTheme.typography.bodyMedium
+                    )
+                }
+            }
+
+            OutlinedTextField(
+                value = name,
+                onValueChange = { name = it; viewModel.clearError() },
+                label = { Text("Full name") },
+                singleLine = true,
+                modifier = Modifier.fillMaxWidth()
+            )
+            OutlinedTextField(
+                value = email,
+                onValueChange = { email = it; viewModel.clearError() },
+                label = { Text("Email") },
+                keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Email),
+                singleLine = true,
+                modifier = Modifier.fillMaxWidth()
+            )
+            OutlinedTextField(
+                value = password,
+                onValueChange = { password = it; viewModel.clearError() },
+                label = { Text("Password") },
+                supportingText = { Text("At least 8 characters") },
+                singleLine = true,
+                visualTransformation = if (passwordVisible) VisualTransformation.None else PasswordVisualTransformation(),
+                keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password),
+                trailingIcon = {
+                    IconButton(onClick = { passwordVisible = !passwordVisible }) {
+                        Icon(
+                            imageVector = if (passwordVisible) Icons.Default.VisibilityOff else Icons.Default.Visibility,
+                            contentDescription = null
+                        )
+                    }
+                },
+                modifier = Modifier.fillMaxWidth()
+            )
+            Spacer(Modifier.height(8.dp))
+            Button(
+                onClick = { viewModel.signup(email.trim(), password, name.trim()) },
+                enabled = !uiState.isLoading && name.isNotBlank() && email.isNotBlank() && password.length >= 8,
+                modifier = Modifier.fillMaxWidth().height(52.dp)
+            ) {
+                if (uiState.isLoading) {
+                    CircularProgressIndicator(modifier = Modifier.size(20.dp), color = MaterialTheme.colorScheme.onPrimary)
+                } else {
+                    Text("Create account")
+                }
+            }
+        }
+    }
+}

android/app/src/main/java/com/pantree/app/ui/screens/auth/SplashScreen.kt

@@ -0,0 +1,31 @@
+package com.pantree.app.ui.screens.auth
+
+import androidx.compose.foundation.layout.*
+import androidx.compose.material3.*
+import androidx.compose.runtime.*
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+
+@Composable
+fun SplashScreen(
+    onNavigateToSignIn: () -> Unit,
+    onNavigateToPantry: () -> Unit,
+    viewModel: AuthViewModel = hiltViewModel()
+) {
+    val isLoggedIn = remember { viewModel.isLoggedIn() }
+
+    LaunchedEffect(Unit) {
+        if (isLoggedIn) onNavigateToPantry() else onNavigateToSignIn()
+    }
+
+    Box(modifier = Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
+        Column(horizontalAlignment = Alignment.CenterHorizontally, verticalArrangement = Arrangement.spacedBy(16.dp)) {
+            Text("🌿", style = MaterialTheme.typography.headlineLarge)
+            Text("Pantree", style = MaterialTheme.typography.headlineMedium, color = MaterialTheme.colorScheme.primary)
+            CircularProgressIndicator(modifier = Modifier.size(24.dp))
+        }
+    }
+}

android/app/src/main/java/com/pantree/app/ui/screens/pantry/PantryScreen.kt

@@ -0,0 +1,253 @@
+package com.pantree.app.ui.screens.pantry
+
+import androidx.compose.foundation.layout.*
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.items
+import androidx.compose.foundation.text.KeyboardOptions
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.*
+import androidx.compose.material3.*
+import androidx.compose.runtime.*
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.text.input.KeyboardType
+import androidx.compose.ui.unit.dp
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import com.pantree.app.data.local.entity.PantryItemEntity
+import com.pantree.app.ui.components.EmptyState
+import com.pantree.app.ui.components.ErrorState
+import com.pantree.app.ui.components.LoadingState
+
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+fun PantryScreen(
+    onNavigateToRecipes: () -> Unit,
+    onNavigateToShoppingLists: () -> Unit,
+    onNavigateToSettings: () -> Unit,
+    viewModel: PantryViewModel = hiltViewModel()
+) {
+    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
+    var showAddDialog by remember { mutableStateOf(false) }
+    var editingItem by remember { mutableStateOf<PantryItemEntity?>(null) }
+    var deletingItem by remember { mutableStateOf<PantryItemEntity?>(null) }
+    val snackbarHostState = remember { SnackbarHostState() }
+
+    LaunchedEffect(uiState.actionSuccess) {
+        uiState.actionSuccess?.let {
+            snackbarHostState.showSnackbar(it)
+            viewModel.clearActionMessages()
+        }
+    }
+    LaunchedEffect(uiState.actionError) {
+        uiState.actionError?.let {
+            snackbarHostState.showSnackbar(it)
+            viewModel.clearActionMessages()
+        }
+    }
+
+    Scaffold(
+        topBar = {
+            TopAppBar(
+                title = { Text("My Pantry") },
+                actions = {
+                    IconButton(onClick = onNavigateToRecipes) {
+                        Icon(Icons.Default.MenuBook, contentDescription = "Recipes", tint = MaterialTheme.colorScheme.onPrimary)
+                    }
+                    IconButton(onClick = onNavigateToShoppingLists) {
+                        Icon(Icons.Default.ShoppingCart, contentDescription = "Shopping Lists", tint = MaterialTheme.colorScheme.onPrimary)
+                    }
+                    IconButton(onClick = onNavigateToSettings) {
+                        Icon(Icons.Default.Settings, contentDescription = "Settings", tint = MaterialTheme.colorScheme.onPrimary)
+                    }
+                },
+                colors = TopAppBarDefaults.topAppBarColors(
+                    containerColor = MaterialTheme.colorScheme.primary,
+                    titleContentColor = MaterialTheme.colorScheme.onPrimary
+                )
+            )
+        },
+        floatingActionButton = {
+            FloatingActionButton(onClick = { showAddDialog = true }) {
+                Icon(Icons.Default.Add, contentDescription = "Add item")
+            }
+        },
+        snackbarHost = { SnackbarHost(snackbarHostState) }
+    ) { padding ->
+        Box(modifier = Modifier.fillMaxSize().padding(padding)) {
+            when {
+                uiState.isLoading && uiState.items.isEmpty() -> LoadingState(message = "Loading your pantry...")
+                uiState.error != null && uiState.items.isEmpty() -> ErrorState(
+                    message = uiState.error!!,
+                    onRetry = { viewModel.refresh() }
+                )
+                uiState.items.isEmpty() -> EmptyState(
+                    emoji = "\uD83E\uDED9",
+                    title = "Your pantry is empty",
+                    subtitle = "Add ingredients you have on hand and we'll tell you what you can cook.",
+                    actionLabel = "Add your first item",
+                    onAction = { showAddDialog = true }
+                )
+                else -> {
+                    LazyColumn(
+                        contentPadding = PaddingValues(16.dp),
+                        verticalArrangement = Arrangement.spacedBy(8.dp)
+                    ) {
+                        item {
+                            Text(
+                                "${uiState.items.size} item${if (uiState.items.size != 1) "s" else ""}",
+                                style = MaterialTheme.typography.bodySmall,
+                                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.5f),
+                                modifier = Modifier.padding(bottom = 4.dp)
+                            )
+                        }
+                        items(uiState.items, key = { it.id }) { item ->
+                            PantryItemCard(
+                                item = item,
+                                onEdit = { editingItem = item },
+                                onDelete = { deletingItem = item }
+                            )
+                        }
+                        item { Spacer(Modifier.height(80.dp)) }
+                    }
+                }
+            }
+        }
+    }
+
+    if (showAddDialog) {
+        AddPantryItemDialog(
+            onDismiss = { showAddDialog = false },
+            onConfirm = { name, qty ->
+                viewModel.addItem(name, qty)
+                showAddDialog = false
+            }
+        )
+    }
+
+    editingItem?.let { item ->
+        EditPantryItemDialog(
+            item = item,
+            onDismiss = { editingItem = null },
+            onConfirm = { qty ->
+                viewModel.updateItem(item.id, qty)
+                editingItem = null
+            }
+        )
+    }
+
+    deletingItem?.let { item ->
+        AlertDialog(
+            onDismissRequest = { deletingItem = null },
+            title = { Text("Remove item?") },
+            text = { Text("Remove \"${item.itemName}\" from your pantry?") },
+            confirmButton = {
+                TextButton(onClick = { viewModel.deleteItem(item.id); deletingItem = null }) {
+                    Text("Remove", color = MaterialTheme.colorScheme.error)
+                }
+            },
+            dismissButton = { TextButton(onClick = { deletingItem = null }) { Text("Cancel") } }
+        )
+    }
+}
+
+@Composable
+fun PantryItemCard(
+    item: PantryItemEntity,
+    onEdit: () -> Unit,
+    onDelete: () -> Unit
+) {
+    Card(modifier = Modifier.fillMaxWidth()) {
+        Row(
+            modifier = Modifier.padding(horizontal = 16.dp, vertical = 12.dp),
+            verticalAlignment = Alignment.CenterVertically
+        ) {
+            Column(modifier = Modifier.weight(1f)) {
+                Text(item.itemName, style = MaterialTheme.typography.titleMedium)
+                Text(
+                    "Qty: ${item.quantity}",
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.6f)
+                )
+            }
+            IconButton(onClick = onEdit) {
+                Icon(Icons.Default.Edit, contentDescription = "Edit", tint = MaterialTheme.colorScheme.primary)
+            }
+            IconButton(onClick = onDelete) {
+                Icon(Icons.Default.Delete, contentDescription = "Delete", tint = MaterialTheme.colorScheme.error)
+            }
+        }
+    }
+}
+
+@Composable
+fun AddPantryItemDialog(onDismiss: () -> Unit, onConfirm: (String, Int) -> Unit) {
+    var name by remember { mutableStateOf("") }
+    var quantityText by remember { mutableStateOf("1") }
+    val quantity = quantityText.toIntOrNull()
+    val isValid = name.isNotBlank() && quantity != null && quantity > 0
+
+    AlertDialog(
+        onDismissRequest = onDismiss,
+        title = { Text("Add to pantry") },
+        text = {
+            Column(verticalArrangement = Arrangement.spacedBy(12.dp)) {
+                OutlinedTextField(
+                    value = name,
+                    onValueChange = { name = it },
+                    label = { Text("Item name") },
+                    singleLine = true,
+                    modifier = Modifier.fillMaxWidth()
+                )
+                OutlinedTextField(
+                    value = quantityText,
+                    onValueChange = { quantityText = it },
+                    label = { Text("Quantity") },
+                    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Number),
+                    singleLine = true,
+                    isError = quantityText.isNotEmpty() && quantity == null,
+                    supportingText = { if (quantityText.isNotEmpty() && quantity == null) Text("Must be a whole number") },
+                    modifier = Modifier.fillMaxWidth()
+                )
+            }
+        },
+        confirmButton = {
+            TextButton(onClick = { if (isValid) onConfirm(name, quantity!!) }, enabled = isValid) {
+                Text("Add")
+            }
+        },
+        dismissButton = { TextButton(onClick = onDismiss) { Text("Cancel") } }
+    )
+}
+
+@Composable
+fun EditPantryItemDialog(item: PantryItemEntity, onDismiss: () -> Unit, onConfirm: (Int) -> Unit) {
+    var quantityText by remember { mutableStateOf(item.quantity.toString()) }
+    val quantity = quantityText.toIntOrNull()
+    val isValid = quantity != null && quantity > 0
+
+    AlertDialog(
+        onDismissRequest = onDismiss,
+        title = { Text("Edit quantity") },
+        text = {
+            Column(verticalArrangement = Arrangement.spacedBy(8.dp)) {
+                Text(item.itemName, style = MaterialTheme.typography.titleMedium)
+                OutlinedTextField(
+                    value = quantityText,
+                    onValueChange = { quantityText = it },
+                    label = { Text("Quantity") },
+                    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Number),
+                    singleLine = true,
+                    isError = quantityText.isNotEmpty() && !isValid,
+                    modifier = Modifier.fillMaxWidth()
+                )
+            }
+        },
+        confirmButton = {
+            TextButton(onClick = { if (isValid) onConfirm(quantity!!) }, enabled = isValid) {
+                Text("Save")
+            }
+        },
+        dismissButton = { TextButton(onClick = onDismiss) { Text("Cancel") } }
+    )
+}

android/app/src/main/java/com/pantree/app/ui/screens/pantry/PantryViewModel.kt

@@ -0,0 +1,84 @@
+package com.pantree.app.ui.screens.pantry
+
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewModelScope
+import com.pantree.app.data.local.entity.PantryItemEntity
+import com.pantree.app.data.repository.PantryRepository
+import com.pantree.app.util.Result
+import com.pantree.app.util.toUserMessage
+import dagger.hilt.android.lifecycle.HiltViewModel
+import kotlinx.coroutines.flow.*
+import kotlinx.coroutines.launch
+import javax.inject.Inject
+
+data class PantryUiState(
+    val isLoading: Boolean = false,
+    val items: List<PantryItemEntity> = emptyList(),
+    val error: String? = null,
+    val actionError: String? = null,
+    val actionSuccess: String? = null
+)
+
+@HiltViewModel
+class PantryViewModel @Inject constructor(
+    private val pantryRepository: PantryRepository
+) : ViewModel() {
+
+    private val _uiState = MutableStateFlow(PantryUiState(isLoading = true))
+    val uiState: StateFlow<PantryUiState> = _uiState.asStateFlow()
+
+    init {
+        // Observe local cache immediately
+        viewModelScope.launch {
+            pantryRepository.getLocalItems().collect { items ->
+                _uiState.update { it.copy(items = items, isLoading = false) }
+            }
+        }
+        refresh()
+    }
+
+    fun refresh() {
+        viewModelScope.launch {
+            _uiState.update { it.copy(isLoading = true, error = null) }
+            when (val result = pantryRepository.fetchAndCacheItems()) {
+                is Result.Success -> _uiState.update { it.copy(isLoading = false) }
+                is Result.Error -> _uiState.update { it.copy(isLoading = false, error = result.toUserMessage()) }
+                is Result.NetworkError -> _uiState.update { it.copy(isLoading = false, error = null) } // Show cached, offline banner handled elsewhere
+            }
+        }
+    }
+
+    fun addItem(name: String, quantity: Int) {
+        viewModelScope.launch {
+            when (val result = pantryRepository.addItem(name.trim(), quantity)) {
+                is Result.Success -> _uiState.update { it.copy(actionSuccess = "${result.data.item.itemName} added to pantry.", actionError = null) }
+                is Result.Error -> _uiState.update { it.copy(actionError = result.toUserMessage()) }
+                is Result.NetworkError -> _uiState.update { it.copy(actionError = "No internet connection.") }
+            }
+        }
+    }
+
+    fun updateItem(id: String, quantity: Int) {
+        viewModelScope.launch {
+            when (val result = pantryRepository.updateItem(id, quantity)) {
+                is Result.Success -> _uiState.update { it.copy(actionSuccess = "Updated.", actionError = null) }
+                is Result.Error -> _uiState.update { it.copy(actionError = result.toUserMessage()) }
+                is Result.NetworkError -> _uiState.update { it.copy(actionError = "No internet connection.") }
+            }
+        }
+    }
+
+    fun deleteItem(id: String) {
+        viewModelScope.launch {
+            when (val result = pantryRepository.deleteItem(id)) {
+                is Result.Success -> _uiState.update { it.copy(actionSuccess = "Item removed.", actionError = null) }
+                is Result.Error -> _uiState.update { it.copy(actionError = result.toUserMessage()) }
+                is Result.NetworkError -> _uiState.update { it.copy(actionError = "No internet connection.") }
+            }
+        }
+    }
+
+    fun clearActionMessages() {
+        _uiState.update { it.copy(actionError = null, actionSuccess = null) }
+    }
+}

android/app/src/main/java/com/pantree/app/ui/screens/recipe/RecipeDetailScreen.kt

@@ -0,0 +1,187 @@
+package com.pantree.app.ui.screens.recipe
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.*
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.items
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.ArrowBack
+import androidx.compose.material.icons.filled.ShoppingCart
+import androidx.compose.material3.*
+import androidx.compose.runtime.*
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.text.font.FontStyle
+import androidx.compose.ui.unit.dp
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import com.pantree.app.data.model.RecipeIngredientDto
+import com.pantree.app.ui.components.ErrorState
+import com.pantree.app.ui.components.LoadingState
+import com.pantree.app.ui.theme.SuccessGreen
+
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+fun RecipeDetailScreen(
+    recipeId: String,
+    onNavigateBack: () -> Unit,
+    onAddToList: (String) -> Unit,
+    viewModel: RecipeViewModel = hiltViewModel()
+) {
+    val uiState by viewModel.detailState.collectAsStateWithLifecycle()
+
+    LaunchedEffect(recipeId) {
+        viewModel.loadRecipeDetail(recipeId)
+    }
+
+    Scaffold(
+        topBar = {
+            TopAppBar(
+                title = { Text(uiState.recipe?.name ?: "Recipe") },
+                navigationIcon = {
+                    IconButton(onClick = onNavigateBack) {
+                        Icon(Icons.Default.ArrowBack, "Back", tint = MaterialTheme.colorScheme.onPrimary)
+                    }
+                },
+                colors = TopAppBarDefaults.topAppBarColors(
+                    containerColor = MaterialTheme.colorScheme.primary,
+                    titleContentColor = MaterialTheme.colorScheme.onPrimary
+                )
+            )
+        }
+    ) { padding ->
+        when {
+            uiState.isLoading -> LoadingState(modifier = Modifier.padding(padding), message = "Loading recipe...")
+            uiState.error != null -> ErrorState(
+                modifier = Modifier.padding(padding),
+                message = uiState.error!!,
+                onRetry = { viewModel.loadRecipeDetail(recipeId) }
+            )
+            uiState.recipe != null -> {
+                val recipe = uiState.recipe!!
+                LazyColumn(
+                    modifier = Modifier.fillMaxSize().padding(padding),
+                    contentPadding = PaddingValues(16.dp),
+                    verticalArrangement = Arrangement.spacedBy(16.dp)
+                ) {
+                    // Header
+                    item {
+                        Row(verticalAlignment = Alignment.CenterVertically) {
+                            Column(modifier = Modifier.weight(1f)) {
+                                Text(recipe.name, style = MaterialTheme.typography.headlineSmall)
+                                Text(
+                                    "${recipe.scaledServings} servings",
+                                    style = MaterialTheme.typography.bodyMedium,
+                                    color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.6f)
+                                )
+                            }
+                            if (recipe.canMake) {
+                                Surface(
+                                    color = SuccessGreen.copy(alpha = 0.15f),
+                                    shape = MaterialTheme.shapes.small
+                                ) {
+                                    Text(
+                                        "\u2705 Ready to cook",
+                                        style = MaterialTheme.typography.labelLarge,
+                                        color = SuccessGreen,
+                                        modifier = Modifier.padding(horizontal = 8.dp, vertical = 4.dp)
+                                    )
+                                }
+                            }
+                        }
+                    }
+
+                    // Scale selector
+                    item {
+                        Card {
+                            Column(modifier = Modifier.padding(16.dp)) {
+                                Text("Scale recipe", style = MaterialTheme.typography.titleSmall)
+                                Spacer(Modifier.height(8.dp))
+                                Row(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
+                                    listOf(1, 2, 3).forEach { scale ->
+                                        FilterChip(
+                                            selected = uiState.scaleFactor == scale,
+                                            onClick = { viewModel.setScale(recipeId, scale) },
+                                            label = { Text("${scale}x") }
+                                        )
+                                    }
+                                }
+                            }
+                        }
+                    }
+
+                    // Ingredients
+                    item {
+                        Text(
+                            "Ingredients (${recipe.availableIngredientCount}/${recipe.ingredientCount} in pantry)",
+                            style = MaterialTheme.typography.titleMedium
+                        )
+                    }
+                    items(recipe.ingredients) { ingredient ->
+                        IngredientRow(ingredient = ingredient)
+                    }
+
+                    // Instructions
+                    item {
+                        Text("Instructions", style = MaterialTheme.typography.titleMedium)
+                    }
+                    item {
+                        Card {
+                            Text(
+                                recipe.instructions,
+                                style = MaterialTheme.typography.bodyMedium,
+                                modifier = Modifier.padding(16.dp)
+                            )
+                        }
+                    }
+
+                    // Add to shopping list button
+                    item {
+                        Spacer(Modifier.height(8.dp))
+                        Button(
+                            onClick = { /* TODO: show list picker dialog */ },
+                            modifier = Modifier.fillMaxWidth()
+                        ) {
+                            Icon(Icons.Default.ShoppingCart, contentDescription = null)
+                            Spacer(Modifier.width(8.dp))
+                            Text("Add to shopping list")
+                        }
+                        Spacer(Modifier.height(16.dp))
+                    }
+                }
+            }
+        }
+    }
+}
+
+@Composable
+fun IngredientRow(ingredient: RecipeIngredientDto) {
+    Row(
+        modifier = Modifier
+            .fillMaxWidth()
+            .background(
+                if (ingredient.inPantry) SuccessGreen.copy(alpha = 0.07f)
+                else MaterialTheme.colorScheme.surface
+            )
+            .padding(horizontal = 4.dp, vertical = 8.dp),
+        verticalAlignment = Alignment.CenterVertically
+    ) {
+        Text(
+            if (ingredient.inPantry) "\u2705" else "\u274C",
+            modifier = Modifier.width(28.dp)
+        )
+        Column(modifier = Modifier.weight(1f)) {
+            Text(ingredient.itemName, style = MaterialTheme.typography.bodyLarge)
+        }
+        Text(
+            "${formatQuantity(ingredient.quantity)} ${ingredient.unit}",
+            style = MaterialTheme.typography.bodyMedium,
+            color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.7f)
+        )
+    }
+}
+
+fun formatQuantity(qty: Double): String {
+    return if (qty == qty.toLong().toDouble()) qty.toLong().toString()
+    else String.format("%.2f", qty).trimEnd('0').trimEnd('.')
+}

android/app/src/main/java/com/pantree/app/ui/screens/recipe/RecipeViewModel.kt

@@ -0,0 +1,83 @@
+package com.pantree.app.ui.screens.recipe
+
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewModelScope
+import com.pantree.app.data.local.entity.RecipeEntity
+import com.pantree.app.data.model.RecipeDetailDto
+import com.pantree.app.data.repository.RecipeRepository
+import com.pantree.app.util.Result
+import com.pantree.app.util.toUserMessage
+import dagger.hilt.android.lifecycle.HiltViewModel
+import kotlinx.coroutines.flow.*
+import kotlinx.coroutines.launch
+import javax.inject.Inject
+
+data class RecipesUiState(
+    val isLoading: Boolean = false,
+    val recipes: List<RecipeEntity> = emptyList(),
+    val error: String? = null,
+    val currentFilter: String = "all",
+    val searchQuery: String = "",
+    val currentPage: Int = 1,
+    val totalPages: Int = 1
+)
+
+data class RecipeDetailUiState(
+    val isLoading: Boolean = false,
+    val recipe: RecipeDetailDto? = null,
+    val error: String? = null,
+    val scaleFactor: Int = 1
+)
+
+@HiltViewModel
+class RecipeViewModel @Inject constructor(
+    private val recipeRepository: RecipeRepository
+) : ViewModel() {
+
+    private val _listState = MutableStateFlow(RecipesUiState(isLoading = true))
+    val listState: StateFlow<RecipesUiState> = _listState.asStateFlow()
+
+    private val _detailState = MutableStateFlow(RecipeDetailUiState())
+    val detailState: StateFlow<RecipeDetailUiState> = _detailState.asStateFlow()
+
+    init {
+        viewModelScope.launch {
+            recipeRepository.getLocalRecipes().collect { recipes ->
+                _listState.update { it.copy(recipes = recipes, isLoading = false) }
+            }
+        }
+        fetchRecipes()
+    }
+
+    fun fetchRecipes(filter: String = _listState.value.currentFilter, search: String? = null, page: Int = 1) {
+        viewModelScope.launch {
+            _listState.update { it.copy(isLoading = true, error = null, currentFilter = filter, searchQuery = search ?: "") }
+            when (val result = recipeRepository.fetchRecipes(filter, page, search)) {
+                is Result.Success -> _listState.update {
+                    it.copy(
+                        isLoading = false,
+                        currentPage = result.data.pagination.page,
+                        totalPages = result.data.pagination.totalPages
+                    )
+                }
+                is Result.Error -> _listState.update { it.copy(isLoading = false, error = result.toUserMessage()) }
+                is Result.NetworkError -> _listState.update { it.copy(isLoading = false) }
+            }
+        }
+    }
+
+    fun loadRecipeDetail(recipeId: String, scale: Int = 1) {
+        viewModelScope.launch {
+            _detailState.value = RecipeDetailUiState(isLoading = true, scaleFactor = scale)
+            when (val result = recipeRepository.getRecipeById(recipeId, scale)) {
+                is Result.Success -> _detailState.value = RecipeDetailUiState(recipe = result.data.recipe, scaleFactor = scale)
+                is Result.Error -> _detailState.value = RecipeDetailUiState(error = result.toUserMessage())
+                is Result.NetworkError -> _detailState.value = RecipeDetailUiState(error = "No internet connection.")
+            }
+        }
+    }
+
+    fun setScale(recipeId: String, scale: Int) {
+        if (scale in 1..3) loadRecipeDetail(recipeId, scale)
+    }
+}

android/app/src/main/java/com/pantree/app/ui/screens/recipe/RecipesScreen.kt

@@ -0,0 +1,168 @@
+package com.pantree.app.ui.screens.recipe
+
+import androidx.compose.foundation.layout.*
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.items
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.ArrowBack
+import androidx.compose.material.icons.filled.Search
+import androidx.compose.material3.*
+import androidx.compose.runtime.*
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.unit.dp
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import com.pantree.app.data.local.entity.RecipeEntity
+import com.pantree.app.ui.components.EmptyState
+import com.pantree.app.ui.components.ErrorState
+import com.pantree.app.ui.components.LoadingState
+import com.pantree.app.ui.theme.SuccessGreen
+
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+fun RecipesScreen(
+    onRecipeClick: (String) -> Unit,
+    onNavigateBack: () -> Unit,
+    viewModel: RecipeViewModel = hiltViewModel()
+) {
+    val uiState by viewModel.listState.collectAsStateWithLifecycle()
+    var searchText by remember { mutableStateOf("") }
+    var showSearch by remember { mutableStateOf(false) }
+
+    Scaffold(
+        topBar = {
+            if (showSearch) {
+                TopAppBar(
+                    title = {
+                        OutlinedTextField(
+                            value = searchText,
+                            onValueChange = {
+                                searchText = it
+                                viewModel.fetchRecipes(search = it.ifBlank { null })
+                            },
+                            placeholder = { Text("Search recipes...") },
+                            singleLine = true,
+                            modifier = Modifier.fillMaxWidth(),
+                            colors = OutlinedTextFieldDefaults.colors(focusedBorderColor = Color.Transparent, unfocusedBorderColor = Color.Transparent)
+                        )
+                    },
+                    navigationIcon = {
+                        IconButton(onClick = { showSearch = false; searchText = ""; viewModel.fetchRecipes() }) {
+                            Icon(Icons.Default.ArrowBack, "Close search", tint = MaterialTheme.colorScheme.onPrimary)
+                        }
+                    },
+                    colors = TopAppBarDefaults.topAppBarColors(containerColor = MaterialTheme.colorScheme.primary)
+                )
+            } else {
+                TopAppBar(
+                    title = { Text("Recipes") },
+                    navigationIcon = { IconButton(onClick = onNavigateBack) { Icon(Icons.Default.ArrowBack, "Back", tint = MaterialTheme.colorScheme.onPrimary) } },
+                    actions = {
+                        IconButton(onClick = { showSearch = true }) {
+                            Icon(Icons.Default.Search, "Search", tint = MaterialTheme.colorScheme.onPrimary)
+                        }
+                    },
+                    colors = TopAppBarDefaults.topAppBarColors(
+                        containerColor = MaterialTheme.colorScheme.primary,
+                        titleContentColor = MaterialTheme.colorScheme.onPrimary
+                    )
+                )
+            }
+        }
+    ) { padding ->
+        Column(modifier = Modifier.fillMaxSize().padding(padding)) {
+            // Filter chips
+            Row(
+                modifier = Modifier.padding(horizontal = 16.dp, vertical = 8.dp),
+                horizontalArrangement = Arrangement.spacedBy(8.dp)
+            ) {
+                listOf("all" to "All", "can_make" to "Can make", "can_partially_make" to "Partial").forEach { (value, label) ->
+                    FilterChip(
+                        selected = uiState.currentFilter == value,
+                        onClick = { viewModel.fetchRecipes(filter = value) },
+                        label = { Text(label) }
+                    )
+                }
+            }
+
+            when {
+                uiState.isLoading && uiState.recipes.isEmpty() -> LoadingState(message = "Finding recipes...")
+                uiState.error != null && uiState.recipes.isEmpty() -> ErrorState(
+                    message = uiState.error!!,
+                    onRetry = { viewModel.fetchRecipes() }
+                )
+                uiState.recipes.isEmpty() -> EmptyState(
+                    emoji = "\uD83D\uDCDA",
+                    title = when (uiState.currentFilter) {
+                        "can_make" -> "Nothing to cook yet"
+                        "can_partially_make" -> "No partial matches"
+                        else -> "No recipes found"
+                    },
+                    subtitle = when (uiState.currentFilter) {
+                        "can_make" -> "Add more ingredients to your pantry to unlock recipes."
+                        "can_partially_make" -> "Try adding a few more pantry items."
+                        else -> "Try a different search term."
+                    }
+                )
+                else -> {
+                    LazyColumn(
+                        contentPadding = PaddingValues(16.dp),
+                        verticalArrangement = Arrangement.spacedBy(8.dp)
+                    ) {
+                        items(uiState.recipes, key = { it.id }) { recipe ->
+                            RecipeCard(recipe = recipe, onClick = { onRecipeClick(recipe.id) })
+                        }
+                        item { Spacer(Modifier.height(16.dp)) }
+                    }
+                }
+            }
+        }
+    }
+}
+
+@Composable
+fun RecipeCard(recipe: RecipeEntity, onClick: () -> Unit) {
+    Card(modifier = Modifier.fillMaxWidth(), onClick = onClick) {
+        Column(modifier = Modifier.padding(16.dp)) {
+            Row(verticalAlignment = Alignment.CenterVertically) {
+                Text(recipe.name, style = MaterialTheme.typography.titleMedium, modifier = Modifier.weight(1f))
+                if (recipe.canMake) {
+                    Surface(
+                        color = SuccessGreen.copy(alpha = 0.15f),
+                        shape = MaterialTheme.shapes.small
+                    ) {
+                        Text(
+                            "\u2705 Can make",
+                            style = MaterialTheme.typography.labelLarge,
+                            color = SuccessGreen,
+                            modifier = Modifier.padding(horizontal = 8.dp, vertical = 4.dp)
+                        )
+                    }
+                }
+            }
+            Spacer(Modifier.height(8.dp))
+            Row(horizontalArrangement = Arrangement.spacedBy(16.dp)) {
+                Text(
+                    "${recipe.servings} servings",
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.6f)
+                )
+                Text(
+                    "${recipe.availableIngredientCount}/${recipe.ingredientCount} ingredients",
+                    style = MaterialTheme.typography.bodySmall,
+                    color = if (recipe.canMake) SuccessGreen else MaterialTheme.colorScheme.onSurface.copy(alpha = 0.6f)
+                )
+            }
+            if (!recipe.canMake && recipe.ingredientCount > 0) {
+                Spacer(Modifier.height(8.dp))
+                LinearProgressIndicator(
+                    progress = { (recipe.availabilityPercentage / 100f).toFloat() },
+                    modifier = Modifier.fillMaxWidth(),
+                    color = MaterialTheme.colorScheme.primary
+                )
+            }
+        }
+    }
+}

android/app/src/main/java/com/pantree/app/ui/screens/settings/SettingsScreen.kt

@@ -0,0 +1,132 @@
+package com.pantree.app.ui.screens.settings
+
+import androidx.compose.foundation.layout.*
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.ArrowBack
+import androidx.compose.material3.*
+import androidx.compose.runtime.*
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+fun SettingsScreen(
+    onSignOut: () -> Unit,
+    onNavigateBack: () -> Unit,
+    viewModel: SettingsViewModel = hiltViewModel()
+) {
+    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
+    var showDeleteConfirm by remember { mutableStateOf(false) }
+
+    LaunchedEffect(uiState.signedOut) { if (uiState.signedOut) onSignOut() }
+    LaunchedEffect(uiState.accountDeleted) { if (uiState.accountDeleted) onSignOut() }
+
+    Scaffold(
+        topBar = {
+            TopAppBar(
+                title = { Text("Settings") },
+                navigationIcon = {
+                    IconButton(onClick = onNavigateBack) {
+                        Icon(Icons.Default.ArrowBack, "Back", tint = MaterialTheme.colorScheme.onPrimary)
+                    }
+                },
+                colors = TopAppBarDefaults.topAppBarColors(
+                    containerColor = MaterialTheme.colorScheme.primary,
+                    titleContentColor = MaterialTheme.colorScheme.onPrimary
+                )
+            )
+        }
+    ) { padding ->
+        Column(
+            modifier = Modifier.fillMaxSize().padding(padding).padding(16.dp),
+            verticalArrangement = Arrangement.spacedBy(8.dp)
+        ) {
+            if (uiState.error != null) {
+                Card(
+                    colors = CardDefaults.cardColors(containerColor = MaterialTheme.colorScheme.errorContainer),
+                    modifier = Modifier.fillMaxWidth()
+                ) {
+                    Text(
+                        uiState.error!!,
+                        modifier = Modifier.padding(12.dp),
+                        color = MaterialTheme.colorScheme.onErrorContainer
+                    )
+                }
+            }
+
+            Spacer(Modifier.height(8.dp))
+            Text("Account", style = MaterialTheme.typography.titleSmall, color = MaterialTheme.colorScheme.primary)
+            Spacer(Modifier.height(4.dp))
+
+            Card(modifier = Modifier.fillMaxWidth()) {
+                Column {
+                    ListItem(
+                        headlineContent = { Text("Sign out") },
+                        supportingContent = { Text("You can sign back in anytime.") },
+                        modifier = Modifier.fillMaxWidth()
+                    )
+                    Button(
+                        onClick = { viewModel.signOut() },
+                        modifier = Modifier.fillMaxWidth().padding(horizontal = 16.dp, vertical = 8.dp)
+                    ) {
+                        Text("Sign out")
+                    }
+                }
+            }
+
+            Spacer(Modifier.height(16.dp))
+            Text("Danger zone", style = MaterialTheme.typography.titleSmall, color = MaterialTheme.colorScheme.error)
+            Spacer(Modifier.height(4.dp))
+
+            Card(
+                modifier = Modifier.fillMaxWidth(),
+                colors = CardDefaults.cardColors(containerColor = MaterialTheme.colorScheme.errorContainer.copy(alpha = 0.3f))
+            ) {
+                Column(modifier = Modifier.padding(16.dp), verticalArrangement = Arrangement.spacedBy(8.dp)) {
+                    Text("Delete account", style = MaterialTheme.typography.titleMedium)
+                    Text(
+                        "Your account will be scheduled for deletion. You have 15 days to change your mind — just sign back in.",
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.7f)
+                    )
+                    OutlinedButton(
+                        onClick = { showDeleteConfirm = true },
+                        enabled = !uiState.isLoading,
+                        colors = ButtonDefaults.outlinedButtonColors(contentColor = MaterialTheme.colorScheme.error),
+                        modifier = Modifier.fillMaxWidth()
+                    ) {
+                        if (uiState.isLoading) {
+                            CircularProgressIndicator(modifier = Modifier.size(18.dp))
+                        } else {
+                            Text("Delete my account")
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    if (showDeleteConfirm) {
+        AlertDialog(
+            onDismissRequest = { showDeleteConfirm = false },
+            title = { Text("Delete account?") },
+            text = {
+                Text(
+                    "This will schedule your account for permanent deletion in 15 days. " +
+                    "All your pantry items, recipes, and shopping lists will be removed. " +
+                    "Sign back in within 15 days to cancel."
+                )
+            },
+            confirmButton = {
+                TextButton(onClick = { viewModel.deleteAccount(); showDeleteConfirm = false }) {
+                    Text("Yes, delete", color = MaterialTheme.colorScheme.error)
+                }
+            },
+            dismissButton = {
+                TextButton(onClick = { showDeleteConfirm = false }) { Text("Keep my account") }
+            }
+        )
+    }
+}

android/app/src/main/java/com/pantree/app/ui/screens/settings/SettingsViewModel.kt

@@ -0,0 +1,51 @@
+package com.pantree.app.ui.screens.settings
+
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewModelScope
+import com.pantree.app.data.repository.AuthRepository
+import com.pantree.app.util.Result
+import com.pantree.app.util.toUserMessage
+import dagger.hilt.android.lifecycle.HiltViewModel
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.flow.update
+import kotlinx.coroutines.launch
+import javax.inject.Inject
+
+data class SettingsUiState(
+    val isLoading: Boolean = false,
+    val error: String? = null,
+    val signedOut: Boolean = false,
+    val accountDeleted: Boolean = false
+)
+
+@HiltViewModel
+class SettingsViewModel @Inject constructor(
+    private val authRepository: AuthRepository
+) : ViewModel() {
+
+    private val _uiState = MutableStateFlow(SettingsUiState())
+    val uiState: StateFlow<SettingsUiState> = _uiState.asStateFlow()
+
+    fun signOut() {
+        authRepository.logout()
+        _uiState.update { it.copy(signedOut = true) }
+    }
+
+    fun deleteAccount() {
+        viewModelScope.launch {
+            _uiState.update { it.copy(isLoading = true) }
+            when (val result = authRepository.deleteAccount()) {
+                is Result.Success -> {
+                    authRepository.logout()
+                    _uiState.update { it.copy(isLoading = false, accountDeleted = true) }
+                }
+                is Result.Error -> _uiState.update { it.copy(isLoading = false, error = result.toUserMessage()) }
+                is Result.NetworkError -> _uiState.update { it.copy(isLoading = false, error = "No internet connection.") }
+            }
+        }
+    }
+
+    fun clearError() = _uiState.update { it.copy(error = null) }
+}

android/app/src/main/java/com/pantree/app/ui/screens/shopping/ShoppingListDetailScreen.kt

@@ -0,0 +1,305 @@
+package com.pantree.app.ui.screens.shopping
+
+import androidx.compose.foundation.layout.*
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.items
+import androidx.compose.foundation.text.KeyboardOptions
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.*
+import androidx.compose.material3.*
+import androidx.compose.runtime.*
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.text.input.KeyboardType
+import androidx.compose.ui.text.style.TextDecoration
+import androidx.compose.ui.unit.dp
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import com.pantree.app.data.local.entity.ShoppingListItemEntity
+import com.pantree.app.ui.components.EmptyState
+import com.pantree.app.ui.components.ErrorState
+import com.pantree.app.ui.components.LoadingState
+
+val ALLOWED_UNITS = listOf(
+    "cups", "tbsp", "tsp", "oz", "fl_oz",
+    "g", "kg", "ml", "l",
+    "pieces", "slices", "cloves", "pinch",
+    "whole", "can", "package", "bunch"
+)
+
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+fun ShoppingListDetailScreen(
+    listId: String,
+    onNavigateBack: () -> Unit,
+    onNavigateToRecipes: () -> Unit,
+    viewModel: ShoppingListViewModel = hiltViewModel()
+) {
+    val uiState by viewModel.detailState.collectAsStateWithLifecycle()
+    var showAddItemDialog by remember { mutableStateOf(false) }
+    var deletingItemId by remember { mutableStateOf<String?>(null) }
+    val snackbarHostState = remember { SnackbarHostState() }
+
+    LaunchedEffect(listId) { viewModel.loadListDetail(listId) }
+
+    LaunchedEffect(uiState.actionSuccess) {
+        uiState.actionSuccess?.let { snackbarHostState.showSnackbar(it); viewModel.clearDetailMessages() }
+    }
+    LaunchedEffect(uiState.actionError) {
+        uiState.actionError?.let { snackbarHostState.showSnackbar(it); viewModel.clearDetailMessages() }
+    }
+    LaunchedEffect(uiState.addRecipesSuccess) {
+        uiState.addRecipesSuccess?.let { snackbarHostState.showSnackbar(it); viewModel.clearDetailMessages() }
+    }
+
+    val uncheckedItems = uiState.items.filter { !it.checkedOff }
+    val checkedItems = uiState.items.filter { it.checkedOff }
+
+    Scaffold(
+        topBar = {
+            TopAppBar(
+                title = { Text(uiState.listName.ifBlank { "Shopping List" }) },
+                navigationIcon = {
+                    IconButton(onClick = onNavigateBack) {
+                        Icon(Icons.Default.ArrowBack, "Back", tint = MaterialTheme.colorScheme.onPrimary)
+                    }
+                },
+                actions = {
+                    IconButton(onClick = onNavigateToRecipes) {
+                        Icon(Icons.Default.MenuBook, "Add from recipes", tint = MaterialTheme.colorScheme.onPrimary)
+                    }
+                },
+                colors = TopAppBarDefaults.topAppBarColors(
+                    containerColor = MaterialTheme.colorScheme.primary,
+                    titleContentColor = MaterialTheme.colorScheme.onPrimary
+                )
+            )
+        },
+        floatingActionButton = {
+            FloatingActionButton(onClick = { showAddItemDialog = true }) {
+                Icon(Icons.Default.Add, "Add item")
+            }
+        },
+        snackbarHost = { SnackbarHost(snackbarHostState) }
+    ) { padding ->
+        Box(modifier = Modifier.fillMaxSize().padding(padding)) {
+            when {
+                uiState.isLoading && uiState.items.isEmpty() -> LoadingState(message = "Loading list...")
+                uiState.error != null && uiState.items.isEmpty() -> ErrorState(
+                    message = uiState.error!!,
+                    onRetry = { viewModel.loadListDetail(listId) }
+                )
+                uiState.items.isEmpty() -> EmptyState(
+                    emoji = "\uD83D\uDCCB",
+                    title = "This list is empty",
+                    subtitle = "Add items manually or pull in ingredients from a recipe.",
+                    actionLabel = "Add an item",
+                    onAction = { showAddItemDialog = true }
+                )
+                else -> {
+                    LazyColumn(
+                        contentPadding = PaddingValues(16.dp),
+                        verticalArrangement = Arrangement.spacedBy(6.dp)
+                    ) {
+                        // Progress summary
+                        item {
+                            if (uiState.items.isNotEmpty()) {
+                                val progress = checkedItems.size.toFloat() / uiState.items.size
+                                Column(verticalArrangement = Arrangement.spacedBy(4.dp)) {
+                                    Text(
+                                        "${checkedItems.size} of ${uiState.items.size} checked",
+                                        style = MaterialTheme.typography.bodySmall,
+                                        color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.6f)
+                                    )
+                                    LinearProgressIndicator(
+                                        progress = { progress },
+                                        modifier = Modifier.fillMaxWidth()
+                                    )
+                                    Spacer(Modifier.height(8.dp))
+                                }
+                            }
+                        }
+
+                        // Unchecked items
+                        items(uncheckedItems, key = { it.id }) { item ->
+                            ShoppingListItemRow(
+                                item = item,
+                                onToggle = { viewModel.toggleCheckOff(listId, item) },
+                                onDelete = { deletingItemId = item.id }
+                            )
+                        }
+
+                        // Checked items section
+                        if (checkedItems.isNotEmpty()) {
+                            item {
+                                Spacer(Modifier.height(8.dp))
+                                Text(
+                                    "In cart (${checkedItems.size})",
+                                    style = MaterialTheme.typography.labelLarge,
+                                    color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.5f)
+                                )
+                                Spacer(Modifier.height(4.dp))
+                            }
+                            items(checkedItems, key = { it.id }) { item ->
+                                ShoppingListItemRow(
+                                    item = item,
+                                    onToggle = { viewModel.toggleCheckOff(listId, item) },
+                                    onDelete = { deletingItemId = item.id }
+                                )
+                            }
+                        }
+
+                        item { Spacer(Modifier.height(80.dp)) }
+                    }
+                }
+            }
+        }
+    }
+
+    if (showAddItemDialog) {
+        AddShoppingItemDialog(
+            onDismiss = { showAddItemDialog = false },
+            onConfirm = { name, qty, unit ->
+                viewModel.addItem(listId, name, qty, unit)
+                showAddItemDialog = false
+            }
+        )
+    }
+
+    deletingItemId?.let { itemId ->
+        AlertDialog(
+            onDismissRequest = { deletingItemId = null },
+            title = { Text("Remove item?") },
+            text = { Text("Remove this item from the list?") },
+            confirmButton = {
+                TextButton(onClick = { viewModel.deleteItem(listId, itemId); deletingItemId = null }) {
+                    Text("Remove", color = MaterialTheme.colorScheme.error)
+                }
+            },
+            dismissButton = { TextButton(onClick = { deletingItemId = null }) { Text("Cancel") } }
+        )
+    }
+}
+
+@Composable
+fun ShoppingListItemRow(
+    item: ShoppingListItemEntity,
+    onToggle: () -> Unit,
+    onDelete: () -> Unit
+) {
+    Card(
+        modifier = Modifier.fillMaxWidth(),
+        colors = CardDefaults.cardColors(
+            containerColor = if (item.checkedOff)
+                MaterialTheme.colorScheme.surfaceVariant.copy(alpha = 0.5f)
+            else MaterialTheme.colorScheme.surface
+        )
+    ) {
+        Row(
+            modifier = Modifier.padding(horizontal = 8.dp, vertical = 4.dp),
+            verticalAlignment = Alignment.CenterVertically
+        ) {
+            Checkbox(
+                checked = item.checkedOff,
+                onCheckedChange = { onToggle() }
+            )
+            Column(modifier = Modifier.weight(1f)) {
+                Text(
+                    item.itemName,
+                    style = MaterialTheme.typography.bodyLarge.copy(
+                        textDecoration = if (item.checkedOff) TextDecoration.LineThrough else null
+                    ),
+                    color = if (item.checkedOff)
+                        MaterialTheme.colorScheme.onSurface.copy(alpha = 0.4f)
+                    else MaterialTheme.colorScheme.onSurface
+                )
+                Text(
+                    "${formatQty(item.quantity)} ${item.unit}",
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.5f)
+                )
+            }
+            IconButton(onClick = onDelete) {
+                Icon(
+                    Icons.Default.Close,
+                    contentDescription = "Remove",
+                    tint = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.4f)
+                )
+            }
+        }
+    }
+}
+
+fun formatQty(qty: Double): String =
+    if (qty == qty.toLong().toDouble()) qty.toLong().toString()
+    else String.format("%.2f", qty).trimEnd('0').trimEnd('.')
+
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+fun AddShoppingItemDialog(onDismiss: () -> Unit, onConfirm: (String, Double, String) -> Unit) {
+    var name by remember { mutableStateOf("") }
+    var quantityText by remember { mutableStateOf("1") }
+    var selectedUnit by remember { mutableStateOf("pieces") }
+    var unitExpanded by remember { mutableStateOf(false) }
+    val quantity = quantityText.toDoubleOrNull()
+    val isValid = name.isNotBlank() && quantity != null && quantity > 0
+
+    AlertDialog(
+        onDismissRequest = onDismiss,
+        title = { Text("Add item") },
+        text = {
+            Column(verticalArrangement = Arrangement.spacedBy(12.dp)) {
+                OutlinedTextField(
+                    value = name,
+                    onValueChange = { name = it },
+                    label = { Text("Item name") },
+                    singleLine = true,
+                    modifier = Modifier.fillMaxWidth()
+                )
+                Row(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
+                    OutlinedTextField(
+                        value = quantityText,
+                        onValueChange = { quantityText = it },
+                        label = { Text("Qty") },
+                        keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Decimal),
+                        singleLine = true,
+                        isError = quantityText.isNotEmpty() && quantity == null,
+                        modifier = Modifier.weight(1f)
+                    )
+                    ExposedDropdownMenuBox(
+                        expanded = unitExpanded,
+                        onExpandedChange = { unitExpanded = it },
+                        modifier = Modifier.weight(1.5f)
+                    ) {
+                        OutlinedTextField(
+                            value = selectedUnit,
+                            onValueChange = {},
+                            readOnly = true,
+                            label = { Text("Unit") },
+                            trailingIcon = { ExposedDropdownMenuDefaults.TrailingIcon(expanded = unitExpanded) },
+                            modifier = Modifier.menuAnchor()
+                        )
+                        ExposedDropdownMenu(
+                            expanded = unitExpanded,
+                            onDismissRequest = { unitExpanded = false }
+                        ) {
+                            ALLOWED_UNITS.forEach { unit ->
+                                DropdownMenuItem(
+                                    text = { Text(unit) },
+                                    onClick = { selectedUnit = unit; unitExpanded = false }
+                                )
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        confirmButton = {
+            TextButton(
+                onClick = { if (isValid) onConfirm(name, quantity!!, selectedUnit) },
+                enabled = isValid
+            ) { Text("Add") }
+        },
+        dismissButton = { TextButton(onClick = onDismiss) { Text("Cancel") } }
+    )
+}

android/app/src/main/java/com/pantree/app/ui/screens/shopping/ShoppingListViewModel.kt

@@ -0,0 +1,148 @@
+package com.pantree.app.ui.screens.shopping
+
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewModelScope
+import com.pantree.app.data.local.entity.ShoppingListEntity
+import com.pantree.app.data.local.entity.ShoppingListItemEntity
+import com.pantree.app.data.repository.ShoppingListRepository
+import com.pantree.app.util.Result
+import com.pantree.app.util.toUserMessage
+import dagger.hilt.android.lifecycle.HiltViewModel
+import kotlinx.coroutines.flow.*
+import kotlinx.coroutines.launch
+import javax.inject.Inject
+
+data class ShoppingListsUiState(
+    val isLoading: Boolean = false,
+    val lists: List<ShoppingListEntity> = emptyList(),
+    val error: String? = null,
+    val actionError: String? = null,
+    val actionSuccess: String? = null
+)
+
+data class ShoppingListDetailUiState(
+    val isLoading: Boolean = false,
+    val listName: String = "",
+    val items: List<ShoppingListItemEntity> = emptyList(),
+    val error: String? = null,
+    val actionError: String? = null,
+    val actionSuccess: String? = null,
+    val addRecipesSuccess: String? = null
+)
+
+@HiltViewModel
+class ShoppingListViewModel @Inject constructor(
+    private val shoppingListRepository: ShoppingListRepository
+) : ViewModel() {
+
+    private val _listsState = MutableStateFlow(ShoppingListsUiState(isLoading = true))
+    val listsState: StateFlow<ShoppingListsUiState> = _listsState.asStateFlow()
+
+    private val _detailState = MutableStateFlow(ShoppingListDetailUiState())
+    val detailState: StateFlow<ShoppingListDetailUiState> = _detailState.asStateFlow()
+
+    init {
+        viewModelScope.launch {
+            shoppingListRepository.getLocalLists().collect { lists ->
+                _listsState.update { it.copy(lists = lists, isLoading = false) }
+            }
+        }
+        fetchLists()
+    }
+
+    fun fetchLists() {
+        viewModelScope.launch {
+            _listsState.update { it.copy(isLoading = true, error = null) }
+            when (val result = shoppingListRepository.fetchLists()) {
+                is Result.Success -> _listsState.update { it.copy(isLoading = false) }
+                is Result.Error -> _listsState.update { it.copy(isLoading = false, error = result.toUserMessage()) }
+                is Result.NetworkError -> _listsState.update { it.copy(isLoading = false) }
+            }
+        }
+    }
+
+    fun createList(name: String) {
+        viewModelScope.launch {
+            when (val result = shoppingListRepository.createList(name.trim())) {
+                is Result.Success -> _listsState.update { it.copy(actionSuccess = "\"${result.data.shoppingList.listName}\" created.") }
+                is Result.Error -> _listsState.update { it.copy(actionError = result.toUserMessage()) }
+                is Result.NetworkError -> _listsState.update { it.copy(actionError = "No internet connection.") }
+            }
+        }
+    }
+
+    fun deleteList(listId: String) {
+        viewModelScope.launch {
+            when (val result = shoppingListRepository.deleteList(listId)) {
+                is Result.Success -> _listsState.update { it.copy(actionSuccess = "List deleted.") }
+                is Result.Error -> _listsState.update { it.copy(actionError = result.toUserMessage()) }
+                is Result.NetworkError -> _listsState.update { it.copy(actionError = "No internet connection.") }
+            }
+        }
+    }
+
+    fun loadListDetail(listId: String) {
+        viewModelScope.launch {
+            _detailState.update { it.copy(isLoading = true, error = null) }
+            // Observe local items immediately
+            launch {
+                shoppingListRepository.getLocalItems(listId).collect { items ->
+                    _detailState.update { it.copy(items = items, isLoading = false) }
+                }
+            }
+            when (val result = shoppingListRepository.fetchListById(listId)) {
+                is Result.Success -> _detailState.update {
+                    it.copy(isLoading = false, listName = result.data.shoppingList.listName)
+                }
+                is Result.Error -> _detailState.update { it.copy(isLoading = false, error = result.toUserMessage()) }
+                is Result.NetworkError -> _detailState.update { it.copy(isLoading = false) }
+            }
+        }
+    }
+
+    fun addItem(listId: String, name: String, quantity: Double, unit: String) {
+        viewModelScope.launch {
+            when (val result = shoppingListRepository.addItem(listId, name.trim(), quantity, unit)) {
+                is Result.Success -> {
+                    val msg = if (result.data.merged == true)
+                        "Merged with existing ${result.data.item.itemName}."
+                    else "${result.data.item.itemName} added."
+                    _detailState.update { it.copy(actionSuccess = msg, actionError = null) }
+                }
+                is Result.Error -> _detailState.update { it.copy(actionError = result.toUserMessage()) }
+                is Result.NetworkError -> _detailState.update { it.copy(actionError = "No internet connection.") }
+            }
+        }
+    }
+
+    fun addRecipesToList(listId: String, recipeIds: List<String>, scaleFactor: Int) {
+        viewModelScope.launch {
+            when (val result = shoppingListRepository.addRecipesToList(listId, recipeIds, scaleFactor)) {
+                is Result.Success -> _detailState.update {
+                    it.copy(addRecipesSuccess = "Added ${result.data.recipesAdded} recipe(s). ${result.data.itemsMerged} items merged, ${result.data.itemsCreated} new.")
+                }
+                is Result.Error -> _detailState.update { it.copy(actionError = result.toUserMessage()) }
+                is Result.NetworkError -> _detailState.update { it.copy(actionError = "No internet connection.") }
+            }
+        }
+    }
+
+    fun toggleCheckOff(listId: String, item: ShoppingListItemEntity) {
+        viewModelScope.launch {
+            shoppingListRepository.updateItem(listId, item.id, checkedOff = !item.checkedOff)
+        }
+    }
+
+    fun deleteItem(listId: String, itemId: String) {
+        viewModelScope.launch {
+            when (val result = shoppingListRepository.deleteItem(listId, itemId)) {
+                is Result.Success -> _detailState.update { it.copy(actionSuccess = "Item removed.") }
+                is Result.Error -> _detailState.update { it.copy(actionError = result.toUserMessage()) }
+                is Result.NetworkError -> _detailState.update { it.copy(actionError = "No internet connection.") }
+            }
+        }
+    }
+
+    fun clearListsMessages() = _listsState.update { it.copy(actionError = null, actionSuccess = null) }
+    fun clearDetailMessages() = _detailState.update { it.copy(actionError = null, actionSuccess = null, addRecipesSuccess = null) }
+}

android/app/src/main/java/com/pantree/app/ui/screens/shopping/ShoppingListsScreen.kt

@@ -0,0 +1,175 @@
+package com.pantree.app.ui.screens.shopping
+
+import androidx.compose.foundation.layout.*
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.items
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.*
+import androidx.compose.material3.*
+import androidx.compose.runtime.*
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import com.pantree.app.data.local.entity.ShoppingListEntity
+import com.pantree.app.ui.components.EmptyState
+import com.pantree.app.ui.components.ErrorState
+import com.pantree.app.ui.components.LoadingState
+
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+fun ShoppingListsScreen(
+    onListClick: (String) -> Unit,
+    onNavigateBack: () -> Unit,
+    viewModel: ShoppingListViewModel = hiltViewModel()
+) {
+    val uiState by viewModel.listsState.collectAsStateWithLifecycle()
+    var showCreateDialog by remember { mutableStateOf(false) }
+    var deletingList by remember { mutableStateOf<ShoppingListEntity?>(null) }
+    val snackbarHostState = remember { SnackbarHostState() }
+
+    LaunchedEffect(uiState.actionSuccess) {
+        uiState.actionSuccess?.let { snackbarHostState.showSnackbar(it); viewModel.clearListsMessages() }
+    }
+    LaunchedEffect(uiState.actionError) {
+        uiState.actionError?.let { snackbarHostState.showSnackbar(it); viewModel.clearListsMessages() }
+    }
+
+    Scaffold(
+        topBar = {
+            TopAppBar(
+                title = { Text("Shopping Lists") },
+                navigationIcon = {
+                    IconButton(onClick = onNavigateBack) {
+                        Icon(Icons.Default.ArrowBack, "Back", tint = MaterialTheme.colorScheme.onPrimary)
+                    }
+                },
+                colors = TopAppBarDefaults.topAppBarColors(
+                    containerColor = MaterialTheme.colorScheme.primary,
+                    titleContentColor = MaterialTheme.colorScheme.onPrimary
+                )
+            )
+        },
+        floatingActionButton = {
+            FloatingActionButton(onClick = { showCreateDialog = true }) {
+                Icon(Icons.Default.Add, "Create list")
+            }
+        },
+        snackbarHost = { SnackbarHost(snackbarHostState) }
+    ) { padding ->
+        Box(modifier = Modifier.fillMaxSize().padding(padding)) {
+            when {
+                uiState.isLoading && uiState.lists.isEmpty() -> LoadingState(message = "Loading your lists...")
+                uiState.error != null && uiState.lists.isEmpty() -> ErrorState(
+                    message = uiState.error!!,
+                    onRetry = { viewModel.fetchLists() }
+                )
+                uiState.lists.isEmpty() -> EmptyState(
+                    emoji = "\uD83D\uDED2",
+                    title = "No shopping lists yet",
+                    subtitle = "Create a list to start planning your next grocery run.",
+                    actionLabel = "Create a list",
+                    onAction = { showCreateDialog = true }
+                )
+                else -> {
+                    LazyColumn(
+                        contentPadding = PaddingValues(16.dp),
+                        verticalArrangement = Arrangement.spacedBy(8.dp)
+                    ) {
+                        items(uiState.lists, key = { it.id }) { list ->
+                            ShoppingListCard(
+                                list = list,
+                                onClick = { onListClick(list.id) },
+                                onDelete = { deletingList = list }
+                            )
+                        }
+                        item { Spacer(Modifier.height(80.dp)) }
+                    }
+                }
+            }
+        }
+    }
+
+    if (showCreateDialog) {
+        CreateListDialog(
+            onDismiss = { showCreateDialog = false },
+            onConfirm = { name -> viewModel.createList(name); showCreateDialog = false }
+        )
+    }
+
+    deletingList?.let { list ->
+        AlertDialog(
+            onDismissRequest = { deletingList = null },
+            title = { Text("Delete list?") },
+            text = { Text("\"${list.listName}\" and all its items will be permanently deleted.") },
+            confirmButton = {
+                TextButton(onClick = { viewModel.deleteList(list.id); deletingList = null }) {
+                    Text("Delete", color = MaterialTheme.colorScheme.error)
+                }
+            },
+            dismissButton = { TextButton(onClick = { deletingList = null }) { Text("Cancel") } }
+        )
+    }
+}
+
+@Composable
+fun ShoppingListCard(
+    list: ShoppingListEntity,
+    onClick: () -> Unit,
+    onDelete: () -> Unit
+) {
+    Card(modifier = Modifier.fillMaxWidth(), onClick = onClick) {
+        Row(
+            modifier = Modifier.padding(horizontal = 16.dp, vertical = 12.dp),
+            verticalAlignment = Alignment.CenterVertically
+        ) {
+            Column(modifier = Modifier.weight(1f)) {
+                Text(list.listName, style = MaterialTheme.typography.titleMedium)
+                Spacer(Modifier.height(4.dp))
+                Row(horizontalArrangement = Arrangement.spacedBy(12.dp)) {
+                    Text(
+                        "${list.itemCount} item${if (list.itemCount != 1) "s" else ""}",
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.6f)
+                    )
+                    if (list.checkedCount > 0) {
+                        Text(
+                            "${list.checkedCount} checked",
+                            style = MaterialTheme.typography.bodySmall,
+                            color = MaterialTheme.colorScheme.primary
+                        )
+                    }
+                }
+            }
+            Icon(Icons.Default.ChevronRight, contentDescription = null, tint = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.4f))
+            IconButton(onClick = onDelete) {
+                Icon(Icons.Default.Delete, "Delete", tint = MaterialTheme.colorScheme.error)
+            }
+        }
+    }
+}
+
+@Composable
+fun CreateListDialog(onDismiss: () -> Unit, onConfirm: (String) -> Unit) {
+    var name by remember { mutableStateOf("") }
+    AlertDialog(
+        onDismissRequest = onDismiss,
+        title = { Text("New shopping list") },
+        text = {
+            OutlinedTextField(
+                value = name,
+                onValueChange = { name = it },
+                label = { Text("List name") },
+                singleLine = true,
+                modifier = Modifier.fillMaxWidth()
+            )
+        },
+        confirmButton = {
+            TextButton(onClick = { if (name.isNotBlank()) onConfirm(name) }, enabled = name.isNotBlank()) {
+                Text("Create")
+            }
+        },
+        dismissButton = { TextButton(onClick = onDismiss) { Text("Cancel") } }
+    )
+}

android/app/src/main/java/com/pantree/app/ui/theme/Color.kt

@@ -0,0 +1,24 @@
+package com.pantree.app.ui.theme
+
+import androidx.compose.ui.graphics.Color
+
+// Brand palette
+val PantreeGreen = Color(0xFF2D6A4F)
+val PantreeGreenLight = Color(0xFF52B788)
+val PantreeGreenDark = Color(0xFF1B4332)
+val PantreeCream = Color(0xFFF8F4EF)
+val PantreeOrange = Color(0xFFE76F51)
+val PantreeOrangeLight = Color(0xFFF4A261)
+
+// Semantic
+val SuccessGreen = Color(0xFF40916C)
+val ErrorRed = Color(0xFFD62828)
+val WarningAmber = Color(0xFFF4A261)
+val NeutralGray = Color(0xFF6B7280)
+val SurfaceWhite = Color(0xFFFFFFFF)
+val BackgroundCream = Color(0xFFF8F4EF)
+
+// Dark theme
+val PantreeGreenDarkTheme = Color(0xFF52B788)
+val SurfaceDark = Color(0xFF1C1C1E)
+val BackgroundDark = Color(0xFF121212)

android/app/src/main/java/com/pantree/app/ui/theme/Theme.kt

@@ -0,0 +1,65 @@
+package com.pantree.app.ui.theme
+
+import android.app.Activity
+import androidx.compose.foundation.isSystemInDarkTheme
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.darkColorScheme
+import androidx.compose.material3.lightColorScheme
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.SideEffect
+import androidx.compose.ui.graphics.toArgb
+import androidx.compose.ui.platform.LocalView
+import androidx.core.view.WindowCompat
+
+private val LightColorScheme = lightColorScheme(
+    primary = PantreeGreen,
+    onPrimary = SurfaceWhite,
+    primaryContainer = PantreeGreenLight,
+    onPrimaryContainer = PantreeGreenDark,
+    secondary = PantreeOrange,
+    onSecondary = SurfaceWhite,
+    secondaryContainer = PantreeOrangeLight,
+    background = BackgroundCream,
+    onBackground = PantreeGreenDark,
+    surface = SurfaceWhite,
+    onSurface = PantreeGreenDark,
+    error = ErrorRed,
+    onError = SurfaceWhite,
+    outline = NeutralGray
+)
+
+private val DarkColorScheme = darkColorScheme(
+    primary = PantreeGreenDarkTheme,
+    onPrimary = PantreeGreenDark,
+    primaryContainer = PantreeGreenDark,
+    onPrimaryContainer = PantreeGreenLight,
+    secondary = PantreeOrangeLight,
+    onSecondary = SurfaceDark,
+    background = BackgroundDark,
+    onBackground = PantreeCream,
+    surface = SurfaceDark,
+    onSurface = PantreeCream,
+    error = ErrorRed,
+    onError = SurfaceWhite
+)
+
+@Composable
+fun PantreeTheme(
+    darkTheme: Boolean = isSystemInDarkTheme(),
+    content: @Composable () -> Unit
+) {
+    val colorScheme = if (darkTheme) DarkColorScheme else LightColorScheme
+    val view = LocalView.current
+    if (!view.isInEditMode) {
+        SideEffect {
+            val window = (view.context as Activity).window
+            window.statusBarColor = colorScheme.primary.toArgb()
+            WindowCompat.getInsetsController(window, view).isAppearanceLightStatusBars = !darkTheme
+        }
+    }
+    MaterialTheme(
+        colorScheme = colorScheme,
+        typography = PantreeTypography,
+        content = content
+    )
+}

android/app/src/main/java/com/pantree/app/ui/theme/Type.kt

@@ -0,0 +1,54 @@
+package com.pantree.app.ui.theme
+
+import androidx.compose.material3.Typography
+import androidx.compose.ui.text.TextStyle
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.sp
+
+val PantreeTypography = Typography(
+    headlineLarge = TextStyle(
+        fontWeight = FontWeight.Bold,
+        fontSize = 32.sp,
+        lineHeight = 40.sp
+    ),
+    headlineMedium = TextStyle(
+        fontWeight = FontWeight.SemiBold,
+        fontSize = 24.sp,
+        lineHeight = 32.sp
+    ),
+    headlineSmall = TextStyle(
+        fontWeight = FontWeight.SemiBold,
+        fontSize = 20.sp,
+        lineHeight = 28.sp
+    ),
+    titleLarge = TextStyle(
+        fontWeight = FontWeight.SemiBold,
+        fontSize = 18.sp,
+        lineHeight = 24.sp
+    ),
+    titleMedium = TextStyle(
+        fontWeight = FontWeight.Medium,
+        fontSize = 16.sp,
+        lineHeight = 22.sp
+    ),
+    bodyLarge = TextStyle(
+        fontWeight = FontWeight.Normal,
+        fontSize = 16.sp,
+        lineHeight = 24.sp
+    ),
+    bodyMedium = TextStyle(
+        fontWeight = FontWeight.Normal,
+        fontSize = 14.sp,
+        lineHeight = 20.sp
+    ),
+    bodySmall = TextStyle(
+        fontWeight = FontWeight.Normal,
+        fontSize = 12.sp,
+        lineHeight = 16.sp
+    ),
+    labelLarge = TextStyle(
+        fontWeight = FontWeight.Medium,
+        fontSize = 14.sp,
+        lineHeight = 20.sp
+    )
+)

android/app/src/main/java/com/pantree/app/util/Result.kt

@@ -0,0 +1,58 @@
+package com.pantree.app.util
+
+import com.google.gson.Gson
+import com.pantree.app.data.model.ApiError
+import retrofit2.Response
+
+sealed class Result<out T> {
+    data class Success<T>(val data: T) : Result<T>()
+    data class Error(val code: String, val message: String, val httpStatus: Int = 0) : Result<Nothing>()
+    object NetworkError : Result<Nothing>()
+}
+
+suspend fun <T> safeApiCall(gson: Gson, call: suspend () -> Response<T>): Result<T> {
+    return try {
+        val response = call()
+        if (response.isSuccessful) {
+            val body = response.body()
+            if (body != null) {
+                Result.Success(body)
+            } else if (response.code() == 204) {
+                @Suppress("UNCHECKED_CAST")
+                Result.Success(Unit as T)
+            } else {
+                Result.Error("EMPTY_BODY", "Empty response body", response.code())
+            }
+        } else {
+            val errorBody = response.errorBody()?.string()
+            val apiError = try {
+                gson.fromJson(errorBody, ApiError::class.java)
+            } catch (e: Exception) {
+                null
+            }
+            Result.Error(
+                code = apiError?.code ?: "UNKNOWN_ERROR",
+                message = apiError?.error ?: "Something went wrong. Please try again.",
+                httpStatus = response.code()
+            )
+        }
+    } catch (e: java.io.IOException) {
+        Result.NetworkError
+    } catch (e: Exception) {
+        Result.Error("UNKNOWN_ERROR", e.message ?: "An unexpected error occurred.")
+    }
+}
+
+fun Result.Error.toUserMessage(): String = when (code) {
+    "VALIDATION_ERROR" -> message
+    "UNAUTHORIZED" -> "Your session has expired. Please sign in again."
+    "FORBIDDEN" -> message
+    "NOT_FOUND" -> "That item couldn't be found."
+    "CONFLICT" -> message
+    "DUPLICATE_ITEM" -> message
+    "ACCOUNT_PENDING_DELETION" -> message
+    "GONE" -> "This account no longer exists."
+    "INVALID_TOKEN" -> "That link has expired. Please request a new one."
+    "INVALID_GOOGLE_TOKEN" -> "Google sign-in failed. Please try again."
+    else -> "Something went wrong. Please try again."
+}

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

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string name="app_name">Pantree</string>
+</resources>

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

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

android/app/src/test/java/com/pantree/app/ui/screens/recipe/RecipeDetailScreenTest.kt

@@ -0,0 +1,25 @@
+package com.pantree.app.ui.screens.recipe
+
+import org.junit.Assert.*
+import org.junit.Test
+
+class RecipeDetailScreenTest {
+
+    @Test
+    fun `formatQuantity whole number strips decimal`() {
+        assertEquals("2", formatQuantity(2.0))
+        assertEquals("10", formatQuantity(10.0))
+    }
+
+    @Test
+    fun `formatQuantity decimal trims trailing zeros`() {
+        assertEquals("2.5", formatQuantity(2.5))
+        assertEquals("0.25", formatQuantity(0.25))
+    }
+
+    @Test
+    fun `formatQuantity handles repeating decimal`() {
+        val result = formatQuantity(0.6666666666)
+        assertTrue(result.startsWith("0.66"))
+    }
+}

android/app/src/test/java/com/pantree/app/util/ResultTest.kt

@@ -0,0 +1,31 @@
+package com.pantree.app.util
+
+import org.junit.Assert.*
+import org.junit.Test
+
+class ResultTest {
+
+    @Test
+    fun `toUserMessage returns human message for UNAUTHORIZED`() {
+        val error = Result.Error(code = "UNAUTHORIZED", message = "raw", httpStatus = 401)
+        assertEquals("Your session has expired. Please sign in again.", error.toUserMessage())
+    }
+
+    @Test
+    fun `toUserMessage returns human message for NOT_FOUND`() {
+        val error = Result.Error(code = "NOT_FOUND", message = "raw", httpStatus = 404)
+        assertEquals("That item couldn't be found.", error.toUserMessage())
+    }
+
+    @Test
+    fun `toUserMessage passes through VALIDATION_ERROR message`() {
+        val error = Result.Error(code = "VALIDATION_ERROR", message = "Email is required", httpStatus = 400)
+        assertEquals("Email is required", error.toUserMessage())
+    }
+
+    @Test
+    fun `toUserMessage returns generic for unknown code`() {
+        val error = Result.Error(code = "SOME_WEIRD_CODE", message = "raw", httpStatus = 500)
+        assertEquals("Something went wrong. Please try again.", error.toUserMessage())
+    }
+}

android/build.gradle

@@ -0,0 +1,8 @@
+// Top-level build file
+plugins {
+    id 'com.android.application' version '8.3.0' apply false
+    id 'com.android.library' version '8.3.0' apply false
+    id 'org.jetbrains.kotlin.android' version '1.9.23' apply false
+    id 'com.google.dagger.hilt.android' version '2.51.1' apply false
+    id 'com.google.devtools.ksp' version '1.9.23-1.0.20' apply false
+}

android/settings.gradle

@@ -0,0 +1,16 @@
+pluginManagement {
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+rootProject.name = "Pantree"
+include ':app'

jest.config.js

@@ -0,0 +1,24 @@
+/** @type {import('jest').Config} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/src'],
+  testMatch: ['**/*.test.ts'],
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.test.ts',
+    '!src/db/knexfile.ts',
+    '!src/db/migrations/**',
+    '!src/db/seeds/**',
+    '!src/server.ts'
+  ],
+  coverageThreshold: {
+    global: {
+      branches: 70,
+      functions: 80,
+      lines: 80,
+      statements: 80
+    }
+  },
+  setupFiles: ['<rootDir>/src/test/setup.ts']
+};

package.json

@@ -0,0 +1,49 @@
+{
+  "name": "pantree-backend",
+  "version": "1.0.0",
+  "description": "Pantree API Server",
+  "main": "dist/server.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/server.js",
+    "dev": "ts-node-dev --respawn --transpile-only src/server.ts",
+    "test": "jest --runInBand --forceExit",
+    "test:coverage": "jest --runInBand --forceExit --coverage",
+    "migrate": "knex migrate:latest --knexfile src/db/knexfile.ts",
+    "migrate:rollback": "knex migrate:rollback --knexfile src/db/knexfile.ts",
+    "seed": "knex seed:run --knexfile src/db/knexfile.ts"
+  },
+  "dependencies": {
+    "@sendgrid/mail": "^8.1.0",
+    "bcrypt": "^5.1.1",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.5",
+    "express": "^4.19.2",
+    "google-auth-library": "^9.10.0",
+    "jsonwebtoken": "^9.0.2",
+    "knex": "^3.1.0",
+    "node-cron": "^3.0.3",
+    "pg": "^8.11.5",
+    "pino": "^9.1.0",
+    "pino-http": "^10.1.0",
+    "uuid": "^9.0.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/bcrypt": "^5.0.2",
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "@types/jest": "^29.5.12",
+    "@types/jsonwebtoken": "^9.0.6",
+    "@types/node": "^20.12.12",
+    "@types/node-cron": "^3.0.11",
+    "@types/supertest": "^6.0.2",
+    "@types/uuid": "^9.0.8",
+    "jest": "^29.7.0",
+    "supertest": "^7.0.0",
+    "ts-jest": "^29.1.4",
+    "ts-node": "^10.9.2",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^5.4.5"
+  }
+}

src/app.ts

@@ -0,0 +1,42 @@
+import express from 'express';
+import cors from 'cors';
+import { httpLogger } from './utils/logger';
+import { errorHandler } from './middleware/errorHandler';
+import authRoutes from './routes/auth';
+import pantryRoutes from './routes/pantry';
+import recipeRoutes from './routes/recipes';
+import shoppingListRoutes from './routes/shoppingLists';
+import syncRoutes from './routes/sync';
+
+export function createApp() {
+  const app = express();
+
+  app.use(cors());
+  app.use(express.json());
+  app.use(httpLogger);
+
+  // Health check
+  app.get('/health', (_req, res) => {
+    res.status(200).json({ status: 'ok', timestamp: new Date().toISOString() });
+  });
+
+  // Routes
+  app.use('/v1/auth', authRoutes);
+  app.use('/v1/pantry', pantryRoutes);
+  app.use('/v1/recipes', recipeRoutes);
+  app.use('/v1/shopping-lists', shoppingListRoutes);
+  app.use('/v1/sync', syncRoutes);
+
+  // 404 handler
+  app.use((_req, res) => {
+    res.status(404).json({
+      error: 'Route not found.',
+      code: 'NOT_FOUND',
+      timestamp: new Date().toISOString(),
+    });
+  });
+
+  app.use(errorHandler);
+
+  return app;
+}

src/config/constants.ts

@@ -0,0 +1,18 @@
+export const ALLOWED_UNITS = [
+  'cups', 'tbsp', 'tsp', 'oz', 'fl_oz',
+  'g', 'kg', 'ml', 'l',
+  'pieces', 'slices', 'cloves', 'pinch',
+  'whole', 'can', 'package', 'bunch'
+] as const;
+
+export type AllowedUnit = typeof ALLOWED_UNITS[number];
+
+export const BCRYPT_ROUNDS = 12;
+export const JWT_EXPIRES_IN = '24h';
+export const PASSWORD_RESET_EXPIRES_HOURS = 1;
+export const ACCOUNT_DELETION_DAYS = 15;
+export const TOMBSTONE_RETENTION_DAYS = 30;
+export const MAX_RECIPE_SCALE = 3;
+export const MIN_RECIPE_SCALE = 1;
+export const DEFAULT_PAGE_LIMIT = 20;
+export const MAX_PAGE_LIMIT = 50;

src/config/env.ts

@@ -0,0 +1,30 @@
+import dotenv from 'dotenv';
+dotenv.config();
+
+function requireEnv(key: string): string {
+  const value = process.env[key];
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${key}`);
+  }
+  return value;
+}
+
+const isTest = process.env.NODE_ENV === 'test';
+
+export const config = {
+  nodeEnv: process.env.NODE_ENV ?? 'development',
+  port: parseInt(process.env.PORT ?? '3000', 10),
+  databaseUrl: process.env.DATABASE_URL ?? 'postgresql://postgres:postgres@localhost:5432/pantree_test',
+  jwtSecret: isTest
+    ? (process.env.JWT_SECRET ?? 'test_secret_do_not_use_in_production_ever')
+    : requireEnv('JWT_SECRET'),
+  jwtExpiresIn: process.env.JWT_EXPIRES_IN ?? '24h',
+  googleClientId: process.env.GOOGLE_CLIENT_ID ?? '',
+  sendgridApiKey: process.env.SENDGRID_API_KEY ?? '',
+  sendgridFromEmail: process.env.SENDGRID_FROM_EMAIL ?? 'noreply@pantree.app',
+  frontendUrl: process.env.FRONTEND_URL ?? 'http://localhost:3000',
+  passwordResetUrl: process.env.PASSWORD_RESET_URL ?? 'http://localhost:3000/reset-password',
+  isTest,
+  isDev: process.env.NODE_ENV === 'development',
+  isProd: process.env.NODE_ENV === 'production',
+};

src/db/connection.ts

@@ -0,0 +1,6 @@
+import knex from 'knex';
+import knexConfig from './knexfile';
+
+const db = knex(knexConfig);
+
+export default db;

src/db/knexfile.ts

@@ -0,0 +1,22 @@
+import type { Knex } from 'knex';
+import { config } from '../config/env';
+
+const knexConfig: Knex.Config = {
+  client: 'pg',
+  connection: config.databaseUrl,
+  migrations: {
+    directory: './migrations',
+    extension: 'ts',
+  },
+  seeds: {
+    directory: './seeds',
+    extension: 'ts',
+  },
+  pool: {
+    min: 2,
+    max: 10,
+  },
+};
+
+export default knexConfig;
+module.exports = knexConfig;

src/db/migrations/001_create_users.ts

@@ -0,0 +1,27 @@
+import type { Knex } from 'knex';
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.raw('CREATE EXTENSION IF NOT EXISTS "pgcrypto"');
+
+  await knex.schema.createTable('users', (table) => {
+    table.uuid('id').primary().defaultTo(knex.raw('gen_random_uuid()'));
+    table.string('email', 255).notNullable();
+    table.string('password_hash', 255).nullable();
+    table.string('name', 255).notNullable();
+    table.text('profile_picture_url').nullable();
+    table.string('google_id', 255).nullable();
+    table.boolean('email_verified').defaultTo(false);
+    table.timestamp('deleted_at', { useTz: true }).nullable();
+    table.timestamp('deletion_scheduled_at', { useTz: true }).nullable();
+    table.timestamp('created_at', { useTz: true }).defaultTo(knex.fn.now());
+    table.timestamp('updated_at', { useTz: true }).defaultTo(knex.fn.now());
+  });
+
+  await knex.raw(`CREATE UNIQUE INDEX idx_users_email ON users (LOWER(email))`);
+  await knex.raw(`CREATE UNIQUE INDEX idx_users_google_id ON users (google_id) WHERE google_id IS NOT NULL`);
+  await knex.raw(`CREATE INDEX idx_users_deletion_scheduled ON users (deletion_scheduled_at) WHERE deletion_scheduled_at IS NOT NULL`);
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.dropTableIfExists('users');
+}

src/db/migrations/002_create_password_reset_tokens.ts

@@ -0,0 +1,20 @@
+import type { Knex } from 'knex';
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.createTable('password_reset_tokens', (table) => {
+    table.uuid('id').primary().defaultTo(knex.raw('gen_random_uuid()'));
+    table.uuid('user_id').notNullable().references('id').inTable('users').onDelete('CASCADE');
+    table.string('token_hash', 255).notNullable();
+    table.string('lookup_hash', 64).notNullable();
+    table.timestamp('expires_at', { useTz: true }).notNullable();
+    table.timestamp('used_at', { useTz: true }).nullable();
+    table.timestamp('created_at', { useTz: true }).defaultTo(knex.fn.now());
+  });
+
+  await knex.raw(`CREATE INDEX idx_prt_user_id ON password_reset_tokens (user_id)`);
+  await knex.raw(`CREATE UNIQUE INDEX idx_prt_lookup_hash ON password_reset_tokens (lookup_hash)`);
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.dropTableIfExists('password_reset_tokens');
+}

src/db/migrations/003_create_pantry_items.ts

@@ -0,0 +1,22 @@
+import type { Knex } from 'knex';
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.createTable('pantry_items', (table) => {
+    table.uuid('id').primary().defaultTo(knex.raw('gen_random_uuid()'));
+    table.uuid('user_id').notNullable().references('id').inTable('users').onDelete('CASCADE');
+    table.string('item_name', 255).notNullable();
+    table.string('item_name_lower', 255).notNullable();
+    table.integer('quantity').notNullable().checkPositive();
+    table.timestamp('last_modified', { useTz: true }).defaultTo(knex.fn.now());
+    table.timestamp('created_at', { useTz: true }).defaultTo(knex.fn.now());
+    table.timestamp('updated_at', { useTz: true }).defaultTo(knex.fn.now());
+  });
+
+  await knex.raw(`CREATE UNIQUE INDEX idx_pantry_user_item ON pantry_items (user_id, item_name_lower)`);
+  await knex.raw(`CREATE INDEX idx_pantry_user_id ON pantry_items (user_id)`);
+  await knex.raw(`CREATE INDEX idx_pantry_last_modified ON pantry_items (user_id, last_modified)`);
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.dropTableIfExists('pantry_items');
+}

src/db/migrations/004_create_recipes.ts

@@ -0,0 +1,30 @@
+import type { Knex } from 'knex';
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.createTable('recipes', (table) => {
+    table.uuid('id').primary().defaultTo(knex.raw('gen_random_uuid()'));
+    table.string('name', 255).notNullable();
+    table.text('instructions').notNullable();
+    table.integer('servings').notNullable().checkPositive();
+    table.timestamp('created_at', { useTz: true }).defaultTo(knex.fn.now());
+    table.timestamp('updated_at', { useTz: true }).defaultTo(knex.fn.now());
+  });
+
+  await knex.schema.createTable('recipe_ingredients', (table) => {
+    table.uuid('id').primary().defaultTo(knex.raw('gen_random_uuid()'));
+    table.uuid('recipe_id').notNullable().references('id').inTable('recipes').onDelete('CASCADE');
+    table.string('item_name', 255).notNullable();
+    table.string('item_name_lower', 255).notNullable();
+    table.decimal('quantity', 10, 4).notNullable().checkPositive();
+    table.string('unit', 50).notNullable();
+    table.timestamp('created_at', { useTz: true }).defaultTo(knex.fn.now());
+  });
+
+  await knex.raw(`CREATE INDEX idx_recipe_ingredients_recipe ON recipe_ingredients (recipe_id)`);
+  await knex.raw(`CREATE INDEX idx_recipe_ingredients_name ON recipe_ingredients (item_name_lower)`);
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.dropTableIfExists('recipe_ingredients');
+  await knex.schema.dropTableIfExists('recipes');
+}

src/db/migrations/005_create_shopping_lists.ts

@@ -0,0 +1,36 @@
+import type { Knex } from 'knex';
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.createTable('shopping_lists', (table) => {
+    table.uuid('id').primary().defaultTo(knex.raw('gen_random_uuid()'));
+    table.uuid('user_id').notNullable().references('id').inTable('users').onDelete('CASCADE');
+    table.string('list_name', 255).notNullable();
+    table.timestamp('last_modified', { useTz: true }).defaultTo(knex.fn.now());
+    table.timestamp('created_at', { useTz: true }).defaultTo(knex.fn.now());
+    table.timestamp('updated_at', { useTz: true }).defaultTo(knex.fn.now());
+  });
+
+  await knex.schema.createTable('shopping_list_items', (table) => {
+    table.uuid('id').primary().defaultTo(knex.raw('gen_random_uuid()'));
+    table.uuid('shopping_list_id').notNullable().references('id').inTable('shopping_lists').onDelete('CASCADE');
+    table.string('item_name', 255).notNullable();
+    table.string('item_name_lower', 255).notNullable();
+    table.decimal('quantity', 10, 4).notNullable().checkPositive();
+    table.string('unit', 50).notNullable();
+    table.boolean('checked_off').defaultTo(false);
+    table.timestamp('last_modified', { useTz: true }).defaultTo(knex.fn.now());
+    table.timestamp('created_at', { useTz: true }).defaultTo(knex.fn.now());
+    table.timestamp('updated_at', { useTz: true }).defaultTo(knex.fn.now());
+  });
+
+  await knex.raw(`CREATE INDEX idx_shopping_lists_user ON shopping_lists (user_id)`);
+  await knex.raw(`CREATE INDEX idx_shopping_lists_last_modified ON shopping_lists (user_id, last_modified)`);
+  await knex.raw(`CREATE INDEX idx_list_items_list ON shopping_list_items (shopping_list_id)`);
+  await knex.raw(`CREATE INDEX idx_list_items_name_unit ON shopping_list_items (shopping_list_id, item_name_lower, unit)`);
+  await knex.raw(`CREATE INDEX idx_list_items_last_modified ON shopping_list_items (shopping_list_id, last_modified)`);
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.dropTableIfExists('shopping_list_items');
+  await knex.schema.dropTableIfExists('shopping_lists');
+}

src/db/migrations/006_create_deleted_records.ts

@@ -0,0 +1,17 @@
+import type { Knex } from 'knex';
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.createTable('deleted_records', (table) => {
+    table.uuid('id').primary().defaultTo(knex.raw('gen_random_uuid()'));
+    table.uuid('user_id').notNullable();
+    table.string('table_name', 50).notNullable();
+    table.uuid('record_id').notNullable();
+    table.timestamp('deleted_at', { useTz: true }).defaultTo(knex.fn.now());
+  });
+
+  await knex.raw(`CREATE INDEX idx_deleted_records_user_time ON deleted_records (user_id, deleted_at)`);
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.dropTableIfExists('deleted_records');
+}

src/db/seeds/001_recipes.ts

@@ -0,0 +1,164 @@
+import type { Knex } from 'knex';
+
+const recipes = [
+  {
+    name: 'Chocolate Chip Cookies',
+    servings: 24,
+    instructions: '1. Preheat oven to 375°F.\n2. Cream butter and sugars.\n3. Beat in eggs and vanilla.\n4. Mix in flour, baking soda, and salt.\n5. Stir in chocolate chips.\n6. Drop by spoonfuls onto baking sheet.\n7. Bake 9-11 minutes until golden.',
+    ingredients: [
+      { item_name: 'All-Purpose Flour', quantity: 2.25, unit: 'cups' },
+      { item_name: 'Butter', quantity: 1, unit: 'cups' },
+      { item_name: 'Granulated Sugar', quantity: 0.75, unit: 'cups' },
+      { item_name: 'Brown Sugar', quantity: 0.75, unit: 'cups' },
+      { item_name: 'Eggs', quantity: 2, unit: 'pieces' },
+      { item_name: 'Vanilla Extract', quantity: 1, unit: 'tsp' },
+      { item_name: 'Baking Soda', quantity: 1, unit: 'tsp' },
+      { item_name: 'Chocolate Chips', quantity: 2, unit: 'cups' },
+    ],
+  },
+  {
+    name: 'Classic Pancakes',
+    servings: 4,
+    instructions: '1. Mix dry ingredients.\n2. Whisk wet ingredients separately.\n3. Combine wet and dry.\n4. Cook on greased griddle over medium heat.\n5. Flip when bubbles form.',
+    ingredients: [
+      { item_name: 'All-Purpose Flour', quantity: 1.5, unit: 'cups' },
+      { item_name: 'Milk', quantity: 1.25, unit: 'cups' },
+      { item_name: 'Eggs', quantity: 1, unit: 'pieces' },
+      { item_name: 'Butter', quantity: 3, unit: 'tbsp' },
+      { item_name: 'Baking Powder', quantity: 2, unit: 'tsp' },
+      { item_name: 'Granulated Sugar', quantity: 1, unit: 'tbsp' },
+      { item_name: 'Salt', quantity: 1, unit: 'tsp' },
+    ],
+  },
+  {
+    name: 'Spaghetti Bolognese',
+    servings: 4,
+    instructions: '1. Brown ground beef.\n2. Add onion and garlic, cook until soft.\n3. Add tomatoes and simmer 30 minutes.\n4. Cook pasta.\n5. Serve sauce over pasta.',
+    ingredients: [
+      { item_name: 'Spaghetti', quantity: 400, unit: 'g' },
+      { item_name: 'Ground Beef', quantity: 500, unit: 'g' },
+      { item_name: 'Onion', quantity: 1, unit: 'whole' },
+      { item_name: 'Garlic', quantity: 3, unit: 'cloves' },
+      { item_name: 'Canned Tomatoes', quantity: 2, unit: 'can' },
+      { item_name: 'Olive Oil', quantity: 2, unit: 'tbsp' },
+      { item_name: 'Salt', quantity: 1, unit: 'tsp' },
+    ],
+  },
+  {
+    name: 'Caesar Salad',
+    servings: 2,
+    instructions: '1. Wash and chop romaine.\n2. Make dressing with garlic, lemon, and parmesan.\n3. Toss lettuce with dressing.\n4. Top with croutons and extra parmesan.',
+    ingredients: [
+      { item_name: 'Romaine Lettuce', quantity: 1, unit: 'whole' },
+      { item_name: 'Parmesan Cheese', quantity: 0.5, unit: 'cups' },
+      { item_name: 'Garlic', quantity: 2, unit: 'cloves' },
+      { item_name: 'Lemon', quantity: 1, unit: 'whole' },
+      { item_name: 'Olive Oil', quantity: 3, unit: 'tbsp' },
+      { item_name: 'Croutons', quantity: 1, unit: 'cups' },
+    ],
+  },
+  {
+    name: 'Banana Bread',
+    servings: 8,
+    instructions: '1. Preheat oven to 350°F.\n2. Mash bananas.\n3. Mix wet ingredients.\n4. Fold in dry ingredients.\n5. Pour into loaf pan.\n6. Bake 60-65 minutes.',
+    ingredients: [
+      { item_name: 'Ripe Bananas', quantity: 3, unit: 'whole' },
+      { item_name: 'All-Purpose Flour', quantity: 1.5, unit: 'cups' },
+      { item_name: 'Butter', quantity: 0.33, unit: 'cups' },
+      { item_name: 'Granulated Sugar', quantity: 0.75, unit: 'cups' },
+      { item_name: 'Eggs', quantity: 1, unit: 'pieces' },
+      { item_name: 'Baking Soda', quantity: 1, unit: 'tsp' },
+      { item_name: 'Salt', quantity: 0.25, unit: 'tsp' },
+    ],
+  },
+  {
+    name: 'Chicken Stir Fry',
+    servings: 4,
+    instructions: '1. Slice chicken and vegetables.\n2. Heat oil in wok.\n3. Cook chicken until done.\n4. Add vegetables and stir fry.\n5. Add sauce and toss.\n6. Serve over rice.',
+    ingredients: [
+      { item_name: 'Chicken Breast', quantity: 500, unit: 'g' },
+      { item_name: 'Bell Pepper', quantity: 2, unit: 'whole' },
+      { item_name: 'Broccoli', quantity: 2, unit: 'cups' },
+      { item_name: 'Soy Sauce', quantity: 3, unit: 'tbsp' },
+      { item_name: 'Garlic', quantity: 3, unit: 'cloves' },
+      { item_name: 'Vegetable Oil', quantity: 2, unit: 'tbsp' },
+      { item_name: 'Rice', quantity: 2, unit: 'cups' },
+    ],
+  },
+  {
+    name: 'Guacamole',
+    servings: 4,
+    instructions: '1. Halve and pit avocados.\n2. Scoop flesh into bowl.\n3. Mash with fork.\n4. Add lime juice, salt, onion, cilantro.\n5. Mix and adjust seasoning.',
+    ingredients: [
+      { item_name: 'Avocado', quantity: 3, unit: 'whole' },
+      { item_name: 'Lime', quantity: 1, unit: 'whole' },
+      { item_name: 'Red Onion', quantity: 0.25, unit: 'whole' },
+      { item_name: 'Cilantro', quantity: 2, unit: 'tbsp' },
+      { item_name: 'Salt', quantity: 0.5, unit: 'tsp' },
+    ],
+  },
+  {
+    name: 'Tomato Soup',
+    servings: 4,
+    instructions: '1. Sauté onion and garlic.\n2. Add tomatoes and broth.\n3. Simmer 20 minutes.\n4. Blend until smooth.\n5. Season with salt and pepper.',
+    ingredients: [
+      { item_name: 'Canned Tomatoes', quantity: 2, unit: 'can' },
+      { item_name: 'Onion', quantity: 1, unit: 'whole' },
+      { item_name: 'Garlic', quantity: 2, unit: 'cloves' },
+      { item_name: 'Vegetable Broth', quantity: 2, unit: 'cups' },
+      { item_name: 'Olive Oil', quantity: 2, unit: 'tbsp' },
+      { item_name: 'Salt', quantity: 1, unit: 'tsp' },
+    ],
+  },
+  {
+    name: 'French Toast',
+    servings: 2,
+    instructions: '1. Whisk eggs, milk, and cinnamon.\n2. Dip bread slices.\n3. Cook on buttered pan until golden.\n4. Serve with maple syrup.',
+    ingredients: [
+      { item_name: 'Bread', quantity: 4, unit: 'slices' },
+      { item_name: 'Eggs', quantity: 2, unit: 'pieces' },
+      { item_name: 'Milk', quantity: 0.25, unit: 'cups' },
+      { item_name: 'Butter', quantity: 1, unit: 'tbsp' },
+      { item_name: 'Cinnamon', quantity: 0.5, unit: 'tsp' },
+    ],
+  },
+  {
+    name: 'Oatmeal',
+    servings: 1,
+    instructions: '1. Bring water or milk to boil.\n2. Add oats.\n3. Cook 5 minutes stirring occasionally.\n4. Top with fruit and honey.',
+    ingredients: [
+      { item_name: 'Rolled Oats', quantity: 0.5, unit: 'cups' },
+      { item_name: 'Milk', quantity: 1, unit: 'cups' },
+      { item_name: 'Honey', quantity: 1, unit: 'tbsp' },
+      { item_name: 'Salt', quantity: 1, unit: 'pinch' },
+    ],
+  },
+];
+
+export async function seed(knex: Knex): Promise<void> {
+  // Clear existing
+  await knex('recipe_ingredients').delete();
+  await knex('recipes').delete();
+
+  for (const recipe of recipes) {
+    const [inserted] = await knex('recipes')
+      .insert({
+        name: recipe.name,
+        servings: recipe.servings,
+        instructions: recipe.instructions,
+      })
+      .returning('id');
+
+    const recipeId = inserted.id;
+
+    await knex('recipe_ingredients').insert(
+      recipe.ingredients.map((ing) => ({
+        recipe_id: recipeId,
+        item_name: ing.item_name,
+        item_name_lower: ing.item_name.toLowerCase(),
+        quantity: ing.quantity,
+        unit: ing.unit,
+      }))
+    );
+  }
+}

src/jobs/cronJobs.ts

@@ -0,0 +1,34 @@
+import cron from 'node-cron';
+import db from '../db/connection';
+import { logger } from '../utils/logger';
+import { syncService } from '../services/syncService';
+
+let lastCronRun: Date | null = null;
+
+export function getLastCronRun(): Date | null {
+  return lastCronRun;
+}
+
+export function startCronJobs(): void {
+  // Daily at 2:00 AM UTC — hard-delete expired accounts
+  cron.schedule('0 2 * * *', async () => {
+    logger.info('Running daily account hard-delete job...');
+    try {
+      const result = await db('users')
+        .where('deletion_scheduled_at', '<=', db.fn.now())
+        .whereNotNull('deletion_scheduled_at')
+        .delete();
+
+      logger.info({ deletedCount: result }, 'Hard-delete job complete.');
+
+      // Clean up old tombstones
+      await syncService.cleanupTombstones();
+
+      lastCronRun = new Date();
+    } catch (err) {
+      logger.error({ err }, 'Hard-delete cron job failed.');
+    }
+  });
+
+  logger.info('Cron jobs registered.');
+}

src/middleware/auth.ts

@@ -0,0 +1,57 @@
+import { Request, Response, NextFunction } from 'express';
+import jwt from 'jsonwebtoken';
+import { config } from '../config/env';
+import { createError } from './errorHandler';
+import db from '../db/connection';
+
+export interface AuthenticatedRequest extends Request {
+  userId?: string;
+}
+
+export async function authMiddleware(
+  req: AuthenticatedRequest,
+  _res: Response,
+  next: NextFunction
+): Promise<void> {
+  try {
+    const authHeader = req.headers.authorization;
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      return next(createError('Missing or invalid Authorization header.', 401, 'UNAUTHORIZED'));
+    }
+
+    const token = authHeader.slice(7);
+    let payload: { userId: string };
+
+    try {
+      payload = jwt.verify(token, config.jwtSecret) as { userId: string };
+    } catch {
+      return next(createError('Invalid or expired token.', 401, 'UNAUTHORIZED'));
+    }
+
+    // Verify user still exists (including soft-deleted — they may be hitting /restore-account)
+    const user = await db('users')
+      .where({ id: payload.userId })
+      .select('id', 'deleted_at', 'deletion_scheduled_at')
+      .first();
+
+    if (!user) {
+      return next(createError('Invalid or expired token.', 401, 'UNAUTHORIZED'));
+    }
+
+    // Soft-deleted accounts may only access the restore-account route
+    if (user.deleted_at) {
+      const isRestorePath =
+        req.path === '/auth/restore-account' ||
+        req.path.endsWith('/restore-account');
+
+      if (!isRestorePath) {
+        return next(createError('Account is pending deletion.', 403, 'FORBIDDEN'));
+      }
+    }
+
+    req.userId = payload.userId;
+    next();
+  } catch (err) {
+    next(err);
+  }
+}

src/middleware/errorHandler.ts

@@ -0,0 +1,47 @@
+import { Request, Response, NextFunction } from 'express';
+import { ZodError } from 'zod';
+import { logger } from '../utils/logger';
+
+export interface AppError extends Error {
+  statusCode?: number;
+  code?: string;
+  details?: unknown;
+}
+
+export function createError(message: string, statusCode: number, code: string): AppError {
+  const err: AppError = new Error(message);
+  err.statusCode = statusCode;
+  err.code = code;
+  return err;
+}
+
+export function errorHandler(
+  err: AppError,
+  _req: Request,
+  res: Response,
+  _next: NextFunction
+): void {
+  const timestamp = new Date().toISOString();
+
+  if (err instanceof ZodError) {
+    res.status(400).json({
+      error: err.errors.map((e) => `${e.path.join('.')}: ${e.message}`).join('; '),
+      code: 'VALIDATION_ERROR',
+      timestamp,
+    });
+    return;
+  }
+
+  const statusCode = err.statusCode ?? 500;
+  const code = err.code ?? 'INTERNAL_ERROR';
+
+  if (statusCode >= 500) {
+    logger.error({ err }, 'Unhandled server error');
+  }
+
+  res.status(statusCode).json({
+    error: statusCode >= 500 ? 'An internal error occurred.' : err.message,
+    code,
+    timestamp,
+  });
+}

src/routes/auth.ts

@@ -0,0 +1,134 @@
+import { Router, Response, NextFunction } from 'express';
+import { authService } from '../services/authService';
+import { AuthenticatedRequest, authMiddleware } from '../middleware/auth';
+import {
+  signupSchema,
+  signinSchema,
+  googleAuthSchema,
+  passwordResetRequestSchema,
+  passwordResetConfirmSchema,
+} from '../utils/validators';
+
+const router = Router();
+
+// POST /auth/signup
+router.post('/signup', async (req, res: Response, next: NextFunction) => {
+  try {
+    const { email, password, name } = signupSchema.parse(req.body);
+    const result = await authService.signup(email, password, name);
+    res.status(201).json(result);
+  } catch (err) {
+    next(err);
+  }
+});
+
+// POST /auth/signin
+router.post('/signin', async (req, res: Response, next: NextFunction) => {
+  try {
+    const { email, password } = signinSchema.parse(req.body);
+    const result = await authService.signin(email, password);
+    res.status(200).json(result);
+  } catch (err: unknown) {
+    if (
+      err instanceof Error &&
+      (err as { code?: string }).code === 'ACCOUNT_PENDING_DELETION'
+    ) {
+      const appErr = err as { code?: string; statusCode?: number; deletion_scheduled_at?: string };
+      res.status(403).json({
+        error: err.message,
+        code: appErr.code,
+        deletion_scheduled_at: appErr.deletion_scheduled_at,
+        timestamp: new Date().toISOString(),
+      });
+      return;
+    }
+    next(err);
+  }
+});
+
+// POST /auth/google
+router.post('/google', async (req, res: Response, next: NextFunction) => {
+  try {
+    const { id_token } = googleAuthSchema.parse(req.body);
+    const result = await authService.googleAuth(id_token);
+    const statusCode = result.is_new_user ? 201 : 200;
+    res.status(statusCode).json(result);
+  } catch (err: unknown) {
+    if (
+      err instanceof Error &&
+      (err as { code?: string }).code === 'ACCOUNT_PENDING_DELETION'
+    ) {
+      const appErr = err as { code?: string; statusCode?: number; deletion_scheduled_at?: string };
+      res.status(403).json({
+        error: err.message,
+        code: appErr.code,
+        deletion_scheduled_at: appErr.deletion_scheduled_at,
+        timestamp: new Date().toISOString(),
+      });
+      return;
+    }
+    next(err);
+  }
+});
+
+// POST /auth/password-reset
+router.post('/password-reset', async (req, res: Response, next: NextFunction) => {
+  try {
+    const { email } = passwordResetRequestSchema.parse(req.body);
+    await authService.requestPasswordReset(email);
+    res.status(200).json({
+      message: 'If an account exists with this email, a reset link has been sent.',
+      timestamp: new Date().toISOString(),
+    });
+  } catch (err) {
+    next(err);
+  }
+});
+
+// PUT /auth/password-reset
+router.put('/password-reset', async (req, res: Response, next: NextFunction) => {
+  try {
+    const { token, new_password } = passwordResetConfirmSchema.parse(req.body);
+    await authService.confirmPasswordReset(token, new_password);
+    res.status(200).json({
+      message: 'Password updated successfully.',
+      timestamp: new Date().toISOString(),
+    });
+  } catch (err) {
+    next(err);
+  }
+});
+
+// DELETE /auth/account (protected)
+router.delete(
+  '/account',
+  authMiddleware,
+  async (req: AuthenticatedRequest, res: Response, next: NextFunction) => {
+    try {
+      await authService.deleteAccount(req.userId!);
+      res.status(204).send();
+    } catch (err) {
+      next(err);
+    }
+  }
+);
+
+// POST /auth/restore-account (protected)
+router.post(
+  '/restore-account',
+  authMiddleware,
+  async (req: AuthenticatedRequest, res: Response, next: NextFunction) => {
+    try {
+      const user = await authService.restoreAccount(req.userId!);
+      res.status(200).json({
+        user,
+        message: 'Account restored successfully.',
+        timestamp: new Date().toISOString(),
+      });
+    } catch (err) {
+      next(err);
+    }
+  }
+);
+
+export default router;

src/routes/pantry.ts

@@ -0,0 +1,51 @@
+import { Router, Response, NextFunction } from 'express';
+import { authMiddleware, AuthenticatedRequest } from '../middleware/auth';
+import { pantryService } from '../services/pantryService';
+import { addPantryItemSchema, updatePantryItemSchema } from '../utils/validators';
+
+const router = Router();
+router.use(authMiddleware);
+
+// GET /pantry
+router.get('/', async (req: AuthenticatedRequest, res: Response, next: NextFunction) => {
+  try {
+    const items = await pantryService.getItems(req.userId!);
+    res.status(200).json({ items, synced_at: new Date().toISOString() });
+  } catch (err) {
+    next(err);
+  }
+});
+
+// POST /pantry
+router.post('/', async (req: AuthenticatedRequest, res: Response, next: NextFunction) => {
+  try {
+    const { item_name, quantity } = addPantryItemSchema.parse(req.body);
+    const item = await pantryService.addItem(req.userId!, item_name, quantity);
+    res.status(201).json({ item, synced_at: new Date().toISOString() });
+  } catch (err) {
+    next(err);
+  }
+});
+
+// PUT /pantry/:item_id
+router.put('/:item_id', async (req: AuthenticatedRequest, res: Response, next: NextFunction) => {
+  try {
+    const { quantity } = updatePantryItemSchema.parse(req.body);
+    const item = await pantryService.updateItem(req.userId!, req.params.item_id, quantity);
+    res.status(200).json({ item, synced_at: new Date().toISOString() });
+  } catch (err) {
+    next(err);
+  }
+});
+
+// DELETE /pantry/:item_id
+router.delete('/:item_id', async (req: AuthenticatedRequest, res: Response, next: NextFunction) => {
+  try {
+    await pantryService.deleteItem(req.userId!, req.params.item_id);
+    res.status(204).send();
+  } catch (err) {
+    next(err);
+  }
+});
+
+export default router;

src/routes/recipes.ts

@@ -0,0 +1,31 @@
+import { Router, Response, NextFunction } from 'express';
+import { authMiddleware, AuthenticatedRequest } from '../middleware/auth';
+import { recipeService } from '../services/recipeService';
+import { recipeQuerySchema, recipeDetailQuerySchema } from '../utils/validators';
+
+const router = Router();
+router.use(authMiddleware);
+
+// GET /recipes
+router.get('/', async (req: AuthenticatedRequest, res: Response, next: NextFunction) => {
+  try {
+    const { filter, page, limit, search } = recipeQuerySchema.parse(req.query);
+    const result = await recipeService.getRecipes(req.userId!, filter, page, limit, search);
+    res.status(200).json({ ...result, synced_at: new Date().toISOString() });
+  } catch (err) {
+    next(err);
+  }
+});
+
+// GET /recipes/:recipe_id
+router.get('/:recipe_id', async (req: AuthenticatedRequest, res: Response, next: NextFunction) => {
+  try {
+    const { scale } = recipeDetailQuerySchema.parse(req.query);
+    const recipe = await recipeService.getRecipeById(req.params.recipe_id, req.userId!, scale);
+    res.status(200).json({ recipe });
+  } catch (err) {
+    next(err);
+  }
+});
+
+export default router;

src/routes/shoppingLists.ts

@@ -0,0 +1,118 @@
+import { Router, Response, NextFunction } from 'express';
+import { authMiddleware, AuthenticatedRequest } from '../middleware/auth';
+import { shoppingListService } from '../services/shoppingListService';
+import {
+  createShoppingListSchema,
+  addShoppingListItemSchema,
+  updateShoppingListItemSchema,
+  addRecipesToListSchema,
+} from '../utils/validators';
+
+const router = Router();
+router.use(authMiddleware);
+
+// GET /shopping-lists
+router.get('/', async (req: AuthenticatedRequest, res: Response, next: NextFunction) => {
+  try {
+    const lists = await shoppingListService.getLists(req.userId!);
+    res.status(200).json({ shopping_lists: lists, synced_at: new Date().toISOString() });
+  } catch (err) {
+    next(err);
+  }
+});
+
+// POST /shopping-lists
+router.post('/', async (req: AuthenticatedRequest, res: Response, next: NextFunction) => {
+  try {
+    const { list_name } = createShoppingListSchema.parse(req.body);
+    const list = await shoppingListService.createList(req.userId!, list_name);
+    res.status(201).json({ shopping_list: list });
+  } catch (err) {
+    next(err);
+  }
+});
+
+// GET /shopping-lists/:list_id
+router.get('/:list_id', async (req: AuthenticatedRequest, res: Response, next: NextFunction) => {
+  try {
+    const list = await shoppingListService.getListById(req.params.list_id, req.userId!);
+    res.status(200).json({ shopping_list: list, synced_at: new Date().toISOString() });
+  } catch (err) {
+    next(err);
+  }
+});
+
+// DELETE /shopping-lists/:list_id
+router.delete('/:list_id', async (req: AuthenticatedRequest, res: Response, next: NextFunction) => {
+  try {
+    await shoppingListService.deleteList(req.params.list_id, req.userId!);
+    res.status(204).send();
+  } catch (err) {
+    next(err);
+  }
+});
+
+// POST /shopping-lists/:list_id/items
+router.post('/:list_id/items', async (req: AuthenticatedRequest, res: Response, next: NextFunction) => {
+  try {
+    const { item_name, quantity, unit } = addShoppingListItemSchema.parse(req.body);
+    const result = await shoppingListService.addItem(
+      req.params.list_id,
+      req.userId!,
+      item_name,
+      quantity,
+      unit
+    );
+    res.status(201).json(result);
+  } catch (err) {
+    next(err);
+  }
+});
+
+// POST /shopping-lists/:list_id/add-recipes
+router.post('/:list_id/add-recipes', async (req: AuthenticatedRequest, res: Response, next: NextFunction) => {
+  try {
+    const { recipe_ids, scale_factor } = addRecipesToListSchema.parse(req.body);
+    const result = await shoppingListService.addRecipesToList(
+      req.params.list_id,
+      req.userId!,
+      recipe_ids,
+      scale_factor
+    );
+    res.status(201).json(result);
+  } catch (err) {
+    next(err);
+  }
+});
+
+// PUT /shopping-lists/:list_id/items/:item_id
+router.put('/:list_id/items/:item_id', async (req: AuthenticatedRequest, res: Response, next: NextFunction) => {
+  try {
+    const updates = updateShoppingListItemSchema.parse(req.body);
+    const item = await shoppingListService.updateItem(
+      req.params.list_id,
+      req.params.item_id,
+      req.userId!,
+      updates
+    );
+    res.status(200).json({ item, synced_at: new Date().toISOString() });
+  } catch (err) {
+    next(err);
+  }
+});
+
+// DELETE /shopping-lists/:list_id/items/:item_id
+router.delete('/:list_id/items/:item_id', async (req: AuthenticatedRequest, res: Response, next: NextFunction) => {
+  try {
+    await shoppingListService.deleteItem(
+      req.params.list_id,
+      req.params.item_id,
+      req.userId!
+    );
+    res.status(204).send();
+  } catch (err) {
+    next(err);
+  }
+});
+
+export default router;

src/routes/sync.ts

@@ -0,0 +1,20 @@
+import { Router, Response, NextFunction } from 'express';
+import { authMiddleware, AuthenticatedRequest } from '../middleware/auth';
+import { syncService } from '../services/syncService';
+import { syncQuerySchema } from '../utils/validators';
+
+const router = Router();
+router.use(authMiddleware);
+
+// GET /sync
+router.get('/', async (req: AuthenticatedRequest, res: Response, next: NextFunction) => {
+  try {
+    const { since } = syncQuerySchema.parse(req.query);
+    const delta = await syncService.getDelta(req.userId!, since);
+    res.status(200).json(delta);
+  } catch (err) {
+    next(err);
+  }
+});
+
+export default router;

src/server.ts

@@ -0,0 +1,24 @@
+import { createApp } from './app';
+import { config } from './config/env';
+import { logger } from './utils/logger';
+import { startCronJobs } from './jobs/cronJobs';
+import db from './db/connection';
+
+async function main() {
+  // Verify DB connection
+  await db.raw('SELECT 1');
+  logger.info('Database connection established.');
+
+  const app = createApp();
+
+  app.listen(config.port, () => {
+    logger.info(`Pantree API running on port ${config.port}`);
+  });
+
+  startCronJobs();
+}
+
+main().catch((err) => {
+  logger.error({ err }, 'Failed to start server');
+  process.exit(1);
+});

src/services/authService.ts

@@ -0,0 +1,268 @@
+import bcrypt from 'bcrypt';
+import crypto from 'crypto';
+import { OAuth2Client } from 'google-auth-library';
+import db from '../db/connection';
+import { config } from '../config/env';
+import { signToken } from '../utils/jwt';
+import { createError } from '../middleware/errorHandler';
+import { BCRYPT_ROUNDS, ACCOUNT_DELETION_DAYS, PASSWORD_RESET_EXPIRES_HOURS } from '../config/constants';
+import { emailService } from './emailService';
+
+const googleClient = new OAuth2Client(config.googleClientId);
+
+function formatUser(user: Record<string, unknown>) {
+  return {
+    id: user.id,
+    email: user.email,
+    name: user.name,
+    profile_picture_url: user.profile_picture_url ?? null,
+    deleted_at: user.deleted_at ?? null,
+    created_at: user.created_at,
+  };
+}
+
+/**
+ * Derive a fast, constant-length lookup key from a raw reset token.
+ * HMAC-SHA256 with the JWT secret as the key — not a secret in itself,
+ * but prevents offline dictionary attacks against the stored hashes.
+ */
+function hmacToken(rawToken: string): string {
+  return crypto
+    .createHmac('sha256', config.jwtSecret)
+    .update(rawToken)
+    .digest('hex');
+}
+
+export const authService = {
+  async signup(email: string, password: string, name: string) {
+    const existing = await db('users')
+      .whereRaw('LOWER(email) = LOWER(?)', [email])
+      .first();
+
+    if (existing) {
+      throw createError('Email already registered.', 409, 'CONFLICT');
+    }
+
+    const password_hash = await bcrypt.hash(password, BCRYPT_ROUNDS);
+
+    const [user] = await db('users')
+      .insert({
+        email: email.toLowerCase(),
+        password_hash,
+        name,
+      })
+      .returning('*');
+
+    const { token, expiresAt } = signToken(user.id);
+
+    return {
+      user: formatUser(user),
+      token,
+      expires_at: expiresAt.toISOString(),
+    };
+  },
+
+  async signin(email: string, password: string) {
+    const user = await db('users')
+      .whereRaw('LOWER(email) = LOWER(?)', [email])
+      .first();
+
+    if (!user) {
+      throw createError('Invalid credentials.', 401, 'UNAUTHORIZED');
+    }
+
+    if (!user.password_hash) {
+      throw createError('Invalid credentials.', 401, 'UNAUTHORIZED');
+    }
+
+    const valid = await bcrypt.compare(password, user.password_hash);
+    if (!valid) {
+      throw createError('Invalid credentials.', 401, 'UNAUTHORIZED');
+    }
+
+    if (user.deleted_at) {
+      const err = createError('Account is pending deletion.', 403, 'ACCOUNT_PENDING_DELETION');
+      (err as Record<string, unknown>).deletion_scheduled_at = user.deletion_scheduled_at;
+      throw err;
+    }
+
+    const { token, expiresAt } = signToken(user.id);
+
+    return {
+      user: formatUser(user),
+      token,
+      expires_at: expiresAt.toISOString(),
+    };
+  },
+
+  async googleAuth(idToken: string) {
+    let ticket;
+    try {
+      ticket = await googleClient.verifyIdToken({
+        idToken,
+        audience: config.googleClientId,
+      });
+    } catch {
+      throw createError('Google token verification failed.', 401, 'INVALID_GOOGLE_TOKEN');
+    }
+
+    const payload = ticket.getPayload();
+    if (!payload || !payload.email) {
+      throw createError('Google token verification failed.', 401, 'INVALID_GOOGLE_TOKEN');
+    }
+
+    const { sub: googleId, email, name = '', picture } = payload;
+
+    // Check for existing user by google_id or email
+    let user = await db('users')
+      .where({ google_id: googleId })
+      .orWhereRaw('LOWER(email) = LOWER(?)', [email])
+      .first();
+
+    if (user && user.deleted_at) {
+      const err = createError('Account is pending deletion.', 403, 'ACCOUNT_PENDING_DELETION');
+      (err as Record<string, unknown>).deletion_scheduled_at = user.deletion_scheduled_at;
+      throw err;
+    }
+
+    let isNewUser = false;
+
+    if (!user) {
+      [user] = await db('users')
+        .insert({
+          email: email.toLowerCase(),
+          google_id: googleId,
+          name,
+          profile_picture_url: picture ?? null,
+          email_verified: true,
+        })
+        .returning('*');
+      isNewUser = true;
+    } else if (!user.google_id) {
+      // Link google account to existing email account
+      [user] = await db('users')
+        .where({ id: user.id })
+        .update({
+          google_id: googleId,
+          profile_picture_url: user.profile_picture_url ?? picture ?? null,
+          email_verified: true,
+          updated_at: db.fn.now(),
+        })
+        .returning('*');
+    }
+
+    const { token, expiresAt } = signToken(user.id);
+
+    return {
+      user: formatUser(user),
+      token,
+      expires_at: expiresAt.toISOString(),
+      is_new_user: isNewUser,
+    };
+  },
+
+  async requestPasswordReset(email: string) {
+    const user = await db('users')
+      .whereRaw('LOWER(email) = LOWER(?)', [email])
+      .whereNull('deleted_at')
+      .first();
+
+    // Always return success — prevents email enumeration
+    if (!user) return;
+
+    // Invalidate any existing unused tokens
+    await db('password_reset_tokens')
+      .where({ user_id: user.id })
+      .whereNull('used_at')
+      .update({ used_at: db.fn.now() });
+
+    const rawToken = crypto.randomBytes(32).toString('hex');
+    const token_hash = await bcrypt.hash(rawToken, BCRYPT_ROUNDS);
+    const lookup_hash = hmacToken(rawToken);
+    const expires_at = new Date(
+      Date.now() + PASSWORD_RESET_EXPIRES_HOURS * 60 * 60 * 1000
+    ).toISOString();
+
+    await db('password_reset_tokens').insert({
+      user_id: user.id,
+      token_hash,
+      lookup_hash,
+      expires_at,
+    });
+
+    await emailService.sendPasswordReset(user.email, rawToken);
+  },
+
+  async confirmPasswordReset(rawToken: string, newPassword: string) {
+    // Derive the lookup key and fetch the single matching row — no full-table scan
+    const lookup_hash = hmacToken(rawToken);
+
+    const candidate = await db('password_reset_tokens')
+      .where({ lookup_hash })
+      .whereNull('used_at')
+      .where('expires_at', '>', db.fn.now())
+      .first();
+
+    if (!candidate) {
+      throw createError('Token is invalid or has expired.', 401, 'INVALID_TOKEN');
+    }
+
+    // bcrypt-verify the raw token against the stored hash
+    const valid = await bcrypt.compare(rawToken, candidate.token_hash);
+    if (!valid) {
+      throw createError('Token is invalid or has expired.', 401, 'INVALID_TOKEN');
+    }
+
+    const password_hash = await bcrypt.hash(newPassword, BCRYPT_ROUNDS);
+
+    await db.transaction(async (trx) => {
+      await trx('users')
+        .where({ id: candidate.user_id })
+        .update({ password_hash, updated_at: trx.fn.now() });
+
+      await trx('password_reset_tokens')
+        .where({ id: candidate.id })
+        .update({ used_at: trx.fn.now() });
+    });
+  },
+
+  async deleteAccount(userId: string) {
+    const deletionScheduledAt = new Date(
+      Date.now() + ACCOUNT_DELETION_DAYS * 24 * 60 * 60 * 1000
+    ).toISOString();
+
+    await db('users').where({ id: userId }).update({
+      deleted_at: db.fn.now(),
+      deletion_scheduled_at: deletionScheduledAt,
+      updated_at: db.fn.now(),
+    });
+  },
+
+  async restoreAccount(userId: string) {
+    const user = await db('users').where({ id: userId }).first();
+
+    if (!user) {
+      throw createError('Account not found.', 410, 'GONE');
+    }
+
+    if (!user.deleted_at) {
+      // Not deleted — nothing to restore, just return user
+      return formatUser(user);
+    }
+
+    if (user.deletion_scheduled_at && new Date(user.deletion_scheduled_at) <= new Date()) {
+      throw createError('Account restoration window has expired.', 410, 'GONE');
+    }
+
+    const [restored] = await db('users')
+      .where({ id: userId })
+      .update({
+        deleted_at: null,
+        deletion_scheduled_at: null,
+        updated_at: db.fn.now(),
+      })
+      .returning('*');
+
+    return formatUser(restored);
+  },
+};

src/services/emailService.ts

@@ -0,0 +1,29 @@
+import { config } from '../config/env';
+import { logger } from '../utils/logger';
+
+export const emailService = {
+  async sendPasswordReset(toEmail: string, rawToken: string): Promise<void> {
+    const resetUrl = `${config.passwordResetUrl}?token=${rawToken}`;
+
+    if (config.isTest || !config.sendgridApiKey) {
+      logger.info({ toEmail, resetUrl }, 'Password reset email (not sent in test/dev without key)');
+      return;
+    }
+
+    try {
+      const sgMail = await import('@sendgrid/mail');
+      sgMail.default.setApiKey(config.sendgridApiKey);
+
+      await sgMail.default.send({
+        to: toEmail,
+        from: config.sendgridFromEmail,
+        subject: 'Reset your Pantree password',
+        text: `Click the link to reset your password: ${resetUrl}\n\nThis link expires in 1 hour.`,
+        html: `<p>Click the link to reset your password:</p><p><a href="${resetUrl}">${resetUrl}</a></p><p>This link expires in 1 hour.</p>`,
+      });
+    } catch (err) {
+      logger.error({ err }, 'Failed to send password reset email');
+      // Do not throw — prevents email enumeration via timing
+    }
+  },
+};

src/services/pantryService.ts

@@ -0,0 +1,73 @@
+import db from '../db/connection';
+import { createError } from '../middleware/errorHandler';
+
+export const pantryService = {
+  async getItems(userId: string) {
+    const items = await db('pantry_items')
+      .where({ user_id: userId })
+      .select('id', 'item_name', 'quantity', 'last_modified', 'created_at')
+      .orderBy('item_name_lower', 'asc');
+
+    return items;
+  },
+
+  async addItem(userId: string, itemName: string, quantity: number) {
+    const existing = await db('pantry_items')
+      .where({ user_id: userId, item_name_lower: itemName.toLowerCase() })
+      .first();
+
+    if (existing) {
+      throw createError(
+        `Item '${itemName}' already exists in your pantry.`,
+        409,
+        'DUPLICATE_ITEM'
+      );
+    }
+
+    const [item] = await db('pantry_items')
+      .insert({
+        user_id: userId,
+        item_name: itemName,
+        item_name_lower: itemName.toLowerCase(),
+        quantity,
+        last_modified: db.fn.now(),
+      })
+      .returning(['id', 'item_name', 'quantity', 'last_modified', 'created_at']);
+
+    return item;
+  },
+
+  async updateItem(userId: string, itemId: string, quantity: number) {
+    const [item] = await db('pantry_items')
+      .where({ id: itemId, user_id: userId })
+      .update({
+        quantity,
+        last_modified: db.fn.now(),
+        updated_at: db.fn.now(),
+      })
+      .returning(['id', 'item_name', 'quantity', 'last_modified', 'created_at']);
+
+    if (!item) {
+      throw createError('Pantry item not found.', 404, 'NOT_FOUND');
+    }
+
+    return item;
+  },
+
+  async deleteItem(userId: string, itemId: string) {
+    const deleted = await db('pantry_items')
+      .where({ id: itemId, user_id: userId })
+      .delete();
+
+    if (!deleted) {
+      throw createError('Pantry item not found.', 404, 'NOT_FOUND');
+    }
+
+    // Record tombstone for sync
+    await db('deleted_records').insert({
+      user_id: userId,
+      table_name: 'pantry_items',
+      record_id: itemId,
+    });
+  },
+};

src/services/recipeService.ts

@@ -0,0 +1,136 @@
+import db from '../db/connection';
+import { createError } from '../middleware/errorHandler';
+import { DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT } from '../config/constants';
+
+export const recipeService = {
+  async getRecipes(
+    userId: string,
+    filter: 'all' | 'can_make' | 'can_partially_make',
+    page: number,
+    limit: number,
+    search?: string
+  ) {
+    const safeLimit = Math.min(limit, MAX_PAGE_LIMIT);
+    const offset = (page - 1) * safeLimit;
+
+    // Get user's pantry item names (lowercase)
+    const pantryItems = await db('pantry_items')
+      .where({ user_id: userId })
+      .pluck('item_name_lower');
+
+    const pantrySet = new Set(pantryItems);
+
+    // Base query
+    let query = db('recipes').select('recipes.*');
+
+    if (search) {
+      query = query.whereRaw('LOWER(recipes.name) LIKE ?', [`%${search.toLowerCase()}%`]);
+    }
+
+    const allRecipes = await query.orderBy('recipes.name', 'asc');
+
+    // Get ingredients for all recipes in one query
+    const recipeIds = allRecipes.map((r) => r.id);
+    const allIngredients = recipeIds.length
+      ? await db('recipe_ingredients').whereIn('recipe_id', recipeIds)
+      : [];
+
+    const ingredientsByRecipe = new Map<string, typeof allIngredients>();
+    for (const ing of allIngredients) {
+      if (!ingredientsByRecipe.has(ing.recipe_id)) {
+        ingredientsByRecipe.set(ing.recipe_id, []);
+      }
+      ingredientsByRecipe.get(ing.recipe_id)!.push(ing);
+    }
+
+    // Compute availability for each recipe
+    const enriched = allRecipes.map((recipe) => {
+      const ingredients = ingredientsByRecipe.get(recipe.id) ?? [];
+      const ingredientCount = ingredients.length;
+      const availableCount = ingredients.filter((i) =>
+        pantrySet.has(i.item_name_lower)
+      ).length;
+      const canMake = ingredientCount > 0 && availableCount === ingredientCount;
+      const canPartiallyMake = availableCount > 0 && availableCount < ingredientCount;
+      const availabilityPct =
+        ingredientCount > 0
+          ? parseFloat(((availableCount / ingredientCount) * 100).toFixed(2))
+          : 0;
+
+      return {
+        id: recipe.id,
+        name: recipe.name,
+        servings: recipe.servings,
+        ingredient_count: ingredientCount,
+        available_ingredient_count: availableCount,
+        can_make: canMake,
+        can_partially_make: canPartiallyMake,
+        availability_percentage: availabilityPct,
+      };
+    });
+
+    // Apply filter
+    let filtered = enriched;
+    if (filter === 'can_make') {
+      filtered = enriched.filter((r) => r.can_make);
+    } else if (filter === 'can_partially_make') {
+      filtered = enriched.filter((r) => r.can_partially_make);
+    }
+
+    const total = filtered.length;
+    const totalPages = Math.ceil(total / safeLimit);
+    const paginated = filtered.slice(offset, offset + safeLimit);
+
+    return {
+      recipes: paginated,
+      pagination: {
+        page,
+        limit: safeLimit,
+        total,
+        total_pages: totalPages,
+      },
+    };
+  },
+
+  async getRecipeById(recipeId: string, userId: string, scaleFactor: number) {
+    const recipe = await db('recipes').where({ id: recipeId }).first();
+
+    if (!recipe) {
+      throw createError('Recipe not found.', 404, 'NOT_FOUND');
+    }
+
+    const ingredients = await db('recipe_ingredients').where({ recipe_id: recipeId });
+
+    const pantryItems = await db('pantry_items')
+      .where({ user_id: userId })
+      .pluck('item_name_lower');
+
+    const pantrySet = new Set(pantryItems);
+
+    const scaledIngredients = ingredients.map((ing) => ({
+      id: ing.id,
+      item_name: ing.item_name,
+      quantity: parseFloat((parseFloat(ing.quantity) * scaleFactor).toFixed(4)),
+      original_quantity: parseFloat(ing.quantity),
+      unit: ing.unit,
+      in_pantry: pantrySet.has(ing.item_name_lower),
+    }));
+
+    const availableCount = scaledIngredients.filter((i) => i.in_pantry).length;
+    const canMake =
+      scaledIngredients.length > 0 && availableCount === scaledIngredients.length;
+
+    return {
+      id: recipe.id,
+      name: recipe.name,
+      servings: recipe.servings,
+      scaled_servings: recipe.servings * scaleFactor,
+      scale_factor: scaleFactor,
+      instructions: recipe.instructions,
+      ingredients: scaledIngredients,
+      can_make: canMake,
+      available_ingredient_count: availableCount,
+      ingredient_count: scaledIngredients.length,
+    };
+  },
+};

src/services/shoppingListService.ts

@@ -0,0 +1,267 @@
+import db from '../db/connection';
+import { createError } from '../middleware/errorHandler';
+
+async function getListForUser(listId: string, userId: string) {
+  const list = await db('shopping_lists')
+    .where({ id: listId, user_id: userId })
+    .first();
+
+  if (!list) {
+    throw createError('Shopping list not found.', 404, 'NOT_FOUND');
+  }
+
+  return list;
+}
+
+export const shoppingListService = {
+  async getLists(userId: string) {
+    const lists = await db('shopping_lists')
+      .where({ user_id: userId })
+      .select('id', 'list_name', 'last_modified', 'created_at')
+      .orderBy('created_at', 'desc');
+
+    // Get item counts in one query
+    const listIds = lists.map((l) => l.id);
+    const counts = listIds.length
+      ? await db('shopping_list_items')
+          .whereIn('shopping_list_id', listIds)
+          .select('shopping_list_id')
+          .count('id as item_count')
+          .sum(db.raw('CASE WHEN checked_off THEN 1 ELSE 0 END as checked_count'))
+          .groupBy('shopping_list_id')
+      : [];
+
+    const countMap = new Map(
+      counts.map((c) => [
+        c.shopping_list_id,
+        { item_count: parseInt(String(c.item_count), 10), checked_count: parseInt(String(c.checked_count), 10) },
+      ])
+    );
+
+    return lists.map((l) => ({
+      ...l,
+      item_count: countMap.get(l.id)?.item_count ?? 0,
+      checked_count: countMap.get(l.id)?.checked_count ?? 0,
+    }));
+  },
+
+  async createList(userId: string, listName: string) {
+    const [list] = await db('shopping_lists')
+      .insert({ user_id: userId, list_name: listName })
+      .returning(['id', 'list_name', 'last_modified', 'created_at']);
+
+    return { ...list, item_count: 0, checked_count: 0 };
+  },
+
+  async getListById(listId: string, userId: string) {
+    const list = await getListForUser(listId, userId);
+
+    const items = await db('shopping_list_items')
+      .where({ shopping_list_id: listId })
+      .select('id', 'item_name', 'quantity', 'unit', 'checked_off', 'last_modified')
+      .orderBy('item_name_lower', 'asc');
+
+    return {
+      id: list.id,
+      list_name: list.list_name,
+      last_modified: list.last_modified,
+      created_at: list.created_at,
+      items,
+    };
+  },
+
+  async deleteList(listId: string, userId: string) {
+    const deleted = await db('shopping_lists')
+      .where({ id: listId, user_id: userId })
+      .delete();
+
+    if (!deleted) {
+      throw createError('Shopping list not found.', 404, 'NOT_FOUND');
+    }
+
+    await db('deleted_records').insert({
+      user_id: userId,
+      table_name: 'shopping_lists',
+      record_id: listId,
+    });
+  },
+
+  async addItem(
+    listId: string,
+    userId: string,
+    itemName: string,
+    quantity: number,
+    unit: string
+  ) {
+    await getListForUser(listId, userId);
+
+    const existing = await db('shopping_list_items')
+      .where({
+        shopping_list_id: listId,
+        item_name_lower: itemName.toLowerCase(),
+        unit,
+      })
+      .first();
+
+    if (existing) {
+      const previousQuantity = parseFloat(existing.quantity);
+      const newQuantity = previousQuantity + quantity;
+
+      const [updated] = await db('shopping_list_items')
+        .where({ id: existing.id })
+        .update({
+          quantity: newQuantity,
+          last_modified: db.fn.now(),
+          updated_at: db.fn.now(),
+        })
+        .returning(['id', 'item_name', 'quantity', 'unit', 'checked_off', 'last_modified']);
+
+      // Update list last_modified
+      await db('shopping_lists')
+        .where({ id: listId })
+        .update({ last_modified: db.fn.now(), updated_at: db.fn.now() });
+
+      return { item: updated, merged: true, previous_quantity: previousQuantity };
+    }
+
+    const [item] = await db('shopping_list_items')
+      .insert({
+        shopping_list_id: listId,
+        item_name: itemName,
+        item_name_lower: itemName.toLowerCase(),
+        quantity,
+        unit,
+        last_modified: db.fn.now(),
+      })
+      .returning(['id', 'item_name', 'quantity', 'unit', 'checked_off', 'last_modified']);
+
+    await db('shopping_lists')
+      .where({ id: listId })
+      .update({ last_modified: db.fn.now(), updated_at: db.fn.now() });
+
+    return { item, merged: false };
+  },
+
+  async addRecipesToList(
+    listId: string,
+    userId: string,
+    recipeIds: string[],
+    scaleFactor: number
+  ) {
+    await getListForUser(listId, userId);
+
+    // Validate all recipes exist
+    const recipes = await db('recipes').whereIn('id', recipeIds).select('id');
+    if (recipes.length !== recipeIds.length) {
+      throw createError('One or more recipes not found.', 404, 'NOT_FOUND');
+    }
+
+    const ingredients = await db('recipe_ingredients').whereIn('recipe_id', recipeIds);
+
+    let itemsMerged = 0;
+    let itemsCreated = 0;
+
+    await db.transaction(async (trx) => {
+      for (const ing of ingredients) {
+        const scaledQty = parseFloat(ing.quantity) * scaleFactor;
+
+        const existing = await trx('shopping_list_items')
+          .where({
+            shopping_list_id: listId,
+            item_name_lower: ing.item_name_lower,
+            unit: ing.unit,
+          })
+          .first();
+
+        if (existing) {
+          await trx('shopping_list_items')
+            .where({ id: existing.id })
+            .update({
+              quantity: parseFloat(existing.quantity) + scaledQty,
+              last_modified: trx.fn.now(),
+              updated_at: trx.fn.now(),
+            });
+          itemsMerged++;
+        } else {
+          await trx('shopping_list_items').insert({
+            shopping_list_id: listId,
+            item_name: ing.item_name,
+            item_name_lower: ing.item_name_lower,
+            quantity: scaledQty,
+            unit: ing.unit,
+            last_modified: trx.fn.now(),
+          });
+          itemsCreated++;
+        }
+      }
+
+      await trx('shopping_lists')
+        .where({ id: listId })
+        .update({ last_modified: trx.fn.now(), updated_at: trx.fn.now() });
+    });
+
+    const updatedList = await this.getListById(listId, userId);
+
+    return {
+      shopping_list: updatedList,
+      recipes_added: recipeIds.length,
+      items_merged: itemsMerged,
+      items_created: itemsCreated,
+    };
+  },
+
+  async updateItem(
+    listId: string,
+    itemId: string,
+    userId: string,
+    updates: { quantity?: number; unit?: string; checked_off?: boolean }
+  ) {
+    await getListForUser(listId, userId);
+
+    const updateData: Record<string, unknown> = {
+      last_modified: db.fn.now(),
+      updated_at: db.fn.now(),
+    };
+
+    if (updates.quantity !== undefined) updateData.quantity = updates.quantity;
+    if (updates.unit !== undefined) updateData.unit = updates.unit;
+    if (updates.checked_off !== undefined) updateData.checked_off = updates.checked_off;
+
+    const [item] = await db('shopping_list_items')
+      .where({ id: itemId, shopping_list_id: listId })
+      .update(updateData)
+      .returning(['id', 'item_name', 'quantity', 'unit', 'checked_off', 'last_modified']);
+
+    if (!item) {
+      throw createError('Shopping list item not found.', 404, 'NOT_FOUND');
+    }
+
+    await db('shopping_lists')
+      .where({ id: listId })
+      .update({ last_modified: db.fn.now(), updated_at: db.fn.now() });
+
+    return item;
+  },
+
+  async deleteItem(listId: string, itemId: string, userId: string) {
+    await getListForUser(listId, userId);
+
+    const deleted = await db('shopping_list_items')
+      .where({ id: itemId, shopping_list_id: listId })
+      .delete();
+
+    if (!deleted) {
+      throw createError('Shopping list item not found.', 404, 'NOT_FOUND');
+    }
+
+    await db('deleted_records').insert({
+      user_id: userId,
+      table_name: 'shopping_list_items',
+      record_id: itemId,
+    });
+
+    await db('shopping_lists')
+      .where({ id: listId })
+      .update({ last_modified: db.fn.now(), updated_at: db.fn.now() });
+  },
+};

src/services/syncService.ts

@@ -0,0 +1,75 @@
+import db from '../db/connection';
+import { TOMBSTONE_RETENTION_DAYS } from '../config/constants';
+
+export const syncService = {
+  async getDelta(userId: string, since: string) {
+    const serverTimestamp = new Date().toISOString();
+
+    // Pantry: updated items
+    const updatedPantry = await db('pantry_items')
+      .where({ user_id: userId })
+      .where('last_modified', '>', since)
+      .select('id', 'item_name', 'quantity', 'last_modified');
+
+    // Pantry: deleted items
+    const deletedPantry = await db('deleted_records')
+      .where({ user_id: userId, table_name: 'pantry_items' })
+      .where('deleted_at', '>', since)
+      .pluck('record_id');
+
+    // Shopping lists: updated
+    const updatedLists = await db('shopping_lists')
+      .where({ user_id: userId })
+      .where('last_modified', '>', since)
+      .select('id', 'list_name', 'last_modified');
+
+    // For each updated list, get updated/deleted items
+    const listsWithItems = await Promise.all(
+      updatedLists.map(async (list) => {
+        const updatedItems = await db('shopping_list_items')
+          .where({ shopping_list_id: list.id })
+          .where('last_modified', '>', since)
+          .select('id', 'item_name', 'quantity', 'unit', 'checked_off', 'last_modified');
+
+        const deletedItems = await db('deleted_records')
+          .where({ user_id: userId, table_name: 'shopping_list_items' })
+          .where('deleted_at', '>', since)
+          .pluck('record_id');
+
+        return {
+          ...list,
+          items: {
+            updated: updatedItems,
+            deleted: deletedItems,
+          },
+        };
+      })
+    );
+
+    // Deleted shopping lists
+    const deletedLists = await db('deleted_records')
+      .where({ user_id: userId, table_name: 'shopping_lists' })
+      .where('deleted_at', '>', since)
+      .pluck('record_id');
+
+    return {
+      server_timestamp: serverTimestamp,
+      pantry: {
+        updated: updatedPantry,
+        deleted: deletedPantry,
+      },
+      shopping_lists: {
+        updated: listsWithItems,
+        deleted: deletedLists,
+      },
+    };
+  },
+
+  async cleanupTombstones() {
+    const cutoff = new Date(
+      Date.now() - TOMBSTONE_RETENTION_DAYS * 24 * 60 * 60 * 1000
+    ).toISOString();
+
+    await db('deleted_records').where('deleted_at', '<', cutoff).delete();
+  },
+};

src/test/helpers.ts

@@ -0,0 +1,37 @@
+import db from '../db/connection';
+import bcrypt from 'bcrypt';
+
+export async function createTestUser(overrides: Partial<{
+  email: string;
+  password: string;
+  name: string;
+  deleted_at: string | null;
+  deletion_scheduled_at: string | null;
+}> = {}) {
+  const email = overrides.email ?? `test_${Date.now()}@example.com`;
+  const password = overrides.password ?? 'password123';
+  const name = overrides.name ?? 'Test User';
+
+  const password_hash = await bcrypt.hash(password, 4); // Low rounds for test speed
+
+  const [user] = await db('users')
+    .insert({
+      email: email.toLowerCase(),
+      password_hash,
+      name,
+      deleted_at: overrides.deleted_at ?? null,
+      deletion_scheduled_at: overrides.deletion_scheduled_at ?? null,
+    })
+    .returning('*');
+
+  return { user, password };
+}
+
+export async function cleanupTestData() {
+  await db('deleted_records').delete();
+  await db('shopping_list_items').delete();
+  await db('shopping_lists').delete();
+  await db('pantry_items').delete();
+  await db('password_reset_tokens').delete();
+  await db('users').delete();
+}

src/test/routes/auth.test.ts

@@ -0,0 +1,184 @@
+import request from 'supertest';
+import { createApp } from '../../app';
+import db from '../../db/connection';
+import { createTestUser, cleanupTestData } from '../helpers';
+import { signToken } from '../../utils/jwt';
+
+const app = createApp();
+
+beforeEach(async () => {
+  await cleanupTestData();
+});
+
+afterAll(async () => {
+  await cleanupTestData();
+  await db.destroy();
+});
+
+describe('POST /v1/auth/signup', () => {
+  it('creates a new user and returns token', async () => {
+    const res = await request(app).post('/v1/auth/signup').send({
+      email: 'newuser@example.com',
+      password: 'password123',
+      name: 'New User',
+    });
+
+    expect(res.status).toBe(201);
+    expect(res.body.user.email).toBe('newuser@example.com');
+    expect(res.body.token).toBeDefined();
+    expect(res.body.expires_at).toBeDefined();
+  });
+
+  it('returns 409 for duplicate email', async () => {
+    await createTestUser({ email: 'dup@example.com' });
+
+    const res = await request(app).post('/v1/auth/signup').send({
+      email: 'dup@example.com',
+      password: 'password123',
+      name: 'Dup User',
+    });
+
+    expect(res.status).toBe(409);
+    expect(res.body.code).toBe('CONFLICT');
+  });
+
+  it('returns 400 for invalid email', async () => {
+    const res = await request(app).post('/v1/auth/signup').send({
+      email: 'not-an-email',
+      password: 'password123',
+      name: 'User',
+    });
+    expect(res.status).toBe(400);
+    expect(res.body.code).toBe('VALIDATION_ERROR');
+  });
+
+  it('returns 400 for short password', async () => {
+    const res = await request(app).post('/v1/auth/signup').send({
+      email: 'user@example.com',
+      password: 'short',
+      name: 'User',
+    });
+    expect(res.status).toBe(400);
+  });
+});
+
+describe('POST /v1/auth/signin', () => {
+  it('signs in with valid credentials', async () => {
+    await createTestUser({ email: 'signin@example.com', password: 'mypassword1' });
+
+    const res = await request(app).post('/v1/auth/signin').send({
+      email: 'signin@example.com',
+      password: 'mypassword1',
+    });
+
+    expect(res.status).toBe(200);
+    expect(res.body.token).toBeDefined();
+  });
+
+  it('returns 401 for wrong password', async () => {
+    await createTestUser({ email: 'wrong@example.com', password: 'correctpass1' });
+
+    const res = await request(app).post('/v1/auth/signin').send({
+      email: 'wrong@example.com',
+      password: 'wrongpassword1',
+    });
+
+    expect(res.status).toBe(401);
+    expect(res.body.code).toBe('UNAUTHORIZED');
+  });
+
+  it('returns 401 for non-existent user', async () => {
+    const res = await request(app).post('/v1/auth/signin').send({
+      email: 'nobody@example.com',
+      password: 'password123',
+    });
+    expect(res.status).toBe(401);
+  });
+
+  it('returns 403 for soft-deleted account', async () => {
+    const futureDate = new Date(Date.now() + 10 * 24 * 60 * 60 * 1000).toISOString();
+    await createTestUser({
+      email: 'deleted@example.com',
+      password: 'password123',
+      deleted_at: new Date().toISOString(),
+      deletion_scheduled_at: futureDate,
+    });
+
+    const res = await request(app).post('/v1/auth/signin').send({
+      email: 'deleted@example.com',
+      password: 'password123',
+    });
+
+    expect(res.status).toBe(403);
+    expect(res.body.code).toBe('ACCOUNT_PENDING_DELETION');
+    expect(res.body.deletion_scheduled_at).toBeDefined();
+  });
+});
+
+describe('DELETE /v1/auth/account', () => {
+  it('soft-deletes the authenticated user', async () => {
+    const { user } = await createTestUser();
+    const { token } = signToken(user.id);
+
+    const res = await request(app)
+      .delete('/v1/auth/account')
+      .set('Authorization', `Bearer ${token}`);
+
+    expect(res.status).toBe(204);
+
+    const updated = await db('users').where({ id: user.id }).first();
+    expect(updated.deleted_at).not.toBeNull();
+    expect(updated.deletion_scheduled_at).not.toBeNull();
+  });
+
+  it('returns 401 without token', async () => {
+    const res = await request(app).delete('/v1/auth/account');
+    expect(res.status).toBe(401);
+  });
+});
+
+describe('POST /v1/auth/restore-account', () => {
+  it('restores a soft-deleted account', async () => {
+    const futureDate = new Date(Date.now() + 10 * 24 * 60 * 60 * 1000).toISOString();
+    const { user } = await createTestUser({
+      deleted_at: new Date().toISOString(),
+      deletion_scheduled_at: futureDate,
+    });
+    const { token } = signToken(user.id);
+
+    // Temporarily bypass the auth middleware deleted_at check for restore
+    // by directly calling the endpoint (auth middleware allows restore-account path)
+    const res = await request(app)
+      .post('/v1/auth/restore-account')
+      .set('Authorization', `Bearer ${token}`);
+
+    expect(res.status).toBe(200);
+    expect(res.body.user.deleted_at).toBeNull();
+  });
+});
+
+describe('POST /v1/auth/password-reset', () => {
+  it('always returns 200 regardless of email existence', async () => {
+    const res = await request(app)
+      .post('/v1/auth/password-reset')
+      .send({ email: 'nonexistent@example.com' });
+
+    expect(res.status).toBe(200);
+    expect(res.body.message).toContain('If an account exists');
+  });
+
+  it('returns 400 for invalid email', async () => {
+    const res = await request(app)
+      .post('/v1/auth/password-reset')
+      .send({ email: 'not-valid' });
+    expect(res.status).toBe(400);
+  });
+});
+
+describe('GET /health', () => {
+  it('returns 200 with status ok', async () => {
+    const res = await request(app).get('/health');
+    expect(res.status).toBe(200);
+    expect(res.body.status).toBe('ok');
+  });
+});

src/test/routes/pantry.test.ts

@@ -0,0 +1,163 @@
+import request from 'supertest';
+import { createApp } from '../../app';
+import db from '../../db/connection';
+import { createTestUser, cleanupTestData } from '../helpers';
+import { signToken } from '../../utils/jwt';
+
+const app = createApp();
+
+let userId: string;
+let token: string;
+
+beforeEach(async () => {
+  await cleanupTestData();
+  const { user } = await createTestUser();
+  userId = user.id;
+  token = signToken(userId).token;
+});
+
+afterAll(async () => {
+  await cleanupTestData();
+  await db.destroy();
+});
+
+describe('GET /v1/pantry', () => {
+  it('returns empty pantry for new user', async () => {
+    const res = await request(app)
+      .get('/v1/pantry')
+      .set('Authorization', `Bearer ${token}`);
+
+    expect(res.status).toBe(200);
+    expect(res.body.items).toEqual([]);
+    expect(res.body.synced_at).toBeDefined();
+  });
+
+  it('returns 401 without token', async () => {
+    const res = await request(app).get('/v1/pantry');
+    expect(res.status).toBe(401);
+  });
+});
+
+describe('POST /v1/pantry', () => {
+  it('adds a new pantry item', async () => {
+    const res = await request(app)
+      .post('/v1/pantry')
+      .set('Authorization', `Bearer ${token}`)
+      .send({ item_name: 'Flour', quantity: 5 });
+
+    expect(res.status).toBe(201);
+    expect(res.body.item.item_name).toBe('Flour');
+    expect(res.body.item.quantity).toBe(5);
+  });
+
+  it('returns 409 for duplicate item (case-insensitive)', async () => {
+    await request(app)
+      .post('/v1/pantry')
+      .set('Authorization', `Bearer ${token}`)
+      .send({ item_name: 'Flour', quantity: 5 });
+
+    const res = await request(app)
+      .post('/v1/pantry')
+      .set('Authorization', `Bearer ${token}`)
+      .send({ item_name: 'flour', quantity: 3 });
+
+    expect(res.status).toBe(409);
+    expect(res.body.code).toBe('DUPLICATE_ITEM');
+  });
+
+  it('returns 400 for invalid quantity', async () => {
+    const res = await request(app)
+      .post('/v1/pantry')
+      .set('Authorization', `Bearer ${token}`)
+      .send({ item_name: 'Flour', quantity: 0 });
+
+    expect(res.status).toBe(400);
+  });
+
+  it('returns 400 for fractional quantity', async () => {
+    const res = await request(app)
+      .post('/v1/pantry')
+      .set('Authorization', `Bearer ${token}`)
+      .send({ item_name: 'Flour', quantity: 1.5 });
+
+    expect(res.status).toBe(400);
+  });
+});
+
+describe('PUT /v1/pantry/:item_id', () => {
+  it('updates pantry item quantity', async () => {
+    const createRes = await request(app)
+      .post('/v1/pantry')
+      .set('Authorization', `Bearer ${token}`)
+      .send({ item_name: 'Butter', quantity: 2 });
+
+    const itemId = createRes.body.item.id;
+
+    const res = await request(app)
+      .put(`/v1/pantry/${itemId}`)
+      .set('Authorization', `Bearer ${token}`)
+      .send({ quantity: 7 });
+
+    expect(res.status).toBe(200);
+    expect(res.body.item.quantity).toBe(7);
+  });
+
+  it('returns 404 for non-existent item', async () => {
+    const res = await request(app)
+      .put('/v1/pantry/00000000-0000-0000-0000-000000000000')
+      .set('Authorization', `Bearer ${token}`)
+      .send({ quantity: 5 });
+
+    expect(res.status).toBe(404);
+  });
+
+  it('cannot update another user\'s item', async () => {
+    const { user: otherUser } = await createTestUser({ email: 'other@example.com' });
+    const otherToken = signToken(otherUser.id).token;
+
+    const createRes = await request(app)
+      .post('/v1/pantry')
+      .set('Authorization', `Bearer ${token}`)
+      .send({ item_name: 'Sugar', quantity: 3 });
+
+    const itemId = createRes.body.item.id;
+
+    const res = await request(app)
+      .put(`/v1/pantry/${itemId}`)
+      .set('Authorization', `Bearer ${otherToken}`)
+      .send({ quantity: 10 });
+
+    expect(res.status).toBe(404);
+  });
+});
+
+describe('DELETE /v1/pantry/:item_id', () => {
+  it('deletes a pantry item', async () => {
+    const createRes = await request(app)
+      .post('/v1/pantry')
+      .set('Authorization', `Bearer ${token}`)
+      .send({ item_name: 'Salt', quantity: 1 });
+
+    const itemId = createRes.body.item.id;
+
+    const res = await request(app)
+      .delete(`/v1/pantry/${itemId}`)
+      .set('Authorization', `Bearer ${token}`);
+
+    expect(res.status).toBe(204);
+
+    // Verify tombstone created
+    const tombstone = await db('deleted_records')
+      .where({ record_id: itemId, table_name: 'pantry_items' })
+      .first();
+    expect(tombstone).toBeDefined();
+  });
+
+  it('returns 404 for non-existent item', async () => {
+    const res = await request(app)
+      .delete('/v1/pantry/00000000-0000-0000-0000-000000000000')
+      .set('Authorization', `Bearer ${token}`);
+
+    expect(res.status).toBe(404);
+  });
+});

src/test/routes/recipes.test.ts

@@ -0,0 +1,148 @@
+import request from 'supertest';
+import { createApp } from '../../app';
+import db from '../../db/connection';
+import { createTestUser, cleanupTestData } from '../helpers';
+import { signToken } from '../../utils/jwt';
+
+const app = createApp();
+
+let userId: string;
+let token: string;
+
+beforeAll(async () => {
+  await cleanupTestData();
+  // Seed a test recipe
+  const [recipe] = await db('recipes')
+    .insert({
+      name: 'Test Cookies',
+      servings: 12,
+      instructions: 'Mix and bake.',
+    })
+    .returning('*');
+
+  await db('recipe_ingredients').insert([
+    { recipe_id: recipe.id, item_name: 'Flour', item_name_lower: 'flour', quantity: 2, unit: 'cups' },
+    { recipe_id: recipe.id, item_name: 'Sugar', item_name_lower: 'sugar', quantity: 1, unit: 'cups' },
+    { recipe_id: recipe.id, item_name: 'Butter', item_name_lower: 'butter', quantity: 0.5, unit: 'cups' },
+  ]);
+});
+
+beforeEach(async () => {
+  await db('pantry_items').delete();
+  await db('users').delete();
+  const { user } = await createTestUser();
+  userId = user.id;
+  token = signToken(userId).token;
+});
+
+afterAll(async () => {
+  await cleanupTestData();
+  await db.destroy();
+});
+
+describe('GET /v1/recipes', () => {
+  it('returns all recipes with pagination', async () => {
+    const res = await request(app)
+      .get('/v1/recipes')
+      .set('Authorization', `Bearer ${token}`);
+
+    expect(res.status).toBe(200);
+    expect(Array.isArray(res.body.recipes)).toBe(true);
+    expect(res.body.pagination).toBeDefined();
+    expect(res.body.synced_at).toBeDefined();
+  });
+
+  it('returns 401 without token', async () => {
+    const res = await request(app).get('/v1/recipes');
+    expect(res.status).toBe(401);
+  });
+
+  it('filters can_make correctly when pantry has all ingredients', async () => {
+    // Add all ingredients to pantry
+    await db('pantry_items').insert([
+      { user_id: userId, item_name: 'Flour', item_name_lower: 'flour', quantity: 5 },
+      { user_id: userId, item_name: 'Sugar', item_name_lower: 'sugar', quantity: 3 },
+      { user_id: userId, item_name: 'Butter', item_name_lower: 'butter', quantity: 2 },
+    ]);
+
+    const res = await request(app)
+      .get('/v1/recipes?filter=can_make')
+      .set('Authorization', `Bearer ${token}`);
+
+    expect(res.status).toBe(200);
+    const testRecipe = res.body.recipes.find((r: { name: string }) => r.name === 'Test Cookies');
+    expect(testRecipe).toBeDefined();
+    expect(testRecipe.can_make).toBe(true);
+  });
+
+  it('filters can_partially_make correctly', async () => {
+    // Add only one ingredient
+    await db('pantry_items').insert([
+      { user_id: userId, item_name: 'Flour', item_name_lower: 'flour', quantity: 5 },
+    ]);
+
+    const res = await request(app)
+      .get('/v1/recipes?filter=can_partially_make')
+      .set('Authorization', `Bearer ${token}`);
+
+    expect(res.status).toBe(200);
+    const testRecipe = res.body.recipes.find((r: { name: string }) => r.name === 'Test Cookies');
+    expect(testRecipe).toBeDefined();
+    expect(testRecipe.can_make).toBe(false);
+  });
+
+  it('returns 400 for invalid filter', async () => {
+    const res = await request(app)
+      .get('/v1/recipes?filter=invalid')
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(400);
+  });
+});
+
+describe('GET /v1/recipes/:recipe_id', () => {
+  it('returns recipe detail with scaling', async () => {
+    const recipe = await db('recipes').where({ name: 'Test Cookies' }).first();
+
+    const res = await request(app)
+      .get(`/v1/recipes/${recipe.id}?scale=2`)
+      .set('Authorization', `Bearer ${token}`);
+
+    expect(res.status).toBe(200);
+    expect(res.body.recipe.scale_factor).toBe(2);
+    expect(res.body.recipe.scaled_servings).toBe(24);
+    const flourIng = res.body.recipe.ingredients.find((i: { item_name: string }) => i.item_name === 'Flour');
+    expect(flourIng.quantity).toBe(4); // 2 * 2
+    expect(flourIng.original_quantity).toBe(2);
+  });
+
+  it('returns 404 for non-existent recipe', async () => {
+    const res = await request(app)
+      .get('/v1/recipes/00000000-0000-0000-0000-000000000000')
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(404);
+  });
+
+  it('returns 400 for invalid scale factor', async () => {
+    const recipe = await db('recipes').where({ name: 'Test Cookies' }).first();
+    const res = await request(app)
+      .get(`/v1/recipes/${recipe.id}?scale=5`)
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(400);
+  });
+
+  it('marks in_pantry correctly', async () => {
+    await db('pantry_items').insert([
+      { user_id: userId, item_name: 'Flour', item_name_lower: 'flour', quantity: 5 },
+    ]);
+
+    const recipe = await db('recipes').where({ name: 'Test Cookies' }).first();
+    const res = await request(app)
+      .get(`/v1/recipes/${recipe.id}`)
+      .set('Authorization', `Bearer ${token}`);
+
+    const flourIng = res.body.recipe.ingredients.find((i: { item_name: string }) => i.item_name === 'Flour');
+    const sugarIng = res.body.recipe.ingredients.find((i: { item_name: string }) => i.item_name === 'Sugar');
+    expect(flourIng.in_pantry).toBe(true);
+    expect(sugarIng.in_pantry).toBe(false);
+  });
+});

src/test/routes/shoppingLists.test.ts

@@ -0,0 +1,277 @@
+import request from 'supertest';
+import { createApp } from '../../app';
+import db from '../../db/connection';
+import { createTestUser, cleanupTestData } from '../helpers';
+import { signToken } from '../../utils/jwt';
+
+const app = createApp();
+
+let userId: string;
+let token: string;
+
+beforeEach(async () => {
+  await cleanupTestData();
+  const { user } = await createTestUser();
+  userId = user.id;
+  token = signToken(userId).token;
+});
+
+afterAll(async () => {
+  await cleanupTestData();
+  await db.destroy();
+});
+
+async function createList(name = 'Test List') {
+  const res = await request(app)
+    .post('/v1/shopping-lists')
+    .set('Authorization', `Bearer ${token}`)
+    .send({ list_name: name });
+  return res.body.shopping_list;
+}
+
+describe('GET /v1/shopping-lists', () => {
+  it('returns empty list for new user', async () => {
+    const res = await request(app)
+      .get('/v1/shopping-lists')
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(200);
+    expect(res.body.shopping_lists).toEqual([]);
+  });
+});
+
+describe('POST /v1/shopping-lists', () => {
+  it('creates a new shopping list', async () => {
+    const res = await request(app)
+      .post('/v1/shopping-lists')
+      .set('Authorization', `Bearer ${token}`)
+      .send({ list_name: 'Groceries' });
+
+    expect(res.status).toBe(201);
+    expect(res.body.shopping_list.list_name).toBe('Groceries');
+    expect(res.body.shopping_list.item_count).toBe(0);
+  });
+
+  it('returns 400 for empty list name', async () => {
+    const res = await request(app)
+      .post('/v1/shopping-lists')
+      .set('Authorization', `Bearer ${token}`)
+      .send({ list_name: '' });
+    expect(res.status).toBe(400);
+  });
+});
+
+describe('GET /v1/shopping-lists/:list_id', () => {
+  it('returns list with items', async () => {
+    const list = await createList();
+
+    const res = await request(app)
+      .get(`/v1/shopping-lists/${list.id}`)
+      .set('Authorization', `Bearer ${token}`);
+
+    expect(res.status).toBe(200);
+    expect(res.body.shopping_list.id).toBe(list.id);
+    expect(res.body.shopping_list.items).toEqual([]);
+  });
+
+  it('returns 404 for non-existent list', async () => {
+    const res = await request(app)
+      .get('/v1/shopping-lists/00000000-0000-0000-0000-000000000000')
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(404);
+  });
+
+  it('cannot access another user\'s list', async () => {
+    const { user: other } = await createTestUser({ email: 'other2@example.com' });
+    const otherToken = signToken(other.id).token;
+    const list = await createList();
+
+    const res = await request(app)
+      .get(`/v1/shopping-lists/${list.id}`)
+      .set('Authorization', `Bearer ${otherToken}`);
+    expect(res.status).toBe(404);
+  });
+});
+
+describe('POST /v1/shopping-lists/:list_id/items', () => {
+  it('adds an item to the list', async () => {
+    const list = await createList();
+
+    const res = await request(app)
+      .post(`/v1/shopping-lists/${list.id}/items`)
+      .set('Authorization', `Bearer ${token}`)
+      .send({ item_name: 'Milk', quantity: 2, unit: 'cups' });
+
+    expect(res.status).toBe(201);
+    expect(res.body.item.item_name).toBe('Milk');
+    expect(res.body.merged).toBe(false);
+  });
+
+  it('merges items with same name and unit', async () => {
+    const list = await createList();
+
+    await request(app)
+      .post(`/v1/shopping-lists/${list.id}/items`)
+      .set('Authorization', `Bearer ${token}`)
+      .send({ item_name: 'Milk', quantity: 2, unit: 'cups' });
+
+    const res = await request(app)
+      .post(`/v1/shopping-lists/${list.id}/items`)
+      .set('Authorization', `Bearer ${token}`)
+      .send({ item_name: 'milk', quantity: 1, unit: 'cups' });
+
+    expect(res.status).toBe(201);
+    expect(res.body.merged).toBe(true);
+    expect(parseFloat(res.body.item.quantity)).toBe(3);
+    expect(res.body.previous_quantity).toBe(2);
+  });
+
+  it('does NOT merge items with same name but different unit', async () => {
+    const list = await createList();
+
+    await request(app)
+      .post(`/v1/shopping-lists/${list.id}/items`)
+      .set('Authorization', `Bearer ${token}`)
+      .send({ item_name: 'Flour', quantity: 2, unit: 'cups' });
+
+    const res = await request(app)
+      .post(`/v1/shopping-lists/${list.id}/items`)
+      .set('Authorization', `Bearer ${token}`)
+      .send({ item_name: 'Flour', quantity: 250, unit: 'g' });
+
+    expect(res.status).toBe(201);
+    expect(res.body.merged).toBe(false);
+
+    const listRes = await request(app)
+      .get(`/v1/shopping-lists/${list.id}`)
+      .set('Authorization', `Bearer ${token}`);
+    expect(listRes.body.shopping_list.items.length).toBe(2);
+  });
+
+  it('returns 400 for invalid unit', async () => {
+    const list = await createList();
+    const res = await request(app)
+      .post(`/v1/shopping-lists/${list.id}/items`)
+      .set('Authorization', `Bearer ${token}`)
+      .send({ item_name: 'Milk', quantity: 2, unit: 'gallons' });
+    expect(res.status).toBe(400);
+  });
+});
+
+describe('PUT /v1/shopping-lists/:list_id/items/:item_id', () => {
+  it('updates item checked_off status', async () => {
+    const list = await createList();
+    const addRes = await request(app)
+      .post(`/v1/shopping-lists/${list.id}/items`)
+      .set('Authorization', `Bearer ${token}`)
+      .send({ item_name: 'Eggs', quantity: 6, unit: 'pieces' });
+
+    const itemId = addRes.body.item.id;
+
+    const res = await request(app)
+      .put(`/v1/shopping-lists/${list.id}/items/${itemId}`)
+      .set('Authorization', `Bearer ${token}`)
+      .send({ checked_off: true });
+
+    expect(res.status).toBe(200);
+    expect(res.body.item.checked_off).toBe(true);
+  });
+
+  it('returns 400 when no fields provided', async () => {
+    const list = await createList();
+    const addRes = await request(app)
+      .post(`/v1/shopping-lists/${list.id}/items`)
+      .set('Authorization', `Bearer ${token}`)
+      .send({ item_name: 'Eggs', quantity: 6, unit: 'pieces' });
+
+    const itemId = addRes.body.item.id;
+
+    const res = await request(app)
+      .put(`/v1/shopping-lists/${list.id}/items/${itemId}`)
+      .set('Authorization', `Bearer ${token}`)
+      .send({});
+
+    expect(res.status).toBe(400);
+  });
+});
+
+describe('DELETE /v1/shopping-lists/:list_id', () => {
+  it('deletes a shopping list', async () => {
+    const list = await createList();
+
+    const res = await request(app)
+      .delete(`/v1/shopping-lists/${list.id}`)
+      .set('Authorization', `Bearer ${token}`);
+
+    expect(res.status).toBe(204);
+  });
+
+  it('returns 404 for non-existent list', async () => {
+    const res = await request(app)
+      .delete('/v1/shopping-lists/00000000-0000-0000-0000-000000000000')
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(404);
+  });
+});
+
+describe('DELETE /v1/shopping-lists/:list_id/items/:item_id', () => {
+  it('deletes an item from the list', async () => {
+    const list = await createList();
+    const addRes = await request(app)
+      .post(`/v1/shopping-lists/${list.id}/items`)
+      .set('Authorization', `Bearer ${token}`)
+      .send({ item_name: 'Butter', quantity: 1, unit: 'cups' });
+
+    const itemId = addRes.body.item.id;
+
+    const res = await request(app)
+      .delete(`/v1/shopping-lists/${list.id}/items/${itemId}`)
+      .set('Authorization', `Bearer ${token}`);
+
+    expect(res.status).toBe(204);
+  });
+});
+
+describe('POST /v1/shopping-lists/:list_id/add-recipes', () => {
+  it('adds recipe ingredients to list', async () => {
+    const [recipe] = await db('recipes')
+      .insert({ name: 'Simple Recipe', servings: 2, instructions: 'Cook it.' })
+      .returning('*');
+
+    await db('recipe_ingredients').insert([
+      { recipe_id: recipe.id, item_name: 'Flour', item_name_lower: 'flour', quantity: 1, unit: 'cups' },
+      { recipe_id: recipe.id, item_name: 'Water', item_name_lower: 'water', quantity: 0.5, unit: 'cups' },
+    ]);
+
+    const list = await createList();
+
+    const res = await request(app)
+      .post(`/v1/shopping-lists/${list.id}/add-recipes`)
+      .set('Authorization', `Bearer ${token}`)
+      .send({ recipe_ids: [recipe.id], scale_factor: 2 });
+
+    expect(res.status).toBe(201);
+    expect(res.body.recipes_added).toBe(1);
+    expect(res.body.items_created).toBe(2);
+
+    const flourItem = res.body.shopping_list.items.find((i: { item_name: string }) => i.item_name === 'Flour');
+    expect(parseFloat(flourItem.quantity)).toBe(2); // 1 * scale 2
+  });
+
+  it('returns 400 for empty recipe_ids', async () => {
+    const list = await createList();
+    const res = await request(app)
+      .post(`/v1/shopping-lists/${list.id}/add-recipes`)
+      .set('Authorization', `Bearer ${token}`)
+      .send({ recipe_ids: [] });
+    expect(res.status).toBe(400);
+  });
+
+  it('returns 404 for non-existent recipe', async () => {
+    const list = await createList();
+    const res = await request(app)
+      .post(`/v1/shopping-lists/${list.id}/add-recipes`)
+      .set('Authorization', `Bearer ${token}`)
+      .send({ recipe_ids: ['00000000-0000-0000-0000-000000000000'] });
+    expect(res.status).toBe(404);
+  });
+});

src/test/routes/sync.test.ts

@@ -0,0 +1,87 @@
+import request from 'supertest';
+import { createApp } from '../../app';
+import db from '../../db/connection';
+import { createTestUser, cleanupTestData } from '../helpers';
+import { signToken } from '../../utils/jwt';
+
+const app = createApp();
+
+let userId: string;
+let token: string;
+
+beforeEach(async () => {
+  await cleanupTestData();
+  const { user } = await createTestUser();
+  userId = user.id;
+  token = signToken(userId).token;
+});
+
+afterAll(async () => {
+  await cleanupTestData();
+  await db.destroy();
+});
+
+describe('GET /v1/sync', () => {
+  it('returns delta since epoch (full sync)', async () => {
+    // Add a pantry item
+    await db('pantry_items').insert({
+      user_id: userId,
+      item_name: 'Flour',
+      item_name_lower: 'flour',
+      quantity: 5,
+    });
+
+    const res = await request(app)
+      .get('/v1/sync?since=1970-01-01T00:00:00.000Z')
+      .set('Authorization', `Bearer ${token}`);
+
+    expect(res.status).toBe(200);
+    expect(res.body.server_timestamp).toBeDefined();
+    expect(res.body.pantry.updated.length).toBe(1);
+    expect(res.body.pantry.updated[0].item_name).toBe('Flour');
+    expect(Array.isArray(res.body.pantry.deleted)).toBe(true);
+    expect(Array.isArray(res.body.shopping_lists.updated)).toBe(true);
+    expect(Array.isArray(res.body.shopping_lists.deleted)).toBe(true);
+  });
+
+  it('returns only items modified since timestamp', async () => {
+    const since = new Date().toISOString();
+
+    // Wait a tick then add item
+    await new Promise((r) => setTimeout(r, 10));
+
+    await db('pantry_items').insert({
+      user_id: userId,
+      item_name: 'Sugar',
+      item_name_lower: 'sugar',
+      quantity: 2,
+    });
+
+    const res = await request(app)
+      .get(`/v1/sync?since=${encodeURIComponent(since)}`)
+      .set('Authorization', `Bearer ${token}`);
+
+    expect(res.status).toBe(200);
+    expect(res.body.pantry.updated.length).toBe(1);
+    expect(res.body.pantry.updated[0].item_name).toBe('Sugar');
+  });
+
+  it('returns 400 for missing since parameter', async () => {
+    const res = await request(app)
+      .get('/v1/sync')
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(400);
+  });
+
+  it('returns 400 for invalid since parameter', async () => {
+    const res = await request(app)
+      .get('/v1/sync?since=not-a-date')
+      .set('Authorization', `Bearer ${token}`);
+    expect(res.status).toBe(400);
+  });
+
+  it('returns 401 without token', async () => {
+    const res = await request(app).get('/v1/sync?since=1970-01-01T00:00:00.000Z');
+    expect(res.status).toBe(401);
+  });
+});

src/test/setup.ts

@@ -0,0 +1,4 @@
+process.env.NODE_ENV = 'test';
+process.env.DATABASE_URL = process.env.TEST_DATABASE_URL ?? 'postgresql://postgres:postgres@localhost:5432/pantree_test';
+process.env.JWT_SECRET = 'test_jwt_secret_that_is_long_enough_for_testing_purposes_only';
+process.env.GOOGLE_CLIENT_ID = 'test_google_client_id';

src/test/utils.test.ts

@@ -0,0 +1,27 @@
+import { createError } from '../../middleware/errorHandler';
+import { signToken } from '../../utils/jwt';
+import jwt from 'jsonwebtoken';
+
+describe('createError', () => {
+  it('creates an error with statusCode and code', () => {
+    const err = createError('Something went wrong', 404, 'NOT_FOUND');
+    expect(err.message).toBe('Something went wrong');
+    expect(err.statusCode).toBe(404);
+    expect(err.code).toBe('NOT_FOUND');
+  });
+});
+
+describe('signToken', () => {
+  it('returns a token and expiry date', () => {
+    const { token, expiresAt } = signToken('test-user-id');
+    expect(typeof token).toBe('string');
+    expect(expiresAt).toBeInstanceOf(Date);
+    expect(expiresAt.getTime()).toBeGreaterThan(Date.now());
+  });
+
+  it('encodes userId in the token', () => {
+    const { token } = signToken('my-user-id');
+    const decoded = jwt.decode(token) as { userId: string };
+    expect(decoded.userId).toBe('my-user-id');
+  });
+});

src/test/validators.test.ts

@@ -0,0 +1,158 @@
+import { signupSchema, signinSchema, addPantryItemSchema, updatePantryItemSchema, addShoppingListItemSchema, updateShoppingListItemSchema, addRecipesToListSchema, recipeQuerySchema, syncQuerySchema } from '../../utils/validators';
+
+describe('Validators', () => {
+  describe('signupSchema', () => {
+    it('accepts valid signup data', () => {
+      const result = signupSchema.safeParse({ email: 'user@example.com', password: 'password123', name: 'Jane' });
+      expect(result.success).toBe(true);
+    });
+
+    it('rejects invalid email', () => {
+      const result = signupSchema.safeParse({ email: 'not-an-email', password: 'password123', name: 'Jane' });
+      expect(result.success).toBe(false);
+    });
+
+    it('rejects short password', () => {
+      const result = signupSchema.safeParse({ email: 'user@example.com', password: 'short', name: 'Jane' });
+      expect(result.success).toBe(false);
+    });
+
+    it('rejects non-alphanumeric password', () => {
+      const result = signupSchema.safeParse({ email: 'user@example.com', password: 'pass!word', name: 'Jane' });
+      expect(result.success).toBe(false);
+    });
+
+    it('rejects empty name', () => {
+      const result = signupSchema.safeParse({ email: 'user@example.com', password: 'password123', name: '' });
+      expect(result.success).toBe(false);
+    });
+  });
+
+  describe('addPantryItemSchema', () => {
+    it('accepts valid pantry item', () => {
+      const result = addPantryItemSchema.safeParse({ item_name: 'Flour', quantity: 5 });
+      expect(result.success).toBe(true);
+    });
+
+    it('rejects zero quantity', () => {
+      const result = addPantryItemSchema.safeParse({ item_name: 'Flour', quantity: 0 });
+      expect(result.success).toBe(false);
+    });
+
+    it('rejects negative quantity', () => {
+      const result = addPantryItemSchema.safeParse({ item_name: 'Flour', quantity: -1 });
+      expect(result.success).toBe(false);
+    });
+
+    it('rejects fractional quantity', () => {
+      const result = addPantryItemSchema.safeParse({ item_name: 'Flour', quantity: 1.5 });
+      expect(result.success).toBe(false);
+    });
+
+    it('rejects empty item name', () => {
+      const result = addPantryItemSchema.safeParse({ item_name: '', quantity: 5 });
+      expect(result.success).toBe(false);
+    });
+  });
+
+  describe('updatePantryItemSchema', () => {
+    it('accepts valid update', () => {
+      const result = updatePantryItemSchema.safeParse({ quantity: 3 });
+      expect(result.success).toBe(true);
+    });
+
+    it('accepts update with last_modified', () => {
+      const result = updatePantryItemSchema.safeParse({ quantity: 3, last_modified: '2024-01-15T10:30:00.000Z' });
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe('addShoppingListItemSchema', () => {
+    it('accepts valid item', () => {
+      const result = addShoppingListItemSchema.safeParse({ item_name: 'Milk', quantity: 2, unit: 'cups' });
+      expect(result.success).toBe(true);
+    });
+
+    it('rejects invalid unit', () => {
+      const result = addShoppingListItemSchema.safeParse({ item_name: 'Milk', quantity: 2, unit: 'gallons' });
+      expect(result.success).toBe(false);
+    });
+
+    it('accepts fractional quantity', () => {
+      const result = addShoppingListItemSchema.safeParse({ item_name: 'Flour', quantity: 2.5, unit: 'cups' });
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe('updateShoppingListItemSchema', () => {
+    it('accepts partial update', () => {
+      const result = updateShoppingListItemSchema.safeParse({ checked_off: true });
+      expect(result.success).toBe(true);
+    });
+
+    it('rejects empty object', () => {
+      const result = updateShoppingListItemSchema.safeParse({});
+      expect(result.success).toBe(false);
+    });
+  });
+
+  describe('addRecipesToListSchema', () => {
+    it('accepts valid recipe ids', () => {
+      const result = addRecipesToListSchema.safeParse({
+        recipe_ids: ['123e4567-e89b-12d3-a456-426614174000'],
+        scale_factor: 2,
+      });
+      expect(result.success).toBe(true);
+    });
+
+    it('rejects empty recipe_ids', () => {
+      const result = addRecipesToListSchema.safeParse({ recipe_ids: [] });
+      expect(result.success).toBe(false);
+    });
+
+    it('rejects scale_factor > 3', () => {
+      const result = addRecipesToListSchema.safeParse({
+        recipe_ids: ['123e4567-e89b-12d3-a456-426614174000'],
+        scale_factor: 4,
+      });
+      expect(result.success).toBe(false);
+    });
+
+    it('defaults scale_factor to 1', () => {
+      const result = addRecipesToListSchema.safeParse({
+        recipe_ids: ['123e4567-e89b-12d3-a456-426614174000'],
+      });
+      expect(result.success).toBe(true);
+      if (result.success) expect(result.data.scale_factor).toBe(1);
+    });
+  });
+
+  describe('recipeQuerySchema', () => {
+    it('defaults to all filter, page 1, limit 20', () => {
+      const result = recipeQuerySchema.safeParse({});
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.filter).toBe('all');
+        expect(result.data.page).toBe(1);
+        expect(result.data.limit).toBe(20);
+      }
+    });
+
+    it('rejects limit > 50', () => {
+      const result = recipeQuerySchema.safeParse({ limit: '51' });
+      expect(result.success).toBe(false);
+    });
+  });
+
+  describe('syncQuerySchema', () => {
+    it('accepts valid ISO timestamp', () => {
+      const result = syncQuerySchema.safeParse({ since: '2024-01-15T10:30:00.000Z' });
+      expect(result.success).toBe(true);
+    });
+
+    it('rejects invalid timestamp', () => {
+      const result = syncQuerySchema.safeParse({ since: 'not-a-date' });
+      expect(result.success).toBe(false);
+    });
+  });
+});

src/utils/jwt.ts

@@ -0,0 +1,17 @@
+import jwt from 'jsonwebtoken';
+import { config } from '../config/env';
+
+export interface TokenPayload {
+  userId: string;
+}
+
+export function signToken(userId: string): { token: string; expiresAt: Date } {
+  const expiresIn = config.jwtExpiresIn;
+  const token = jwt.sign({ userId }, config.jwtSecret, { expiresIn } as jwt.SignOptions);
+
+  // Calculate expiry date
+  const decoded = jwt.decode(token) as { exp: number };
+  const expiresAt = new Date(decoded.exp * 1000);
+
+  return { token, expiresAt };
+}

src/utils/logger.ts

@@ -0,0 +1,15 @@
+import pino from 'pino';
+import pinoHttp from 'pino-http';
+import { config } from '../config/env';
+
+export const logger = pino({
+  level: config.isTest ? 'silent' : 'info',
+  transport: config.isDev
+    ? { target: 'pino-pretty', options: { colorize: true } }
+    : undefined,
+});
+
+export const httpLogger = pinoHttp({
+  logger,
+  autoLogging: !config.isTest,
+});

src/utils/validators.ts

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+import { ALLOWED_UNITS } from '../config/constants';
+
+export const signupSchema = z.object({
+  email: z.string().email('Invalid email format.'),
+  password: z
+    .string()
+    .min(8, 'Password must be at least 8 characters.')
+    .regex(/^[a-zA-Z0-9]+$/, 'Password must be alphanumeric.'),
+  name: z.string().min(1, 'Name is required.').max(255),
+});
+
+export const signinSchema = z.object({
+  email: z.string().email('Invalid email format.'),
+  password: z.string().min(1, 'Password is required.'),
+});
+
+export const googleAuthSchema = z.object({
+  id_token: z.string().min(1, 'id_token is required.'),
+});
+
+export const passwordResetRequestSchema = z.object({
+  email: z.string().email('Invalid email format.'),
+});
+
+export const passwordResetConfirmSchema = z.object({
+  token: z.string().min(1, 'Token is required.'),
+  new_password: z
+    .string()
+    .min(8, 'Password must be at least 8 characters.')
+    .regex(/^[a-zA-Z0-9]+$/, 'Password must be alphanumeric.'),
+});
+
+export const addPantryItemSchema = z.object({
+  item_name: z.string().min(1, 'Item name is required.').max(255),
+  quantity: z
+    .number()
+    .int('Quantity must be a whole number.')
+    .positive('Quantity must be positive.'),
+});
+
+export const updatePantryItemSchema = z.object({
+  quantity: z
+    .number()
+    .int('Quantity must be a whole number.')
+    .positive('Quantity must be positive.'),
+  last_modified: z.string().datetime().optional(),
+});
+
+export const createShoppingListSchema = z.object({
+  list_name: z.string().min(1, 'List name is required.').max(255),
+});
+
+export const addShoppingListItemSchema = z.object({
+  item_name: z.string().min(1, 'Item name is required.').max(255),
+  quantity: z.number().positive('Quantity must be positive.'),
+  unit: z.enum(ALLOWED_UNITS as [string, ...string[]], {
+    errorMap: () => ({ message: `Unit must be one of: ${ALLOWED_UNITS.join(', ')}` }),
+  }),
+});
+
+export const updateShoppingListItemSchema = z
+  .object({
+    quantity: z.number().positive('Quantity must be positive.').optional(),
+    unit: z
+      .enum(ALLOWED_UNITS as [string, ...string[]], {
+        errorMap: () => ({ message: `Unit must be one of: ${ALLOWED_UNITS.join(', ')}` }),
+      })
+      .optional(),
+    checked_off: z.boolean().optional(),
+  })
+  .refine(
+    (data) => Object.keys(data).length > 0,
+    { message: 'At least one field must be provided.' }
+  );
+
+export const addRecipesToListSchema = z.object({
+  recipe_ids: z
+    .array(z.string().uuid('Each recipe_id must be a valid UUID.'))
+    .min(1, 'At least one recipe_id is required.'),
+  scale_factor: z.number().int().min(1).max(3).optional().default(1),
+});
+
+export const recipeQuerySchema = z.object({
+  filter: z.enum(['all', 'can_make', 'can_partially_make']).optional().default('all'),
+  page: z.coerce.number().int().positive().optional().default(1),
+  limit: z.coerce.number().int().positive().max(50).optional().default(20),
+  search: z.string().optional(),
+});
+
+export const recipeDetailQuerySchema = z.object({
+  scale: z.coerce.number().int().min(1).max(3).optional().default(1),
+});
+
+export const syncQuerySchema = z.object({
+  since: z.string().datetime('since must be a valid ISO 8601 timestamp.'),
+});

tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}