# 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` 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` | 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` 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 = 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`. 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()!! // householdId baked in val batch = call.receive() 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 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 ) │ ▼ 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: }] } │ ▼ Client: local tx { UPDATE plan_entry SET updated_at = , 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= │ ▼ 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*