# Architecture Research

**Domain:** Offline-first meal-planning app (KMP + Ktor, household-shared)
**Researched:** 2026-04-23
**Confidence:** HIGH (locked stack; standard patterns within it)

## System Overview

```
┌──────────────────────────────────────────────────────────────────┐
│  composeApp/ (Android · iOS · Desktop · Wasm)                    │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  UI: Compose screens + NavHost (Jetpack Nav CMP)          │   │
│  │  ViewModel (StateFlow) ──► Repository (reactive Flow)     │   │
│  │         │                         │                        │   │
│  │         ▼                         ▼                        │   │
│  │  SyncEngine (singleton) ◄──► SQLDelight (local) + Outbox  │   │
│  │         │                                                  │   │
│  │         │   AuthSession (AppAuth / ASWebAuth)              │   │
│  │         ▼                                                  │   │
│  │  Ktor Client (JWT bearer) ─────────────────┐               │   │
│  └────────────────────────────────────────────┼───────────────┘   │
└──────────────────────────────────────────────┼───────────────────┘
                                               │  HTTPS
              ┌────────────────────────────────┼───────────┐
              │  Authentik (OIDC IdP, homelab) │  JWKS     │
              └────────────────────────────────┴───────────┘
                                               │
┌──────────────────────────────────────────────▼───────────────────┐
│  server/ (Ktor 3.x, same homelab)                                │
│  Auth (ktor-server-auth-jwt) ──► Routes /api/v1/*                │
│             │                          │                          │
│             ▼                          ▼                          │
│  PrincipalResolver ──► Services ──► Exposed DSL ──► Postgres     │
│                                                    (Flyway)       │
└──────────────────────────────────────────────────────────────────┘

shared/commonMain: domain models + API DTOs (client + server both depend)
```

## Component Responsibilities

| Component | Responsibility | Typical Implementation |
|-----------|----------------|------------------------|
| Screen (`@Composable`) | Render state, forward intents. No I/O. | `PlannerScreen(state, onAddMeal)`; consumes `collectAsStateWithLifecycle()` |
| ViewModel | Expose `StateFlow`; coordinate repo calls; zero Compose imports | Extends `ViewModel`, scoped via `koinViewModel()`, method-per-action |
| Repository | Single source of truth for one aggregate; hide local/remote split | Exposes `Flow<Domain>` from SQLDelight; write path goes through local DB + outbox |
| SyncEngine | Own outbox drain, pull loop, backoff, auth failure handling | App-scoped Koin singleton; one `CoroutineScope(SupervisorJob)`; started after auth |
| DataSource (local) | Thin SQLDelight wrapper, mapping rows ↔ domain | Per-table `Queries` injected; suspend + `asFlow().mapToList()` |
| DataSource (remote) | Typed Ktor calls for `/sync/push`, `/sync/pull`, catalog endpoints | `HttpClient` with `Auth { bearer { ... } }` + `ContentNegotiation(Json)` |
| AuthSession | Own tokens, refresh, sign-in/out; expose `StateFlow<AuthState>` | Platform-specific actual class (AppAuth / ASWebAuth) behind `expect` |
| Koin Module | Wire graph per layer (`appModule`, `dataModule`, `syncModule`, `authModule`) | Declared in `commonMain`; `startKoin` in `App()` + `MainViewController` |
| Ktor route | HTTP surface; validate DTO; call service; never touch DB directly | `Route.planRoutes()` under `authenticate("auth-jwt") { route("/api/v1") { ... } }` |
| Exposed table | Schema definition + column types; DSL queries via `transaction {}` | `object PlanEntries : Table("plan_entries")` — no DAO |
| Outbox | Durable queue of unsynced local writes keyed by aggregate+id | `sync_outbox` table in SQLDelight; `(op, table, pk, payload_json, attempts)` |

## Recommended Project Structure

```
composeApp/src/commonMain/kotlin/app/recipe/
├── app/                           # App() composable, root nav, Koin bootstrap
├── navigation/                    # @Serializable route classes + NavGraphBuilder extensions
├── ui/
│   ├── theme/                     # Color, typography, Haze style tokens
│   ├── components/                # Reusable (GlassCard, MealSlotChip, ...)
│   └── screens/
│       ├── recipes/               # RecipeListScreen, RecipeDetailScreen, *ViewModel
│       ├── planner/               # PlannerScreen, DayColumn, *ViewModel
│       ├── pantry/
│       └── shopping/
├── data/
│   ├── local/                     # SQLDelight driver factory (expect/actual), Queries wrappers
│   ├── remote/                    # HttpClient factory, DTOs mirroring shared/, auth interceptor
│   ├── sync/                      # SyncEngine, Outbox, pull scheduler, conflict policy
│   └── repository/                # PlanRepository, PantryRepository, CatalogRepository, ...
├── domain/                        # Value types, enums (MealSlot), pure computations (shortfall, aggregation)
├── auth/                          # AuthSession interface, token store, OIDC config
└── di/                            # appModule, dataModule, syncModule, authModule

server/src/main/kotlin/app/recipe/server/
├── Application.kt                 # embeddedServer, install plugins, call moduleMain()
├── plugins/                       # Auth, ContentNegotiation, CallLogging, StatusPages, CORS
├── auth/                          # JWKS config, PrincipalResolver (sub → user → household)
├── routes/
│   ├── sync/                      # push.kt, pull.kt
│   ├── catalog/                   # recipes, ingredients, products (read-mostly)
│   ├── households/                # memberships, invites
│   └── health/
├── services/                      # PlanService, SyncService — orchestrate transactions
├── db/
│   ├── tables/                    # Exposed Table objects (no DAO)
│   ├── Mappers.kt                 # ResultRow → shared DTO
│   └── Database.kt                # HikariCP + Flyway.migrate()
└── util/                          # Clock (injectable), IdGen, Json

server/src/main/resources/db/migration/     # V1__init.sql, V2__plan_entries.sql, ...
shared/src/commonMain/kotlin/app/recipe/shared/   # Domain + DTOs (@Serializable) — no I/O deps
```

Rationale: groups by UI concern then data layer, matching the locked decision in PROJECT.md. `data/sync/` is a first-class folder because sync is the spine of the app. `domain/` holds pure logic so it can be unit-tested without Android/iOS runtime. Server mirrors the client's layered split (routes → services → db) so reasoning transfers.

## Architectural Patterns

### Pattern 1: Repository → reactive Flow → StateFlow in ViewModel

Repositories expose `Flow<Domain>` built from SQLDelight's `asFlow().mapToList()`. The ViewModel lifts that into a cold-hot `StateFlow` using `stateIn` with `WhileSubscribed(5_000)`. Writes go through the repo, which writes to SQLDelight; the reactive query re-emits automatically. **Never** pre-fetch state with a suspend call in `init {}` — that races with collection.

```kotlin
class PlannerViewModel(private val repo: PlanRepository) : ViewModel() {
  val state: StateFlow<PlannerState> = repo.observeWeek(currentWeek)
    .map(PlannerState::fromEntries)
    .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), PlannerState.Loading)

  fun onAddMeal(day: LocalDate, slot: MealSlot, recipeId: Uuid) =
    viewModelScope.launch { repo.add(day, slot, recipeId) }
}
```

### Pattern 2: Sync engine as a Koin singleton owning outbox + poll cycles

One long-lived `SyncEngine` bound in `syncModule` with a `SupervisorJob`-backed scope. It exposes `pushNow()`, `pullNow()`, `status: StateFlow<SyncStatus>`. Two loops: a push loop that drains `sync_outbox` with exponential backoff on 5xx/network errors, and a pull loop that calls `GET /sync/pull?since={lastCursor}` every 20–30s while foregrounded. Repositories never talk to HTTP directly for household data — they enqueue outbox rows and trust the engine.

```kotlin
class SyncEngine(private val api: SyncApi, private val local: LocalDb, private val clock: Clock) {
  private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default)
  fun start() { scope.launch { pushLoop() }; scope.launch { pullLoop() } }
  suspend fun nudge() = pushSignal.emit(Unit)
}
```

Trade-off: single point of failure if the engine deadlocks, so all its work must be cancellable and idempotent (server-side push is keyed by `client_op_id`).

### Pattern 3: Household-scope enforcement at three layers

Defence in depth: (a) **Client query filter** — every SQLDelight query for household-scoped tables includes `WHERE household_id = :hh`, sourced from `AuthSession.activeHouseholdId`; (b) **Server principal resolver** — a `PrincipalResolver` turns the JWT `sub` claim into `(userId, householdId)` via a cached lookup against `memberships`; routes receive an `AuthPrincipal` already carrying `householdId`; (c) **DB row ownership** — every household-scoped table has `household_id uuid NOT NULL` with an index, and every `UPDATE`/`DELETE` includes `AND household_id = ?`.

```kotlin
fun Route.planRoutes(svc: PlanService) = authenticate("auth-jwt") {
  post("/api/v1/sync/push") {
    val p = call.principal<AuthPrincipal>()!!         // householdId baked in
    val batch = call.receive<PushBatch>()
    call.respond(svc.applyBatch(p.householdId, batch))
  }
}
```

Never trust a `householdId` field inside a client payload — overwrite with the principal's.

### Pattern 4: Catalog (read-mostly) vs Household (read-write, synced) split

Two cache + sync policies in one app. **Catalog** (recipes, ingredients, products) is pre-seeded server-side, pulled via versioned ETag (`GET /api/v1/catalog?etag=...`), cached in SQLDelight with a simple "replace all or diff by updated_at" refresh on app start + manual refresh. No outbox. **Household** (plan entries, pantry, shopping items) is LWW-synced with server-assigned `updated_at`, uses the outbox, and is reactively observed. Keep these in separate repositories and separate Koin modules so their refresh semantics don't leak into each other.

## Data Flow — Hero Write Path (Add Meal to Plan)

```
User taps "add meal"
    │
    ▼
PlannerScreen invokes onAddMeal(day, slot, recipeId)
    │
    ▼
PlannerViewModel.onAddMeal → viewModelScope.launch { repo.add(...) }
    │
    ▼
PlanRepository.add():
  ├─ SQLDelight transaction:
  │     INSERT plan_entry (id=localUuid, household_id, day, slot, recipe_id,
  │                        updated_at=NULL /* server will stamp */, pending=1)
  │     INSERT sync_outbox (op='upsert', table='plan_entry', pk=id,
  │                         payload_json, client_op_id, attempts=0)
  └─ Flow<PlanEntries> re-emits → PlannerViewModel.state recomputes → UI updates
    │                              (optimistic; pending=1 may render a subtle marker)
    ▼
SyncEngine.nudge() — push loop wakes
    │
    ▼
Ktor Client POST /api/v1/sync/push  (Authorization: Bearer <jwt>)
    │
    ▼
Ktor Server: install(Authentication) { jwt("auth-jwt") { verifier(jwkProvider) } }
    │  JWT validated against Authentik JWKS (cached, rotating)
    ▼
PrincipalResolver: sub → userId → householdId (cached)
    │
    ▼
sync/push.kt → SyncService.applyBatch(householdId, batch)
    │
    ▼
Exposed transaction {
    PlanEntries.upsert { it[id]=...; it[householdId]=...; it[updatedAt]=Clock.now() }
    // server clock is authoritative
}
    │
    ▼
Response { applied: [{ id, client_op_id, updated_at: <server ts> }] }
    │
    ▼
Client: local tx {
  UPDATE plan_entry SET updated_at = <server ts>, pending = 0 WHERE id = ?
  DELETE FROM sync_outbox WHERE client_op_id = ?
}
    │
    ▼
Flow re-emits → pending marker vanishes
    │
    ~~~  (later) partner's device  ~~~
    ▼
Pull loop: GET /api/v1/sync/pull?since=<lastCursor>
    │
    ▼
Server returns rows with updated_at > since, scoped to householdId
    │
    ▼
Client upserts rows in a single SQLDelight tx; advances cursor
    │
    ▼
Partner's PlannerViewModel StateFlow emits new state → their UI updates
```

## Anti-Patterns

### Anti-Pattern 1: Suspend fetch in `init {}` feeding a `MutableStateFlow`

```kotlin
// WRONG
init { viewModelScope.launch { _state.value = repo.getOnce() } }
```

Races with UI collection; loses SQLDelight's reactive updates; forces manual refresh after every write. **Instead:** build the `StateFlow` declaratively from `repo.observeX().stateIn(...)`.

### Anti-Pattern 2: Using Exposed DAO (active record) for new tables

Exposed's DAO API (`IntEntity`, `EntityClass`) looks convenient but leaks lazy-loading through transactions and fights JSONB/composite types. PROJECT.md already forbids it. **Instead:** use the DSL (`Table` objects + `transaction { Table.select { ... } }` + explicit `ResultRow → DTO` mappers). Predictable SQL, no session/transaction surprises.

### Anti-Pattern 3: Sharing SQLDelight transactions across coroutine contexts on iOS

SQLDelight's iOS driver (native-sqlite) uses thread-confined connections. Launching nested `withContext(Dispatchers.IO)` inside a `transaction { }` can throw `IllegalStateException` or silently serialize incorrectly. **Instead:** keep the entire transaction inside one coroutine, use SQLDelight's `transactionWithResult { }`, and do network/CPU work *outside* the tx. On iOS, the driver's own dispatcher handles threading.

### Anti-Pattern 4: Using device clock for `updated_at`

Phones have drifting clocks and timezone shenanigans; a device whose clock is 10 minutes fast will always "win" LWW. **Instead:** server stamps `updated_at` inside the push transaction (`Clock.System.now()` on the server, or `now()` in SQL). The client only stores what the server returns. Local-only edits carry `pending=1` until acknowledged.

### Anti-Pattern 5: Putting UI, HTTP, or DB types in `shared/commonMain`

PROJECT.md scopes `shared/` to domain models + DTOs. Dragging Ktor or SQLDelight into `shared/` pulls platform-specific deps into the server build graph and vice versa. **Instead:** client-only concerns live in `composeApp/`, server-only in `server/`, and `shared/` stays a pure-Kotlin library with `kotlinx.serialization` + `kotlinx.datetime` as its only non-stdlib deps.

## Build Order Implication

The layer that must exist first is **auth + a working Ktor skeleton that echoes an authenticated principal**, because every subsequent layer depends on having a real `householdId` to scope against. After that the unblock order is: (1) **sync engine foundation** — outbox table, empty push/pull endpoints, cursor persistence — so every feature slots into an already-synced path instead of being retrofitted; (2) **catalog read path** — lets the UI render recipes without any write-path complexity, proving HTTP + SQLDelight + Coil end-to-end on a trivial aggregate; (3) **household write path** — the planner as the first real outbox-backed aggregate, which flushes out LWW edge cases; (4) **UI chrome** — Haze-backed glass, navigation polish, theming — last, because decorating a working app is cheap while architecting around decoration is expensive. Skipping step 1 or 2 and jumping to the planner looks faster for a week and costs a month.

## Sources

- `/Users/rwilk/dev/repo/recipe/.planning/PROJECT.md` (authoritative stack + constraints)
- Training knowledge: Compose Multiplatform 1.7+, Jetpack Nav CMP port 2.9.x, SQLDelight 2.x coroutine extensions, Ktor 3.x auth-jwt + JWKS, Exposed DSL transaction semantics, Authentik OIDC discovery
- No web searches needed — patterns are standard within the locked stack

---
*Architecture research for: KMP + Ktor household meal planner*
*Researched: 2026-04-23*
