From 7aef40ca1463dd9167f4ff5b3c36793ee3f050a2 Mon Sep 17 00:00:00 2001 From: ulfrxdev Date: Fri, 24 Apr 2026 13:14:30 +0200 Subject: [PATCH] docs: add CLAUDE.md with project guidance --- CLAUDE.md | 117 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..2633768 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,117 @@ +# CLAUDE.md + +Guidance for Claude Code when working in this repository. + +## Project + +**Recipe** (working title) — a household meal planning + pantry + shopping list app built with Kotlin Multiplatform (iOS-primary) and a self-hosted Ktor server. Offline-first with last-write-wins sync; household sharing (me + partner); auth via self-hosted Authentik (OIDC). + +**Core value:** "My week is planned." I pick recipes, the calendar fills up, and I know what we're eating. + +## Planning workflow — always start here + +This project uses GSD (Get Shit Done). All product scope, tech decisions, requirements, and phase structure live in `.planning/`. **Read these files before doing any implementation work.** + +| File | What it is | When to read | +|------|-----------|--------------| +| `.planning/PROJECT.md` | Product scope, locked tech decisions, constraints, out-of-scope | Every session — source of truth | +| `.planning/REQUIREMENTS.md` | 72 v1 requirements with REQ-IDs grouped by category, plus v2 / out-of-scope | When touching any feature area | +| `.planning/ROADMAP.md` | 11 phases with goals, mapped requirements, success criteria | To know which phase we're in | +| `.planning/STATE.md` | Current phase + high-level pointer | Fast orientation | +| `.planning/config.json` | Workflow settings (YOLO mode, fine granularity, quality models) | Rarely — set once | +| `.planning/research/SUMMARY.md` | Executive synthesis of architecture + pitfalls research | When planning a phase | +| `.planning/research/ARCHITECTURE.md` | Component structure, data flow, build-order reasoning | When structuring code | +| `.planning/research/PITFALLS.md` | 14 critical pitfalls specific to this stack | Before touching auth, sync, or iOS specifics | + +## Tech stack (locked — see PROJECT.md § Key Decisions for full rationale) + +**Client (`composeApp/`):** +- Kotlin Multiplatform + Compose Multiplatform (iOS-primary; Android, Desktop, Wasm secondary) +- Navigation: `org.jetbrains.androidx.navigation:navigation-compose` (JetBrains-official CMP port of Jetpack Navigation) +- State: ViewModel + StateFlow, method-per-action; `org.jetbrains.androidx.lifecycle:lifecycle-viewmodel-compose` +- DI: Koin (`koin-core`, `koin-compose`, `koin-compose-viewmodel`) +- Local DB: SQLDelight 2.x (raw `.sq` files, generated type-safe Kotlin) +- HTTP: Ktor Client +- Serialization: kotlinx.serialization +- Date/time: kotlinx.datetime +- Logging: Kermit (Touchlab) +- Images: Coil 3 (`io.coil-kt.coil3:coil-compose`) +- Settings/KV: `com.russhwolf:multiplatform-settings` +- Glass/blur: Haze (`dev.chrisbanes.haze:haze`) +- Mobile OIDC: AppAuth on Android; ASWebAuthenticationSession wrapper on iOS (KMP interface) + +**Server (`server/`):** +- Ktor Server 3.x on the user's homelab (alongside Authentik) +- Postgres +- Exposed (DSL only — never the DAO / active-record API) +- Flyway for migrations +- Auth: `io.ktor:ktor-server-auth-jwt` validating Authentik tokens via JWKS + +**Shared (`shared/commonMain`):** +- Domain models + API DTOs only +- No UI, no HTTP, no DB code — keep dependency graph minimal + +**Sync:** Last-write-wins with server-assigned `updated_at`; HTTP polling (20–30s foreground) + pull-to-refresh + debounced push after writes. `POST /api/v1/sync/push`, `GET /api/v1/sync/pull?since=...`. + +## Module structure + +``` +recipe/ +├── composeApp/ # KMP: commonMain + androidMain + iosMain + jvmMain (desktop) +├── iosApp/ # iOS bootstrap (Swift/SwiftUI thin shell) +├── server/ # Ktor + Exposed + Postgres + Flyway +├── shared/ # commonMain: domain + DTOs, no UI/HTTP/DB +├── build-logic/ # Convention plugins (Kotlin/Compose/test config) +├── gradle/libs.versions.toml # Single source of truth for versions +└── .planning/ # GSD planning artifacts (see above) +``` + +**Package layout inside `composeApp/commonMain`:** +``` +dev.ulfrx.recipe/ +├── app/ # App entry, Koin init, theme +├── navigation/ # NavHost, routes, nav graph (nested NavHosts per tab) +├── ui/ +│ ├── theme/ # Colors, typography, Haze glass styles +│ ├── components/ # Shared composables +│ └── screens/{recipes,planner,pantry,shopping}/ # Each with screen + ViewModel +├── data/{local,remote,repository}/ +└── domain/ # Client-only logic; shared/ handles cross-cutting +``` + +**Rule:** No feature modules in v1. Flat `composeApp/commonMain` with the package layout above. + +## Non-negotiable conventions + +1. **Sync timestamps come from the server, never the device.** `updated_at` is assigned server-side; pulling uses lexicographic `(updated_at, id)` cursor. +2. **Row identity is always UUIDs, never composite natural keys.** `(date, slot)` is not a primary key. See ARCHITECTURE.md § Anti-Patterns. +3. **Household scope is enforced in 3 layers:** client query filter + server `PrincipalResolver` deriving `householdId` from JWT `sub` + DB `household_id` column. Never accept `household_id` from request body. +4. **All sync I/O goes through the `SyncEngine` Koin singleton.** Features write to SQLDelight + outbox, never to HTTP directly. See ARCHITECTURE.md § Pattern 2. +5. **Exposed DSL only, never DAO.** Active-record pattern has footguns with JSONB and coroutines. +6. **`newSuspendedTransaction` for every coroutine-touching handler.** Plain `transaction {}` inside a `suspend` block exhausts the connection pool. +7. **iOS binary flags on day 1:** `kotlin.native.binary.objcDisposeOnMain=false`, `kotlin.native.binary.gc=cms`. +8. **`shared/commonMain` stays light.** No Ktor, Compose, or SQLDelight imports. +9. **Strings externalized from day 1** — Polish-only content, but resources are multi-locale-ready. +10. **Haze blur on chrome only** (tab bar, nav bar), never over fast-scrolling content. + +## Current phase + +See `.planning/STATE.md`. The roadmap has 11 phases; you must work within the currently active one. Don't jump ahead. + +**Build order (load-bearing — do not reorder):** +Phase 1 Infra → Phase 2 Auth → Phase 3 Households → Phase 4 SyncEngine skeleton → Phase 5 Recipe catalog → Phase 6 Planner core → Phase 7 Planner customization/nutrition → Phase 8 Pantry → Phase 9 Shopping → Phase 10 UI chrome (Haze) → Phase 11 Localization + deployment. + +## GSD commands you'll use + +- `/gsd-progress` — show current state and suggest next action +- `/gsd-discuss-phase N` — socratic phase clarification before planning +- `/gsd-plan-phase N` — produce detailed PLAN.md for phase N +- `/gsd-execute-phase N` — execute the plans in phase N +- `/gsd-next` — automatically advance to the next logical step + +## Functional reference + +The legacy PWA mockup at `~/dev/repo/recipe-mockup/` is the **functional** reference (logic, data shapes, user flows). It is **not** a visual reference — UI is being rebuilt around a Liquid-Glass-inspired language. Mine it for planner customization logic (substitutions, amount overrides, product selections), shortfall computation, and shopping aggregation. Do not port its vanilla-JS data or Tailwind styling. + +--- +*Initialized: 2026-04-24. Update when `.planning/PROJECT.md` § Key Decisions gains load-bearing new entries.*