openfoodjournal

name

openfoodjournal

description

Living project knowledge for OpenFoodJournal — an iOS 26 food journaling app with AI-powered nutrition scanning. Consult this skill FIRST when starting any work on this project. Contains architecture decisions, data models, service contracts, current state, known issues, and conventions. Update this skill whenever requirements, architecture, or project state changes so it stays accurate across sessions.

OpenFoodJournal — Project Knowledge

This is the single source of truth for any LLM agent working on this project. Read this before writing code. Update it when things change.

Quick Facts

Key	Value
Platform	iOS 26.2+ (iPhone)
UI Framework	SwiftUI + Liquid Glass (no #available gating needed)
Data Layer	SwiftData (@Model) + CloudKit Private Database (iCloud.k3vnc.OpenFoodJournal) + optional push-only Turso mirror
State Pattern	@Observable + @Environment injection (no singletons)
Bundle ID	k3vnc.OpenFoodJournal
Build System	Xcode (xcodebuild), no SPM dependencies
Build Verify Command	xcodebuild -project OpenFoodJournal.xcodeproj -scheme OpenFoodJournal -destination generic/platform=iOS build
Build Notes	No iOS simulators installed. Use generic/platform=iOS for compile-only verification. Physical device (iPhone 18,3) available when connected. Device support symbols at /Volumes/DevDisk/Developer/Xcode/iOS DeviceSupport/.
Release Automation	GitHub xcode-27 cloud CI; testflight builds once and uploads internally; app-store promotes the exact tested build
AI Backend	BYOK direct AI calls: Gemini, OpenRouter, or Azure OpenAI for Assistant; Gemini/OpenRouter for Scan; native, Tavily, or Parallel research
App Entry	MacrosApp in OpenFoodJournalApp.swift

Architecture Overview

MacrosApp (creates ModelContainer w/ CloudKit + @Observable services)
  └─ ContentView (5-tab TabView)
       ├─ Journal tab → DailyLogView (WeeklyCalendarStrip, macro summary, meal sections, RadialMenuButton)
       ├─ Food Bank tab → FoodBankView (searchable, sortable active saved food list, swipe-to-archive/edit, "+" menu: AI Search/Composite/Nutrition Calculator/Search OFF/Manual/Archive)
       ├─ History tab → HistoryView (CalendarGridView with progress rings, MacroChartView, macro cards → NutritionDetailView)
       ├─ Assistant tab → ChatView (streaming AI chat over nutrition data, persistent CloudKit-synced threads)
       └─ Settings tab → SettingsView (goals, health, data export)

Radial FAB: DailyLogView uses RadialMenuButton — a "+" icon at bottom center that fans out Scan / Manual / Containers / Food Bank in an upper semicircle (210°–330°). Supports tap-to-toggle and drag-to-action. Containers are accessed from here instead of a separate tab.

Service injection: All services (NutritionStore, ScanService, ChatService, TursoMirrorService, HealthKitService, UserGoals, MealTimeSettings, OpenFoodFactsService) are created in MacrosApp.init() and passed via .environment(). Views consume them with @Environment(ServiceType.self). SyncService was removed — CloudKit handles sync natively via ModelConfiguration(cloudKitDatabase:); Turso is an optional push-only mirror, not a source of truth.

Sheet management: DailyLogView uses a single DailyLogSheet enum with .sheet(item:) — never multiple booleans.

Data Models

See references/models.md for full property lists.

• DailyLog — @Model, keyed by date normalized to midnight (no @Attribute(.unique) — CloudKit can't enforce uniqueness; app-level dedup in fetchOrCreateLog(for:)). Owns [NutritionEntry]? (optional for CloudKit) via cascade delete. Uses safeEntries computed property for reads.
• NutritionEntry — @Model, stores core macros (cal/protein/carbs/fat) + dynamic micronutrients: [String: MicronutrientValue] + brand/serving/servingCount/servingQuantity/servingUnit/servingMappings + optional selectionSummary for generated calculator builds. Includes HealthKit sync metadata (healthKitSyncStatus, healthKitSyncedAt, healthKitSyncVersion, healthKitLastError, healthKitLastWriteHash) so Apple Health writes are idempotent.
• SavedFood — @Model, reusable food template in Food Bank. Same fields as NutritionEntry minus meal/log context. Includes optional emoji: String? plus optional generated icon image data/mime/update/prompt for the Food Bank icon, kind: SavedFoodKind (.single/.composite/.calculator), compositeIngredients: [CompositeIngredientSnapshot], calculatorIngredients: [CalculatorIngredient], isOnShelf: Bool, lastUsedAt: Date (defaults to createdAt) for "Last Used" sorting, and archivedAt: Date? for manual cosmetic archive state. Composite ingredients are copied snapshots, never live SavedFood references, so editing a composite only affects future logs. Nutrition calculators are also saved-food rows: flat ingredient/portion value snapshots, not SwiftData relationship trees. Foods auto-archive cosmetically when lastUsedAt is more than 14 days old unless isOnShelf is true; manual archive always wins. Archived foods stay in SwiftData, remain searchable, and can be browsed from Food Bank "+" → Archive.
• TrackedContainer — @Model, weight-based container tracking. Snapshots food nutrition at creation time. Start weight → final weight → derived consumption via math.

Services

See references/services.md for full API contracts.

• NutritionStore — SwiftData CRUD and the canonical journal-mutation boundary. log(), saveEntry(), moveEntry(), and entry/log deletion persist SwiftData first, then automatically schedule the matching idempotent HealthKit sync/delete through an injected NutritionEntryHealthSyncing adapter when Apple Health export is enabled. Views, Assistant tools, and future entry-writing surfaces must not call HealthKit separately. entriesNeedingHealthSync() drives launch/foreground reconciliation and Settings backfill so interrupted or older-build writes heal from SwiftData. Also provides fetchLog(), fetchLogs(), repairDailyLogEntryRelationships(), exportCSV(), exportBackup(), and importBackup(). CSV is spreadsheet/analytics only. Restore-grade backup uses versioned JSON DTOs in OpenFoodJournalBackup.swift and imports idempotently by UUID. Local/iCloud remain source of truth; successful saves schedule the optional Turso mirror when enabled.
• ScanService — Accepts 1-4 photos for label and food-photo scans. Resizes each image to max 1200px (UIGraphicsImageRenderer), encodes label JPEGs at 0.50 and food-photo JPEGs at 0.80, then sends each photo to the selected AI provider and returns a reviewable NutritionEntry (not yet inserted). Direct Gemini uses streamed Interactions SSE (generativelanguage.googleapis.com/v1beta/interactions) with generation_config.thinking_summaries = "auto" so step.delta events with delta.type == "thought_summary" update thinkingTrace; delta.type == "text" is accumulated as final nutrition JSON. OpenRouter uses streamed OpenAI-compatible chat completions (openrouter.ai/api/v1/chat/completions) with base64 image content parts, JSON response format, app attribution headers, optional plugins: [{"id":"web"}] for AI Search, and optional provider routing to prefer/require google-vertex. OpenRouter does not currently drive the Gemini thought-summary UI; it shows a neutral provider wait state and logs stream timing. Gemini may emit only one late thought-summary event for a request; do not fake streaming by delaying the final nutrition sheet just to display that late summary. Also supports Food Bank AI Search, nutrition-calculator OCR import via extractCalculatorIngredient(named:from:useProModel:), sequential Food Bank emoji backfill via , and direct Gemini Flash Lite image icon generation via / . Direct Gemini uses for label/lite/emoji work and for Pro food photo scans/search; do not replace these with concrete preview/versioned model slugs unless Google removes the latest endpoints. The icon image endpoint is the concrete Interactions image model. OpenRouter model slugs are runtime-editable in Settings and default to the analogous Google latest aliases. User reviews in , , or before committing. Logs scan/search/OCR/emoji/icon duration via , stores standard scan durations on , emits redacted telemetry to the configured Turso sink, and keeps usage/cost totals in SwiftData. Stores for scan-page/result-sheet redo without recapturing photos.

View Map

See references/views.md for detailed view hierarchy and notable patterns.

Scan Flow (Core Value Prop)

User taps Scan → CameraController (AVCaptureSession) → 1-4 photos
  → Camera view offers 0.5x / 1x / 2x zoom (0.5x uses ultra-wide when available; 1x/2x use wide camera)
  → Prompt overlay: review thumbnails, optionally add another angle or library photos
  → Food photo shows text input, label scan skips prompt
  → ScanService.scan(images, mode) → loads the selected provider API key from KeychainService
  → Resizes/JPEG-encodes each image and builds either Gemini Interactions image blocks or OpenRouter chat-completion image_url content parts
  → Direct Gemini: POST to https://generativelanguage.googleapis.com/v1beta/interactions with x-goog-api-key header
  → OpenRouter: POST to https://openrouter.ai/api/v1/chat/completions with Authorization bearer header, app attribution headers, and optional Google Vertex provider routing
  → Loading overlay shows scan stage; direct Gemini also shows recent thought-summary deltas (`step.delta` / `delta.type == "thought_summary"`)
  → ContinuousClock measures full round-trip duration
  → Direct Gemini label/lite mode: gemini-flash-latest; Pro mode: gemini-pro-latest
  → OpenRouter uses Settings-editable lite/pro/emoji model slugs, defaulting to analogous Google latest aliases
  → Fallback on transient server failures uses the configured fallback model
  → Accumulates response text → JSON → GeminiNutritionResponse
  → GeminiNutritionResponse → NutritionEntry (NOT inserted yet)
  → Entry gets scanDurationMs set from ContinuousClock measurement
  → ScanResultCard (editable, shows duration badge, can redo previous photos) → User taps "Add to Journal"
  → NutritionStore.log(entry, to: date) → SwiftData insert (CloudKit syncs automatically)
  → Auto-creates SavedFood in Food Bank
  → NutritionStore automatically schedules HealthKitService.sync(entry) if enabled (replaces OpenFoodJournal-owned HealthKit samples by sync identifier)

Barcode Scan Flow

User taps "Scan Barcode" card → CameraController (AVCaptureSession) → JPEG
  → promptOverlay: "Look Up" button (no text prompt for barcode mode)
  → Vision VNDetectBarcodesRequest detects barcode from photo
  → OpenFoodFactsService.lookupBarcode(barcodeValue)
  → GET https://world.openfoodfacts.org/api/v2/product/{code}?fields=...
  → OFFProduct (requires calories > 0 and usable nutrition) → ManualEntryView(defaultDate:, prefillProduct:)
  → User reviews/edits pre-filled nutrition data → saves to journal

Open Food Facts Search Flow

User taps "Search Open Food Facts" in Food Bank "+" menu
  → OpenFoodFactsSearchView (searchable, Enter-only via .onSubmit)
  → GET https://search.openfoodfacts.org/search?q={query}&fields=...&page_size=25
  → Converts hits to OFFProduct and filters out zero-calorie/no-usable-nutrition rows
  → OFFProductRow (styled like SavedFoodRowView — macros, calories, serving)
  → Tap row → ManualEntryView(defaultDate:, prefillProduct: product)
  → User reviews/edits pre-filled data → saves to journal

AI Search Flow

User taps "AI Search" in Food Bank "+" menu
  → AIFoodSearchView with a search-style prompt row and arrow submit button
  → ScanService.searchNutrition(query, useProModel) loads API key from KeychainService
  → Direct Gemini builds Interactions request with tools: [{"type": "google_search"}]
  → OpenRouter builds chat-completions request with plugins: [{"id": "web"}]
  → Uses the selected provider's Lite model by default or Pro model when Settings "Use Pro Model for AI" is enabled
  → Parses JSON nutrition response → NutritionEntry (NOT inserted yet)
  → ManualEntryView(defaultDate:, prefill:) opens for editable review
  → User chooses "Add to Journal" or "Add to Journal & Food Bank"

Food Bank Emoji Flow

Settings → Food Bank → Enable Food Icon Generation
  → @AppStorage("foodBank.autoGenerateEmojis") enables the manual icon-generation controls, but does not enqueue background work by itself
  → Optional @AppStorage("foodBank.useGeneratedIconImages") switches the icon target from text emoji to generated images
  → Toggling either setting must not queue the whole Food Bank. Generation starts only from Settings → "Generate Missing ..." or, when icon generation is enabled, a Food Bank row context-menu generate/regenerate action.
  → Emoji mode: ScanService.backfillMissingFoodEmojis() fetches all SavedFood rows with empty emoji
  → Image mode: ScanService.backfillMissingFoodIconImages() fetches all SavedFood rows without generated icon image data
  → Processes foods sequentially. Emoji mode uses the selected provider's emoji model and a JSON-only one-emoji prompt; image mode uses direct Gemini `models/gemini-3.1-flash-lite-image` with the Gemini key.
  → Image prompts are JSON such as {"Brand":"Tyson","item":"Crispy Chicken Fries"} and omit the Brand key entirely when no brand exists.
  → Generated images are normalized before persistence to compact 160 px JPEG thumbnails; do not store raw 1K Gemini image bytes in SwiftData/CloudKit for row icons. Image backfill also optimizes any already-stored larger icon images locally without another API call.
  → Sets SavedFood.emoji or SavedFood.generatedIconImageData only if that target is still missing; automatic backfill skips existing icons and also skips the same prompt/model for one hour after a failure so bad requests do not churn through the whole Food Bank. Context menus can force-regenerate the active icon mode and bypass that recent-failure cache.
  → Food Bank row context menus also expose "Pixel Pass" for rows with generated image data; this is a local-only test action that flood-fills border-connected near-white background pixels on the 160 px thumbnail, uses a soft alpha ramp to preserve light gray food shadows, and stores a PNG for dark-mode inspection without another API call.
  → Writes GeminiScanLog(operation: .foodEmoji or .foodIconImage), updates GeminiCostAccumulator, and schedules optional Turso mirror
  → DEBUG Xcode logs for food icon image generation print the estimated request cost and token counts on the completion line, using the same pricing metadata persisted to GeminiScanLog.
  → SavedFoodRowView shows a circular generated image above calories when image mode is enabled and image data exists; while image mode is enabled but image data is still missing, it shows a neutral photo placeholder rather than falling back to the old emoji.
  → Newly assigned or regenerated generated images animate from SavedFoodRowView using generatedIconImageUpdatedAt: a short scale pulse, diagonal shine, and tiny sparkles pulse. Ordinary row render/scroll should not replay the effect.
  → LogFoodSheet shows the saved food's icon above brand/name: prefer generated image when image mode is enabled and image data exists, otherwise show the saved emoji, with generated image as fallback when no emoji exists.
  → Settings shows the actual generated-image storage footprint from stored SwiftData bytes.

Food Bank Archive Flow

Default Food Bank list
  → Shows active foods only (`!SavedFood.isArchivedInFoodBank`)
  → Empty search filters active foods; non-empty search filters all saved foods so archived matches still appear
  → Trailing swipe: Archive/Unarchive + Edit
  → Leading swipe or tap: LogFoodSheet
  → `NutritionStore.log()` refreshes linked SavedFood usage via `savedFoodID` so logged foods update `lastUsedAt` and leave the archive

Food Bank "+" → Archive
  → FoodBankArchiveView lists foods with `archivedAt != nil` or `lastUsedAt` older than 14 days
  → Users can search archived foods, log them, edit them, or unarchive them
  → Unarchive clears `archivedAt` and refreshes `lastUsedAt` so the item becomes visible in the active list

Food Bank Shelf Recommendation Flow

Food Bank row context menu or Edit Food → Add to Shelf
  → `SavedFood.isOnShelf = true`; age-based auto-archive is bypassed, but manual archive still excludes the food
  → After today's calories reach the configured trigger (default 50%), Food Bank shows "Good Fits" above the normal list
  → `ShelfRecommendationEngine` evaluates deterministic serving candidates against separate energy intent and nutrition-emphasis policies for calorie, protein, fiber, carb, fat, and sodium goals
  → When enabled and sufficiently covered, the prior six days can adjust today's calorie-ranking target by at most ±300 kcal or ±15%; the 50% appearance trigger and optional hard cap still use the normal daily goal
  → Top results include a plain-language reason and quantity; incomplete nutrients are labeled and conservatively penalized or excluded per Settings
  → Tapping a result opens `LogFoodSheet` with the recommended quantity/unit prefilled and still editable

Settings → Food Bank → Shelf Recommendations
  → Enable/disable, top 1...5, 25/50/75/100% trigger, incomplete-data policy, Cut/Maintain/Bulk/Custom energy intent, and Balanced/Protein Focus/Fiber Focus/Low Sodium/Custom nutrition emphasis
  → Custom exposes Reach/Stay Near/Try to Avoid/Ignore plus Gentle/Standard/Strong; it never exposes raw scoring weights
  → Rolling-week context is guarded and clamped; calorie and sodium hard caps are explicit advanced toggles and off by default
  → Configuration syncs through CloudKit `Preferences`, versioned JSON backup/import, and optional Turso mirror

Food Bank Brand Flow

Food Bank toolbar → Brand filter
  → Lists runtime-derived brand buckets from visible saved foods, plus Unbranded for nil/blank brands
  → Empty search uses active foods only; non-empty search uses all foods so archived search matches remain consistent with existing archive behavior
  → Sort menu includes Brand Name, which groups named brands alphabetically before unbranded foods and sorts foods by name within each brand

Food Bank toolbar or "+" menu → Manage Brands
  → User selects one source brand and one target brand or types a new target
  → Bulk consolidation updates SavedFood.brand snapshots for every matching saved food, including archived foods
  → Existing journal entries remain unchanged because logged entries store copied brand/nutrition snapshots

Composite Food Flow

Food Bank "+" → Composite Food
  → CompositeFoodBuilderView
  → User names the composite and adds Food Bank ingredients
  → Each ingredient is stored as CompositeIngredientSnapshot with copied nutrition, serving info, selected quantity, and selected unit
  → SavedFood.refreshCompositeNutrition() sums the selected ingredient portions into a SavedFood(kind: .composite)
  → Editing the composite changes its ingredient snapshots and recalculates future saved-food nutrition only
  → Existing NutritionEntry rows remain unchanged because logging still snapshots SavedFood.toNutritionEntry()

Nutrition Calculator Flow

Food Bank "+" → Nutrition Calculator
  → NutritionCalculatorLibraryView lists SavedFood(kind: .calculator) rows by last used
  → New/Edit opens NutritionCalculatorEditorView
  → User defines restaurant/brand identity and a flat list of ingredients with portion names
  → Ingredient editor can call the selected AI provider's OCR/image understanding on images for the user-named ingredient only
  → Image import stays visibly disabled until the ingredient has a name and at least one image is selected
  → OCR fills nutrition first; imported portions keep source labels when available, otherwise default to "normal"
  → Manually added portions also default to "normal" as actual field text instead of opening with a blank placeholder
  → Calculator ingredients are stored as Codable value arrays on SavedFood, not relationships
  → Build opens NutritionCalculatorBuildView
  → User chooses one portion per ingredient, adjusts quantities, and sees live macro totals
  → Add to Journal writes a NutritionEntry with copied macros/micros, savedFoodID, servingUnit "build", and selectionSummary
  → Later calculator edits affect future builds only; previous NutritionEntry rows keep their logged nutrition snapshot

CloudKit Sync Architecture (app-store branch)

iOS App (SwiftData + CloudKit)
  ←→ iCloud Private Database (automatic, free, multi-device)

  → ScanService → Direct Gemini REST API or OpenRouter chat completions (BYOK, zero server dependency)
  → Gemini/OpenRouter API keys stored in iOS Keychain via KeychainService
  → Optional TursoMirrorService → user-owned Turso DB via SQL-over-HTTP
      ↳ journal/configuration/usage: generation-pruned snapshot mirror
      ↳ detailed AI diagnostics: append-only events with 14-day retention

Strategy: SwiftData's ModelConfiguration(cloudKitDatabase: .private("iCloud.k3vnc.OpenFoodJournal")) handles Apple-device sync automatically. Optional Turso mirroring is a debuggable external copy for SQL inspection; it does not replace SwiftData/iCloud and does not restore data.

CloudKit requirements enforced on all models:

• All stored properties have defaults (including fully qualified enum defaults: MealType.snack not .snack)
• No @Attribute(.unique) (CloudKit can't enforce uniqueness)
• Relationships are optional (var entries: [NutritionEntry]? = [])
• No .deny delete rules

Entitlements: OpenFoodJournal.entitlements includes iCloud (CloudKit), Push Notifications (aps-environment), background mode (remote-notification).

Data migration: TursoMigrationView was deleted — CloudKit replaced the old Turso source-of-truth path. Current Turso support is optional push-only mirroring through TursoMirrorService, with normalized ofj_* tables and JSON columns for complex Swift value fields.

Turso Agent Debugging

When a user has enabled Turso mirroring and provides credentials, use .agents/skills/openfoodjournal/scripts/turso_debug.py for read-only SQL inspection. It accepts TURSO_DATABASE_URL / TURSO_AUTH_TOKEN, common LIBSQL_* aliases, .env by default, or --url / --token. It supports: summary, day YYYY-MM-DD, entry UUID, food-search TEXT, healthkit-pending, ai-events with provider/status/operation/run/request filters, legacy gemini-failures, typed-args-smoke-test, and raw-sql "SELECT ..." (SELECT-only unless --allow-write is passed). ai-events excludes payload_json unless --include-payload is explicit.

GitHub Project Board

Use .agents/skills/openfoodjournal/scripts/github_project_board.py to inspect or update the OpenFoodJournal GitHub Projects v2 kanban board. The helper wraps gh project with repo defaults so agents can avoid retyping owner/repo/project arguments.

Script maintenance: Treat the repo-local path above as the stable command entrypoint, but do not assume it is the canonical source file forever. This helper may later become a symlink to a shared GitHub Projects utility used by OpenFoodJournal and CodeGym. Before changing the script, resolve the real file with realpath .agents/skills/openfoodjournal/scripts/github_project_board.py or readlink, then modify the resolved canonical file and update this skill if the shared location changes. Do not patch a stale copied script while another project points at the shared target. If this is centralized, prefer a neutral shared-tools location near the sibling repos instead of making one app repo own the other app repo's utility.

Requirements:

• gh auth status must show repo and project scopes.
• Default owner/repo: kvn8888/OpenFoodJournal.
• Default project title lookup: OpenFoodJournal.
• Current Status columns are Todo, In Progress, and Done.
• Current Category options are Spikes, Frontend / UX, Backend / API, AI / Gemini, Data / Sync, Health / Integrations, and Project / Process.
• Current Priority options are P0, P1, and P2; Size options are XS, S, M, L, and XL; Source is a text field for the origin of the task.
• GitHub labels are used as an agent work router. Every planned issue should carry exactly one primary agency:* label, exactly one agent:* label, and optionally an output:* label:
  • agency:ready — a coding agent can implement or validate from repo context with little owner input.
  • agency:investigate — a coding agent can independently produce useful diagnosis, evidence, or a plan; implementation may or may not follow.
  • agency:needs-owner-decision — Kevin needs to decide product scope, risk, launch posture, or tradeoffs before implementation.
  • agency:needs-architecture-decision — system shape must be decided before code should move.
  • agency:external-blocked — action depends on Apple, Google, GitHub, CloudKit, App Store Connect, or another external setting/access path.
  • agent:standard — suitable for scoped UI, docs, tests, scripts, and small service changes.
  • agent:strong — use a strong coding agent for cross-layer SwiftData, HealthKit, Gemini, sync, migration, or tricky validation work.
  • agent:frontier — reserve for ambiguous architecture/product/security decisions where a frontier model is worth the cost.
  • output:plan-only — expected output is a decision memo, issue comment, or implementation plan before code.

Common commands:

python .agents/skills/openfoodjournal/scripts/github_project_board.py create
python .agents/skills/openfoodjournal/scripts/github_project_board.py projects
python .agents/skills/openfoodjournal/scripts/github_project_board.py columns
python .agents/skills/openfoodjournal/scripts/github_project_board.py list
python .agents/skills/openfoodjournal/scripts/github_project_board.py list --status Todo
python .agents/skills/openfoodjournal/scripts/github_project_board.py add-issue 4 --status Todo --category "AI / Gemini" --priority P0 --size M --source "manual triage"
python .agents/skills/openfoodjournal/scripts/github_project_board.py move 4 "In Progress"
python .agents/skills/openfoodjournal/scripts/github_project_board.py create-issue --title "Bug title" --body-file /tmp/body.md --label area:healthkit,type:bug,priority:p0,agency:ready,agent:strong --status Todo --category "Health / Integrations" --priority P0 --size M --source "conversation import"
python .agents/skills/openfoodjournal/scripts/github_project_board.py edit-issue 10 --body-file /tmp/body.md --add-label area:healthkit --status Todo --category "Health / Integrations" --priority P0
python .agents/skills/openfoodjournal/scripts/github_project_board.py check-criteria 10 --all
python .agents/skills/openfoodjournal/scripts/github_project_board.py check-criteria 10 "AI Search overlay"
python .agents/skills/openfoodjournal/scripts/github_project_board.py set-fields 10 --status "In Progress" --category "Health / Integrations" --priority P0 --size M --source "validated"

Backup / Export Flow

Settings → Data → Export Spreadsheet CSV
  → NutritionStore.exportCSV()
  → Human-readable analytics CSV with stable IDs, ISO dates, escaped fields, core macros, serving basics, savedFoodID, scanDurationMs, and dynamic micronutrient columns
  → Not intended for restoring app state

Settings → Data → Export Backup
  → NutritionStore.exportBackup(goals, appSettings)
  → Versioned JSON (`schemaVersion: 1`) with DailyLog, NutritionEntry, SavedFood (including emoji, generated icon image data, composite ingredient snapshots, and calculator ingredient snapshots), TrackedContainer, Preferences, UserGoals, meal schedule, and non-sensitive app settings
  → Does not include Gemini/OpenRouter API keys, HealthKit authorization state, or HealthKit samples

Settings → Data → Import Backup
  → Decodes `OpenFoodJournalBackup`
  → Confirms with the user before import
  → NutritionStore.importBackup(...) upserts by stable UUID and relinks entries to DailyLogs by ID
  → Re-importing the same backup updates existing records instead of duplicating them

Settings → Data → Export AI Logs
  → TursoMirrorService.exportDiagnosticCSV()
  → Flushes pending events, then queries the last 14 days from ofj_ai_diagnostic_events
  → Includes provider/model/deployment, run/turn/call/request IDs, timings, usage/cost, status/errors, and bounded redacted operational metadata
  → Does not include prompts, answers, journal/HealthKit values, source URLs/content, attachments, raw provider bodies, chain-of-thought, API keys, or image bytes

Server: The current app path has no proxy server. The iOS app calls Gemini or OpenRouter directly, CloudKit handles Apple-device sync, and optional Turso mirroring talks directly to Turso SQL-over-HTTP. The legacy Express/Turso source-of-truth architecture lives only in old branch history.

Turso mirror schema: TursoMirrorService creates namespaced ofj_* tables: ofj_sync_runs, ofj_daily_logs, ofj_nutrition_entries, ofj_saved_foods, ofj_tracked_containers, ofj_preferences, ofj_user_goals, ofj_app_settings, legacy ofj_gemini_scan_logs, ofj_gemini_cost_accumulators, and append-only ofj_ai_diagnostic_events.

Turso migration pattern: Use CREATE TABLE IF NOT EXISTS for full table creation. For additive columns, query PRAGMA table_info(table_name) and only then run plain ALTER TABLE table ADD COLUMN column TYPE. SQLite/libSQL does not support ALTER TABLE ADD COLUMN IF NOT EXISTS.

Turso sync integration points: SwiftData + CloudKit remain source of truth for conversations, nutrition, run recovery, and usage aggregates. Local application writes call scheduleMirror(reason:); each snapshot mirror upserts current rows with a mirror_generation and prunes older generations per table only after that table succeeds. Detailed diagnostics instead call recordDiagnostic(_:), then flush UUID upserts independently; ofj_ai_diagnostic_events is deliberately excluded from generation pruning. Turso is not read back into application state.

Known Gotchas

1. xcodebuild is stricter than Xcode IDE — missing import SwiftData may compile in previews but fail in CLI builds. Always verify with xcodebuild.
2. .easeInOut is a static property — don't write .easeInOut(value:). The value: belongs to .animation(_:value:).
3. Ternary type mismatch — .primary is HierarchicalShapeStyle, .orange is Color. Use Color.primary to unify.
4. @ObservationIgnored on @AppStorage — required in UserGoals to avoid double-wrapper conflict. Every new @AppStorage property needs it.
5. private enum across structs — private scopes to the type, not the file. Use fileprivate for shared-file enums.
6. ModelContainer(for:configurations:) — not schema:. The Schema wrapper is only for migrations.
7. Swift named parameters must be in declaration order — adding a new init parameter doesn't let you put it anywhere in call sites. Reorder both the declaration and all call sites to match. Build will catch mismatches.
8. PRAGMA table_info() not IF NOT EXISTS for ALTER TABLE — SQLite doesn't support ALTER TABLE ADD COLUMN IF NOT EXISTS. Use PRAGMA to check first.
9. servingQuantity/servingUnit must be set after scaling in LogFoodSheet — toNutritionEntry() copies the food template's serving values; after scaling macros in logButton, write entry.servingQuantity = quantity and entry.servingUnit = selectedUnit so EditEntryView opens with the correct baseline.
10. .swipeActions is silently ignored outside a List — it does nothing in LazyVStack, ScrollView, or VStack. If swipe actions don't fire, check that the is inside a . The modifier compiles without error regardless of container.

What's New Sheet Pattern

WhatsNewSheet is version-gated via @AppStorage("lastSeenVersion") in ContentView. On appear, if lastSeenVersion != currentVersion (from CFBundleShortVersionString), the sheet is presented. On dismiss, lastSeenVersion is updated. To add features for a new version, edit WhatsNewSheet.swift and bump the version header text. Each feature is a FeatureRow(icon:, color:, title:, description:).

v1.1 features: Open Food Facts search, barcode scanning, faster food photo scans (lite model default), reorderable nutrient rings, nutrition history navigation (day/week/month with date picker).

Entitlements (app-store branch)

Already configured in OpenFoodJournal.entitlements:

• com.apple.developer.icloud-services: CloudKit
• com.apple.developer.icloud-container-identifiers: iCloud.k3vnc.OpenFoodJournal
• aps-environment: development (auto-switches to production on Archive)
• UIBackgroundModes: remote-notification

Still needed (must add to entitlements):

• com.apple.developer.healthkit (HealthKit usage compiles but entitlement missing)

Still needed (provisioning profile):

• Enable iCloud + Push Notifications capabilities in Apple Developer portal
• Regenerate provisioning profile

Branches

• main — Original Turso sync architecture. SyncService.swift present, all views have fire-and-forget sync Tasks. Treat this as legacy branch history, not the current app-store architecture.
• testflight — Protected integration/beta branch. Pull requests run cloud compile and non-UI unit/provider-contract tests. Trusted pushes allocate a remote-safe build number, archive once on the pinned GitHub xcode-27 runner, upload to internal TestFlight, and create an immutable testflight/<version>-<build> prerelease manifest.
• app-store — Protected production-promotion branch for the CloudKit architecture and the repository default branch. It must promote a reachable, manifest-backed TestFlight build without rebuilding the binary. App-affecting changes after the selected TestFlight tag block promotion. Normal pushes stage metadata, attach the exact build, validate, and prepare a private vX.Y GitHub release draft; App Review submission requires an explicit manual input plus protected-environment approval. A six-hour public-release sync publishes the draft only after Apple's public storefront reports the same version.

Cloud CI and release workflow

See docs/cloud-release-workflow.md for the old-versus-new comparison, workflow behavior, security model, secrets, branch protections, rollout checklist, and current blockers.

• .github/workflows/cloud-ci.yml runs release-workflow contract tests, compiles all targets, and executes OpenFoodJournalUnitTests on a hosted simulator. It never runs UI tests or receives deployment/provider secrets.
• .github/workflows/release-credentials-check.yml is a manual, read-only smoke workflow. It checks App Store Connect app/build access from both deployment environments and independently validates the TestFlight certificate/password and provisioning profile without allocating a build number, archiving, uploading, staging, or submitting.
• .github/workflows/testflight.yml is gated by ENABLE_TESTFLIGHT_AUTOMATION=true and the testflight-internal GitHub environment. It validates the source-controlled marketing version, allocates only the build number automatically, drafts version-specific public notes with GitHub Models plus deterministic fallback, validates the 4,000-character/locale contract, uses ephemeral signing assets, distributes internally, and publishes an immutable schema-2 commit/build/IPA/notes manifest. DerivedData, archives, IPA files, and signing material are not retained.
• .github/workflows/app-store.yml is gated by ENABLE_APP_STORE_AUTOMATION=true. Its unprivileged prepare job resolves and displays the exact TestFlight binary and hash-bound public notes before the protected app-store-production environment asks for approval. The approved job reverifies the artifact, stages the existing VALID build without recompiling, copies prior public metadata, applies the reviewed notes, runs strict readiness checks, and prepares a private vX.Y draft containing the schema-2 manifest and notes. A normal push never submits; submission requires workflow_dispatch with submit_for_review=true plus environment approval.
• .github/workflows/app-store-release-sync.yml runs every six hours or manually without Apple credentials. It reads Apple's public storefront version, resolves the matching private vX.Y draft, verifies its app/version/build/TestFlight tag/commit/target/note hash against the attached schema-2 manifest, and only then publishes it as the immutable Latest GitHub release. An already-published match is an idempotent no-op; a missing or mismatched draft fails closed.
• ci/release-config.json owns non-secret Apple identifiers, toolchain pins, and the default GitHub Models release-note model. Credentials stay in protected GitHub environment secrets or an external secrets manager.
• GitHub Models receives only bounded commit-derived release evidence through a short-lived with . AI may draft public copy, but deterministic automation validates and seals the artifact. Build numbers, signing, build identity, upload/promotion, state changes, legal/privacy/export/health declarations, and public submission remain outside AI authority.

Conventions

• Comments: Explain why, not what. Entry-level devs should understand each function's purpose.
• File creation: Build large files in small chunks to avoid network errors.
• Retrospectives: Live in docs/. Update when later fixes change the story.
• Skills: This file is the project skill. Update it when architecture or requirements change.
• Commits: Descriptive messages. Push after every significant change.

DailyLogView container: Uses a List (not ScrollView+LazyVStack) with .listStyle(.plain) + .scrollContentBackground(.hidden). WeeklyCalendarStrip and MacroSummaryBar are plain List rows with listRowBackground(Color.clear) + listRowSeparator(.hidden). Meal sections use MealSectionView which returns a Section{} that becomes a proper sticky List section header in a List context. All swipe actions are on the MealSectionView Button wrapper (not on EntryRowView).

Repeat logging and scan-to-container UX: LogFoodSheet applies the most recent valid quantity + unit for the linked SavedFood on first appearance, falling back to the template when history is missing or its unit is no longer available. Scan results expose an explicit "Save to Food Bank & Track Container" action that saves without journal logging and presents NewContainerSheet(preselectedFood:); dismissing container setup keeps the Food Bank item.

RadialMenuButton: Option bubbles support direct .onTapGesture (as well as drag-to-select). A Color.clear.contentShape(Rectangle()).ignoresSafeArea() layer behind GlassEffectContainer dismisses the menu when tapping outside. The layer is only inserted into the ZStack when isOpen == true. Option label text has a subtle drop shadow for legibility over light/glass backgrounds.

Swipe mappings:

• FoodBankView row: trailing (swipe left) = Archive/Unarchive (gray/green) + Edit (blue); leading (swipe right) = Add to journal (green)
• MealSectionView row: trailing (swipe left) = Delete; leading (swipe right) = Edit — both on the outer Button wrapper (never on EntryRowView to avoid double-registration gesture lag)

FoodNutrientBreakdownView: Inverse of NutrientBreakdownView — shows all nutrients (macros + micros) for a specific food across the selected period. Accessed by tapping a food row in NutrientBreakdownView's "By Food" section.

EditEntryView: Has full serving-mappings section (same as LogFoodSheet). Uses shared AddServingMappingSheet (defined in LogFoodSheet.swift, internal not private). addMapping() calls nutritionStore.saveEntry(entry).

CursorEndModifier: Applied once at the app root with .cursorAtEnd(). It keeps UITextField cursors at the end on focus and installs a non-canceling window tap recognizer that dismisses the keyboard when tapping outside text inputs. Keep this centralized instead of adding competing per-view whitespace tap gestures.

Current State (Last Updated: 2026-07-26)

• Branch: app-store — CloudKit is the primary sync path, with optional push-only Turso mirror for user-owned SQL debugging
• Cloud release foundation — Both release branches and deployment environments exist. Credentials pass App Store Connect read checks, and TestFlight signing assets pass integrity checks. testflight-internal is restricted to testflight; app-store-production is restricted to app-store and requires kvn8888 approval. Both branches require pull requests, resolved conversations, and cloud CI; force pushes/deletion are blocked. testflight stays linear, while app-store uses merge commits for promotion so immutable TestFlight tags remain ancestors of production. GitHub release immutability and scheduled public-App-Store release synchronization are enabled, and both deployment variables are enabled.
• Public App Store: version 1.3 build 3 — live App Store Connect state READY_FOR_DISTRIBUTION; GitHub v1.2 and v1.3 releases were reconciled to Apple on 2026-07-30, with v1.3 Latest.
• Internal TestFlight: version 1.4 build 11 — immutable schema-2 prerelease manifest testflight/1.4-11; it remains a prerelease until Apple publishes App Store version 1.4.
• App structure complete: all models, services, and views implemented
• 5-tab layout: Journal, Food Bank, History, Assistant, Settings (Containers accessed via RadialMenuButton)
• Assistant tab (agent foundations 2026-07-20): persistent CloudKit-synced agentic chat with independent Gemini/OpenRouter/Azure provider selection, independent model-native/Tavily/Parallel web-research selection, Azure Sol/Terra deployments, 50k/200k/maximum token budgets, portable compaction, durable versioned sources, cancellation/recovery, and retry-safe approved writes. Read tools (journal, Food Bank, goals, Apple Health energy, calculators, web_search, secure fetch_url, and read_conversation_source) run silently with activity/source chips; write tools show durable Allow/Deny permission cards. Supports image/PDF attachments, regenerate, provider-reported usage, context meter/warnings, and the always-visible "not medical advice" footer.
• App and full unit/UI test targets compile with xcodebuild ... build-for-testing against generic/platform=iOS; generic unsigned Release and signed App Store archives also succeed. The installed simulator runtime works with an isolated /private/tmp device set, but this Mac's default CoreSimulator store is symlinked to an external volume that CoreSimulatorService cannot write, so XCTest execution needs that host configuration repaired or a safe signed device destination.

App Store Submission Notes

First submission rejected (Guideline 1.4.1 — Physical Harm): App provided health/nutrition data without citations. Fixed by adding HealthDisclaimerView (Settings → Sources & Disclaimers) with FDA Daily Values links, Atwater system reference, AI estimation disclaimer, and general medical disclaimer. Inline citations added to NutritionDetailView, ScanResultCard, and GoalsEditorView.

Other audit findings to address before next submission:

• README.md has been updated for the current app-store architecture, including optional Turso mirroring. Re-check before submission if branch contents change again.
• Reviewer notes previously contained false HealthKit claim ("data is never read") — corrected to list all read/write types.
• server/ directory and render.yaml are dead code on app-store branch — reviewers clicking the GitHub link may be confused.
• AGPL-3.0 license has App Store exception in LICENSE_NOTICE.md — Apple may or may not flag this.
• Privacy policy is web-only (GitHub link) — fails offline. Consider embedding a copy in-app.

Planned Work (Backlog)

UX / Feature Improvements

• Weekly/monthly view should display daily averages — In NutritionDetailView, when selectedPeriod is .weekly or .monthly, macroTotals currently accumulates totals. For multi-day periods, display the daily average (total ÷ days in period) so "14,000 kcal this week" becomes "2,000 kcal/day avg". The period picker label should reflect this ("Weekly Avg", "Monthly Avg"). Same applies to the comparisonCard values in HistoryView.weekComparisonSection (already divides by 7 — verify .monthly path does the same).

Open Food Facts Integration

• Open Food Facts (OFF) is a free, open database of 4M+ food products. Integrated into the Food Bank for searching and adding foods without scanning.
• Service: OpenFoodFactsService — @Observable @MainActor service for OFF REST API calls (text search + barcode lookup). Injected via .environment() from MacrosApp.
• API endpoints used:
  • Text search: GET https://search.openfoodfacts.org/search?q={query}&fields=product_name,brands,code,nutriments,serving_size,serving_quantity&page_size=25 — dedicated Elasticsearch-backed search service (the legacy v1 CGI endpoint returns 503)
  • Barcode/product lookup (v2): GET https://world.openfoodfacts.org/api/v2/product/{barcode}?fields=... — full nutrition data
  • Filtering: OFFProduct.hasUsableNutrition requires calories > 0 plus at least one macro or micronutrient. Text search and barcode lookup reject zero-calorie/no-nutrition placeholder rows before UI prefill.
  • Fields requested (for product detail): product_name,brands,nutriments,serving_size,serving_quantity,code
  • Nutriments mapping: energy-kcal_100g → calories, proteins_100g → protein, carbohydrates_100g → carbs, fat_100g → fat, plus micronutrients (fiber, sugar, sodium, etc.)
  • User-Agent: OpenFoodJournal/1.0 ([e-mail]) — required by OFF API policy
  • Rate limits: 10 req/min for search, 100 req/min for product reads
  • No auth required for reads; writes (contribute) require OFF account credentials
• UI access points:
  • FoodBankView toolbar: "+" button (leading of sort button) → Menu with 3 options: Scan, Manual Entry, Search Open Food Facts
  • Scan and Manual Entry reuse existing sheets (ScanView via DailyLogSheet, ManualEntryView)
  • Search Open Food Facts opens OpenFoodFactsSearchView — Enter-only search, filtered usable results, tap to review details
  • Result action: Same pattern as ManualEntryView — "Add to Journal" or "Add to Journal & Food Bank" via toolbar Menu