Caluru

Caluru - Project Documentation

A comprehensive iOS nutrition tracking and meal planning app built with SwiftUI, SwiftData, Supabase, and CloudKit.

🍎 What is Caluru?

Caluru is a hybrid local + cloud nutrition app that helps users:

Language

The app UI is in Spanish (localized strings, labels, recipe content).

🛠 Tech Stack

Technology Version / Note Purpose
Swift 5.9+ Language
SwiftUI iOS 17+ UI
SwiftData iOS 17+ Local persistence
CloudKit iOS 17+ Sync (private container iCloud.com.agarcia.caluru)
Supabase — Auth (Sign in with Apple), Edge Function (openai-proxy)
OpenAI API — GPT-4o-mini (Assistant), GPT-4o (food photo); key server-side only
Open Food Facts — Barcode product lookup
AVFoundation — Camera / barcode scanning
UserNotifications — Meal, goal, streak, weight reminders
SF Symbols — Icons

Requirements

🚀 How to Run Locally

Step 1: Clone/Open the Project

cd /path/to/Caluru
open Caluru.xcodeproj

Step 2: Select Target

Step 3: Build and Run

# Or press Cmd+R in Xcode

Step 4: First Launch

📁 Project Structure

Caluru/                    # repo root
├── Caluru.xcodeproj
├── Caluru/                  # app source
    ├── CaluruApp.swift     # @main; ModelContainer (SwiftData + CloudKit); theme; notifications; AppDelegate (notifications)
    ├── ContentView.swift        # → MainTabView
    ├── Config.swift            # SupabaseConfig (url, anonKey from Info.plist)
    │
    ├── Models/
    │   ├── UserProfile.swift   # Extended: onboarding, targets, legacy (dietType, allergies, etc.)
    │   ├── FoodItem, Recipe, Ingredient, DailyLog, MealEntry, LoggedItem
    │   ├── WeeklyPlan, PlannedDay, ShoppingList, ShoppingListItem
    │   ├── WeightEntry.swift
    │   ├── OnboardingState.swift, OnboardingTypes.swift  # Onboarding enums & draft state
    │   ├── AssistantAction.swift  # LogMeal, CreateRecipe, GenerateMealPlan, AdjustTarget, viewRecipe, viewProgress
    │   └── CloudRecipe.swift (if used)
    │
    ├── Views/
    │   ├── MainTabView.swift   # 5 tabs; onboarding fullScreenCover; progressive profiling overlay
    │   ├── Home/ (HomeView, AddFoodSheet)
    │   ├── Plan/ (WeeklyPlanView)
    │   ├── Scan/ (ScanView)
    │   ├── Recipes/ (RecipesView, RecipeDetailView, AddRecipeSheet)
    │   ├── ShoppingList/ (ShoppingListView)
    │   ├── Assistant/ (AssistantView)
    │   ├── Profile/ (ProfileView, AppPreferencesView, WeightTrackingView, NotificationsSettingsView, LegalView)
    │   └── Onboarding/
    │       ├── OnboardingFlowView.swift
    │       ├── Screens/ (S0Welcome, S1WelcomeGoal, SMotivations, S15Confidence, EncouragementGoals, SQuickBasics, SBodyMetrics, S8–S10, S12–S13, SMealsDessert, SDislikedFoods, STargetsReveal, SignIn, S0aName, S0bUsername, SFirstLogNudge, AdjustTargetsSheet)
    │       └── Components/ (shared onboarding UI in OnboardingFlowView)
    │
    ├── ViewModels/
    │   ├── HomeViewModel, WeeklyPlanViewModel, RecipesViewModel
    │   ├── ScanViewModel, ShoppingListViewModel, AssistantViewModel
    │   ├── ProfileViewModel, OnboardingViewModel
    │   └── (Models/HomeViewModel.swift if present)
    │
    ├── Services/
    │   ├── NutritionCalculator, SeedDataService, ShoppingListBuilder
    │   ├── AssistantResponseService.swift  # AIAssistantService (GPT-4o-mini via OpenAIProxyService)
    │   ├── OpenAIProxyService   # Calls Supabase Edge Function openai-proxy
    │   ├── OpenFoodFactsService # Barcode lookup
    │   ├── FoodRecognitionService # Photo → GPT-4o Vision via proxy
    │   ├── MockFoodRecognitionService # Fallback/offline
    │   ├── SupabaseClient.swift # SupabaseManager (shared client)
    │   ├── AuthService         # Sign in with Apple, session restore, signOut
    │   ├── TargetCalculator   # Mifflin-St Jeor; onboarding targets
    │   ├── MealPlanGenerator  # Auto-generate weekly plan
    │   ├── ProgressiveProfilingService # Post-onboarding profile cards
    │   ├── NotificationService # Meal, goal, streak, weight reminders
    │   ├── AccountResetService # Reset data / re-onboard
    │   ├── RecipeService, OnboardingAnalytics
    │   └── ...
    │
    ├── DesignSystem/
    │   ├── AppColors, AppTypography, AppSpacing
    │   └── Components/ (Card, PillSegment, MacroChip, PrimaryButton, IconButton, EmptyState, ProgressRing, SearchBar, RecipeCard, StreakBadge, ...)
    │
    └── Assets.xcassets/

⚙️ Configuration

Nutrition Targets

Default targets are defined in Services/SeedDataService.swift:

UserProfile(
    calorieTarget: 3500,
    proteinTarget: 190,
    carbsTarget: 250,
    fatTarget: 85,
    language: "es"
)

Color Palette

Edit DesignSystem/AppColors.swift:

Color Hex Usage
accentGreen #8FB996 Primary accent, buttons, progress
background #F5F6F8 Screen backgrounds
cardBackground #FFFFFF Card surfaces
textPrimary #1A1A2E Main text
textSecondary #6B7280 Secondary text

Supabase (Info.plist or xcconfig)

Permissions

The app does not request microphone access (NSMicrophoneUsageDescription is not present).

See App Store Connect listing for store metadata that matches in-app branding.

🔨 Build Commands

Command Action
Cmd+R Build and run
Cmd+B Build only
Cmd+U Run tests
Cmd+Shift+K Clean build folder

Testing

# Unit tests
xcodebuild test -scheme Caluru -destination 'platform=iOS Simulator,name=iPhone 15'

🐛 Common Troubleshooting

“Multiple commands produce Info.plist”

The project auto-generates Info.plist. Delete any manually created Info.plist file in the source folder.

SwiftData not persisting

Ensure the ModelContainer is configured with isStoredInMemoryOnly: false in CaluruApp.swift.

Camera not working in simulator

Camera features require a physical device. The simulator will show a blank preview.

Seed data not appearing

  1. Delete the app from the simulator/device
  2. Clean build folder (Cmd+Shift+K)
  3. Run again to trigger fresh seed

Swift 6 concurrency warnings

The project uses SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor. ViewModels that access UI state from async contexts must be marked @MainActor.

📚 Additional Documentation

📄 License

This project is for educational and demonstration purposes.