docs: add CLAUDE.md with project guidance
This commit is contained in:
117
CLAUDE.md
Normal file
117
CLAUDE.md
Normal file
@@ -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.*
|
||||
Reference in New Issue
Block a user