Add CLAUDE.md with build commands and architecture guide
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Seto Elkahfi committed
Jun 19, 2026 at 22:07 UTC
597614d1079016c638ff194acbfdc86ec0fe8b69
1 file changed
+105
CLAUDE.md
new
+105
@@ -0,0 +1,105 @@
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 [Onde Swift SDK](https://github.com/ondeinference/onde-swift) 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 `OndeChatEngine` (from the Onde 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`).