Caluru

Caluru - Architecture Guide

This document describes the high-level architecture, design patterns, and key data flows in Caluru.

---

📐 Architecture Overview

Caluru uses MVVM with SwiftData + CloudKit for persistence and Supabase for Auth and AI proxy. Entry and shell:

• CaluruApp (@main): Creates ModelContainer (SwiftData + CloudKit private iCloud.com.agarcia.caluru); injects .modelContainer; applies preferredColorScheme from appTheme; runs AuthService.restoreSession() and setupNotificationsIfNeeded(); uses AppDelegate for UNUserNotificationCenter (foreground presentation, tap handling).
• ContentView: Simply presents MainTabView() (used if you need a single root; otherwise app can point directly to MainTabView).
• MainTabView: Hosts 5 tabs (Home, Plan, Scan, Recipes, Profile); shows onboarding as fullScreenCover when hasCompletedOnboarding is false (derived from profiles.first?.hasCompletedOnboarding after a short CloudKit wait); shows progressive profiling overlay when ProgressiveProfilingService.shared.currentCard is non-nil; runs SeedDataService.seedIfNeeded and profiling triggers on appear.

Layers:

┌─────────────────────────────────────────────────────────────────┐
│                         SwiftUI Views                           │
│  MainTabView, Home, Plan, Scan, Recipes, ShoppingList,          │
│  Assistant, Profile, Onboarding (Duolingo-style quiz flow)              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     ViewModels (@Observable)                    │
│  Home, Plan, Scan, Recipes, ShoppingList, Assistant,           │
│  Profile, Onboarding                                            │
│  • State & navigation                                            │
│  • Data load/save via ModelContext                              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                         Services Layer                          │
│  NutritionCalculator, SeedDataService, ShoppingListBuilder      │
│  AIAssistantService (AssistantResponseService) → OpenAIProxy   │
│  OpenFoodFactsService, FoodRecognitionService (→ OpenAIProxy)   │
│  AuthService, TargetCalculator, MealPlanGenerator              │
│  ProgressiveProfilingService, NotificationService               │
│  AccountResetService, RecipeService, OnboardingAnalytics       │
└─────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
┌──────────────────┐ ┌──────────────┐ ┌─────────────────────────┐
│ SwiftData        │ │ Supabase     │ │ External APIs            │
│ + CloudKit       │ │ Auth +       │ │ Open Food Facts         │
│ (local + sync)   │ │ openai-proxy │ │ (barcode)                │
└──────────────────┘ └──────────────┘ └─────────────────────────┘

---

🎨 Design Patterns

1. MVVM (Model-View-ViewModel)

Implementation:

• Views: SwiftUI structs in /Views/ folder
• ViewModels: @Observable classes in /ViewModels/ folder
• Models: SwiftData @Model classes in /Models/ folder

Example:

// View (HomeView.swift)
struct HomeView: View {
    @State private var viewModel = HomeViewModel()
    // View reads from viewModel, calls viewModel methods
}

// ViewModel (HomeViewModel.swift)
@Observable
class HomeViewModel {
    var dailyLog: DailyLog?
    func loadData(context: ModelContext) { ... }
    func addFoodItem(_ food: FoodItem, ...) { ... }
}

2. Dependency Injection via Environment

SwiftData’s ModelContext is injected via SwiftUI’s environment:

// App entry point
@main
struct CaluruApp: App {
    var body: some Scene {
        WindowGroup {
            MainTabView()
        }
        .modelContainer(sharedModelContainer)  // Injects ModelContext
    }
}

// View accesses it
struct HomeView: View {
    @Environment(\.modelContext) private var modelContext
}

3. Static Services (Utility Pattern)

Services are implemented as classes with static methods (no instances needed):

class NutritionCalculator {
    static func calculate(from log: DailyLog) -> NutritionSummary { ... }
    static func suggestRecipe(...) -> Recipe? { ... }
}

4. Onboarding Gate (CloudKit-Driven)

• MainTabView uses @Query private var profiles: [UserProfile] and hasCompletedOnboarding = profiles.first?.hasCompletedOnboarding == true.
• On first launch (or reinstall), CloudKit may not have synced yet; a short delay (~2s) is used before setting hasCheckedCloudKit so an existing profile can appear and skip onboarding.
• Onboarding draft is stored in UserDefaults (OnboardingState); final result is written to UserProfile in SwiftData and onboardingCompletedAt set.

5. Codable Nested Data

Complex nested data is stored as JSON Data in SwiftData models:

@Model
final class DailyLog {
    var entriesData: Data?  // Stored as JSON
    
    var entries: [MealEntry] {
        get { /* decode from entriesData */ }
        set { /* encode to entriesData */ }
    }
}

---

🗺 Component Diagram

graph TB
    subgraph App["Caluru App"]
        subgraph Views["Views Layer"]
            MainTab[MainTabView]
            Home[HomeView]
            Plan[WeeklyPlanView]
            Scan[ScanView]
            Recipes[RecipesView]
            RecipeDetail[RecipeDetailView]
            Shopping[ShoppingListView]
            Assistant[AssistantView]
            AddFood[AddFoodSheet]
            Profile[ProfileView]
            Onboarding[OnboardingFlowView]
        end
        
        subgraph ViewModels["ViewModels Layer"]
            HomeVM[HomeViewModel]
            PlanVM[WeeklyPlanViewModel]
            ScanVM[ScanViewModel]
            RecipesVM[RecipesViewModel]
            ShoppingVM[ShoppingListViewModel]
            AssistantVM[AssistantViewModel]
            ProfileVM[ProfileViewModel]
            OnboardingVM[OnboardingViewModel]
        end
        
        subgraph Services["Services Layer"]
            NutritionCalc[NutritionCalculator]
            ShoppingBuilder[ShoppingListBuilder]
            AIAssistant[AIAssistantService]
            OpenAIProxy[OpenAIProxyService]
            OpenFoodFacts[OpenFoodFactsService]
            FoodRecognition[FoodRecognitionService]
            AuthSvc[AuthService]
            TargetCalc[TargetCalculator]
            MealPlanGen[MealPlanGenerator]
            ProgressiveProf[ProgressiveProfilingService]
            NotifSvc[NotificationService]
            SeedData[SeedDataService]
        end
        
        subgraph Data["SwiftData Layer"]
            UserProfile[(UserProfile)]
            FoodItem[(FoodItem)]
            Recipe[(Recipe)]
            DailyLog[(DailyLog)]
            WeeklyPlan[(WeeklyPlan)]
            ShoppingList[(ShoppingList)]
            WeightEntry[(WeightEntry)]
        end
        
        subgraph DesignSystem["Design System"]
            Colors[AppColors]
            Typography[AppTypography]
            Components[UI Components]
        end
    end
    
    MainTab --> Home
    MainTab --> Plan
    MainTab --> Scan
    MainTab --> Recipes
    MainTab --> Profile
    MainTab --> Onboarding
    
    Home --> HomeVM
    Plan --> PlanVM
    Scan --> ScanVM
    Recipes --> RecipesVM
    Shopping --> ShoppingVM
    Assistant --> AssistantVM
    
    HomeVM --> NutritionCalc
    HomeVM --> DailyLog
    HomeVM --> UserProfile
    
    PlanVM --> WeeklyPlan
    PlanVM --> Recipe
    
    ShoppingVM --> ShoppingBuilder
    ShoppingVM --> ShoppingList
    ShoppingVM --> WeeklyPlan
    
    AssistantVM --> AIAssistant
    AIAssistant --> OpenAIProxy
    AssistantVM --> DailyLog
    AssistantVM --> Recipe
    
    ScanVM --> OpenFoodFacts
    ScanVM --> FoodRecognition
    FoodRecognition --> OpenAIProxy
    ScanVM --> FoodItem
    
    ProfileVM[ProfileViewModel] --> AuthSvc
    ProfileVM --> WeightEntry
    OnboardingVM[OnboardingViewModel] --> TargetCalc
    OnboardingVM --> UserProfile
    
    Views --> Components
    Views --> Colors
    Views --> Typography

---

🔄 Key Data Flows

Flow 1: Adding a Meal (Food Logging)

sequenceDiagram
    participant User
    participant HomeView
    participant HomeVM as HomeViewModel
    participant AddSheet as AddFoodSheet
    participant DailyLog
    participant SwiftData as ModelContext
    
    User->>HomeView: Tap "+" on Desayuno row
    HomeView->>HomeVM: openAddFood(for: .desayuno)
    HomeVM->>HomeVM: showAddFoodSheet = true
    HomeView->>AddSheet: Present sheet
    
    User->>AddSheet: Search & select "Huevo"
    AddSheet->>HomeVM: onAddFood(foodItem, 1.0)
    HomeVM->>HomeVM: Create LoggedItem from FoodItem
    HomeVM->>DailyLog: addItem(loggedItem, to: .desayuno)
    DailyLog->>DailyLog: Encode entries to JSON Data
    HomeVM->>SwiftData: context.save()
    
    Note over HomeView: SwiftUI observes @Observable
    HomeView->>HomeView: UI updates with new totals
    
    Note over HomeView: Progress ring animates<br/>Macro cards update

Flow 2: Generating Shopping List

sequenceDiagram
    participant User
    participant ShoppingView as ShoppingListView
    participant ShoppingVM as ShoppingListViewModel
    participant Builder as ShoppingListBuilder
    participant WeeklyPlan
    participant ShoppingList
    
    User->>ShoppingView: Tap "Actualizar"
    ShoppingView->>ShoppingVM: regenerateFromPlan()
    ShoppingVM->>WeeklyPlan: Fetch current plan
    ShoppingVM->>Builder: build(from: plan)
    
    loop For each day in plan
        Builder->>Builder: Get breakfast/lunch/dinner recipes
        Builder->>Builder: Extract ingredients
        Builder->>Builder: Aggregate by name+unit
    end
    
    Builder-->>ShoppingVM: Return [ShoppingListItem]
    ShoppingVM->>ShoppingList: Update items
    ShoppingVM->>ShoppingView: UI refreshes

---

🧭 Navigation Architecture

Tab-Based Navigation

The app uses a custom TabView with 5 tabs. Shopping List is reached from Plan (e.g. cart icon) or can be a separate tab depending on implementation.

Tab	View	Icon
Inicio	HomeView	house.fill
Plan	WeeklyPlanView	calendar
Scan	ScanView (fullScreenCover)	camera.fill
Recetas	RecipesView	book.fill
Perfil	ProfileView	person.fill

Navigation Stack

Each tab uses NavigationStack for internal navigation:

struct RecipesView: View {
    var body: some View {
        NavigationStack {
            // Grid of recipes
            .navigationDestination(isPresented: $viewModel.showRecipeDetail) {
                RecipeDetailView(recipe: viewModel.selectedRecipe!)
            }
        }
    }
}

Modal Sheets

Used for:

• AddFoodSheet - Adding food to meals
• RecipePickerSheet - Selecting recipe for meal plan
• AddShoppingItemSheet - Manual item entry
• AssistantView - Chat interface

---

💾 Persistence Strategy

SwiftData Configuration

// CaluruApp.swift
let schema = Schema([
    UserProfile.self,
    FoodItem.self,
    Recipe.self,
    DailyLog.self,
    WeeklyPlan.self,
    ShoppingList.self,
    WeightEntry.self
])

let modelConfiguration = ModelConfiguration(
    schema: schema,
    isStoredInMemoryOnly: false,
    cloudKitDatabase: .private("iCloud.com.agarcia.caluru")
)

Data Storage Location

• Local: SwiftData store (e.g. ~/Library/Application Support/default.store).
• Sync: CloudKit private database for the same schema (when enabled).

Seeding Strategy

On first launch, SeedDataService.seedIfNeeded() checks for existing UserProfile:

• If empty → Seeds all initial data
• If exists → Skips (preserves user data)

---

🔐 State Management

@Observable Pattern (iOS 17+)

ViewModels use the new @Observable macro:

@Observable
class HomeViewModel {
    var selectedDate: Date = Date()      // Observed by Views
    var dailyLog: DailyLog?              // Observed by Views
    var showAddFoodSheet: Bool = false   // Controls sheet presentation
}

State Ownership

| State Type | Owner | Example | |————|——-|———| | UI State | ViewModel | showAddFoodSheet, selectedCategory | | Domain Data | SwiftData | DailyLog, Recipe | | Navigation | View (@State) | selectedTab, showScanView | | Environment | SwiftUI | modelContext |

---

🔌 Dependency Boundaries

┌─────────────────────────────────────────────────────────────────┐
│                          Views                                  │
│  • Import: SwiftUI, SwiftData                                  │
│  • Depend on: ViewModels, DesignSystem, Models                 │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                        ViewModels                               │
│  • Import: Foundation, SwiftData, SwiftUI                      │
│  • Depend on: Models, Services                                 │
│  • Do NOT import: Views, DesignSystem                          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                         Services                                │
│  • Import: Foundation, SwiftData (where needed)                │
│  • Depend on: Models                                           │
│  • Do NOT import: Views, ViewModels, DesignSystem              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                          Models                                 │
│  • Import: Foundation, SwiftData                               │
│  • Depend on: Nothing (pure data)                              │
└─────────────────────────────────────────────────────────────────┘

---

⚡ Performance Considerations

Lazy Loading

• Recipe grid uses LazyVGrid for efficient scrolling
• Shopping list sections are rendered on-demand

JSON Encoding Overhead

Nested data (entries, ingredients, steps) is encoded/decoded as JSON. For large datasets, consider:

• Caching decoded values
• Using separate SwiftData relationships

Image Placeholders

Currently uses SF Symbols as placeholders. For real images:

• Use AsyncImage with caching
• Implement progressive loading

---

🔮 Future Architecture Considerations

Backend Integration (Current)

• Assistant: AIAssistantService uses OpenAI GPT-4o-mini via Supabase Edge Function openai-proxy; API key server-side only.
• Scan: Barcode via OpenFoodFactsService; photo via FoodRecognitionService (GPT-4o Vision through same proxy).
• Auth: Optional Sign in with Apple via Supabase Auth.
• Sync: CloudKit private database for SwiftData.
• Mock: MockFoodRecognitionService remains available as fallback/offline.

Modularization

Current structure supports splitting into Swift packages:

• CaluruCore - Models, Services
• CaluruUI - DesignSystem, Components
• CaluruApp - Views, ViewModels

---

📚 Related Documents

• Backend - Supabase Edge Function, Auth, CloudKit
• Data Model Reference
• Screens Reference
• Services Reference