| 1 | # CLAUDE.md |
| 2 | |
| 3 | This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | |
| 5 | ## Project |
| 6 | |
| 7 | Klepon is a SwiftUI guide to Indonesian dishes, ingredients, and food traditions. It supports iOS, macOS, tvOS, visionOS, and watchOS and uses the [Ed Swift SDK](https://github.com/ondeinference/ed-swift) (the Onde-powered on-device agent) for private on-device AI answers. |
| 8 | |
| 9 | ## Project structure |
| 10 | |
| 11 | The `.xcodeproj` is generated by [XcodeGen](https://github.com/yonaskolb/XcodeGen) from `project.yml`. Modify `project.yml` to change targets, sources, dependencies, or build settings, then regenerate: |
| 12 | |
| 13 | ```sh |
| 14 | xcodegen generate |
| 15 | ``` |
| 16 | |
| 17 | Source layout: |
| 18 | - `Klepon/` — shared source used by iOS, macOS, tvOS, and visionOS (conditional compilation via `#if os(...)`) |
| 19 | - `KleponTV/App/` — tvOS-only entry point; replaces `KleponApp.swift` and `AppRootView.swift` with a UIKit `AppDelegate` + `SceneDelegate` + `KleponTabBarController` |
| 20 | - `KleponWatch/` — watchOS app; shares only `GuideEntry.swift`, `KleponColor.swift`, and the bundled content JSON |
| 21 | - `KleponTVTopShelfExtension/` — tvOS Top Shelf extension |
| 22 | - `KleponMac/`, `KleponVision/` — target-specific Info.plist and entitlements |
| 23 | - `Klepon/Resources/Content/` — bundled JSON content (`guide_entries.json`, `collections.json`) |
| 24 | - `Configs/` — xcconfig files for build settings and secrets |
| 25 | |
| 26 | ## Build commands |
| 27 | |
| 28 | Build each scheme without signing (for CI or local verification): |
| 29 | |
| 30 | ```sh |
| 31 | # iOS Simulator |
| 32 | xcodebuild -project Klepon.xcodeproj -scheme Klepon -destination 'generic/platform=iOS Simulator' CODE_SIGNING_ALLOWED=NO build |
| 33 | |
| 34 | # macOS |
| 35 | xcodebuild -project Klepon.xcodeproj -scheme 'Klepon Mac' -destination 'platform=macOS' CODE_SIGNING_ALLOWED=NO build |
| 36 | |
| 37 | # tvOS Simulator |
| 38 | xcodebuild -project Klepon.xcodeproj -scheme 'Klepon TV' -destination 'generic/platform=tvOS Simulator' CODE_SIGNING_ALLOWED=NO build |
| 39 | |
| 40 | # visionOS Simulator |
| 41 | xcodebuild -project Klepon.xcodeproj -scheme 'Klepon Vision' -destination 'generic/platform=visionOS Simulator' CODE_SIGNING_ALLOWED=NO build |
| 42 | |
| 43 | # watchOS Simulator |
| 44 | xcodebuild -project Klepon.xcodeproj -scheme 'Klepon Watch' -destination 'generic/platform=watchOS Simulator' CODE_SIGNING_ALLOWED=NO build |
| 45 | ``` |
| 46 | |
| 47 | ## Tests |
| 48 | |
| 49 | The `KleponSnapshotTests` target contains both logic tests (Swift Testing `@Test`) and snapshot tests (PointFree SnapshotTesting). Run all tests via the `Klepon` scheme: |
| 50 | |
| 51 | ```sh |
| 52 | xcodebuild test \ |
| 53 | -project Klepon.xcodeproj \ |
| 54 | -scheme Klepon \ |
| 55 | -destination 'platform=iOS Simulator,OS=26.2,name=iPhone 17' \ |
| 56 | -only-testing:KleponSnapshotTests \ |
| 57 | CODE_SIGNING_ALLOWED=NO |
| 58 | ``` |
| 59 | |
| 60 | Validate bundled JSON content (runs on Linux in CI): |
| 61 | |
| 62 | ```sh |
| 63 | python3 Scripts/validate_content.py |
| 64 | ``` |
| 65 | |
| 66 | ## Architecture |
| 67 | |
| 68 | ### Dependency graph |
| 69 | |
| 70 | `AppState` (injected as `@EnvironmentObject`) owns all services and stores: |
| 71 | |
| 72 | ``` |
| 73 | AppState |
| 74 | ├── ContentRepository — loads guide_entries.json + collections.json at startup |
| 75 | ├── SearchService — token-based search over ContentRepository |
| 76 | ├── FavoritesStore — UserDefaults-backed Set<String> of entry IDs |
| 77 | ├── RecentSearchStore — persisted recent queries |
| 78 | ├── RecentlyViewedStore — persisted recently viewed entry IDs |
| 79 | ├── OndeGuideEngine — wraps the Onde Rust/UniFFI on-device inference runtime |
| 80 | ├── GuideAnswerService — composes ContentRepository + GuideAnswering to answer questions |
| 81 | └── AccountStore — Onde Cloud session management |
| 82 | ``` |
| 83 | |
| 84 | ### On-device AI |
| 85 | |
| 86 | `OndeGuideEngine` conforms to `GuideAnswering` and lazily initializes `EdAgent` (from the Ed Swift package) only when inference is actually requested. `GuideAnswerService` depends on the `GuideAnswering` protocol, not the concrete engine, so tests can inject `StubGuideEngine` without touching the Rust/UniFFI runtime. |
| 87 | |
| 88 | tvOS inference is gated on hardware: Apple TV 4K 3rd generation (AppleTV14,1, A15) or newer — checked via `sysctlbyname("hw.machine", ...)` in `OndeGuideEngine.swift`. |
| 89 | |
| 90 | ### Platform adaptations |
| 91 | |
| 92 | - **iOS compact (iPhone)** and **tvOS**: `TabView`-based navigation |
| 93 | - **iOS regular (iPad)**: `NavigationSplitView` with a sidebar |
| 94 | - **macOS / visionOS**: same SwiftUI views as iOS, with minimum window size constraints |
| 95 | - **tvOS root**: entirely UIKit — `AppDelegate` → `SceneDelegate` → `KleponTabBarController` hosting SwiftUI views via `UIHostingController` |
| 96 | |
| 97 | ### Design system |
| 98 | |
| 99 | `KleponColor` and `KleponTypography` define all colors and type styles. Use these rather than system defaults to keep visual consistency across platforms. |
| 100 | |
| 101 | ## Credentials setup |
| 102 | |
| 103 | Copy `Configs/Secrets.local.xcconfig.example` to `Configs/Secrets.local.xcconfig` (git-ignored) and fill in per-SDK Onde Cloud credentials (`ONDE_APP_ID`, `ONDE_APP_SECRET`). Without this file the private guide feature shows a configuration error at runtime but the rest of the app works. |
| 104 | |
| 105 | For testing on a physical device over LAN, copy `Configs/Debug.local.xcconfig.example` to `Configs/Debug.local.xcconfig` and set `ONDE_WEB_DEV_HOST` to your Mac's LAN IP (`ipconfig getifaddr en0`). |