Caluru

Caluru - Data Model Reference

This document describes all data models, their fields, relationships, and how data flows through the system.

📊 Entity Relationship Overview

┌─────────────────┐
│   UserProfile   │ ──── Singleton; onboarding fields, targets, legacy
│ (hasCompleted   │       onboardingCompletedAt → onboarding gate
│  Onboarding)    │
└─────────────────┘

┌─────────────────┐       ┌─────────────────┐
│  WeightEntry    │       │   UserProfile   │ (linked by app; no FK)
│ (weight log)   │       └─────────────────┘
└─────────────────┘

┌─────────────────┐       ┌─────────────────┐
│    FoodItem     │       │     Recipe      │
│  (40+ seeded)   │       │  (20+ seeded)   │
└─────────────────┘       └─────────────────┘
         │                        │
         │                        │ contains
         │                        ▼
         │               ┌─────────────────┐
         │               │   Ingredient    │ (Codable struct)
         │               └─────────────────┘
         │
         ▼
┌─────────────────┐       
│   LoggedItem    │ ←──── Created when user logs food/recipe
│ (Codable struct)│
└─────────────────┘
         │
         │ grouped by
         ▼
┌─────────────────┐
│   MealEntry     │ (Codable struct: desayuno/comida/cena/snack)
└─────────────────┘
         │
         │ belongs to
         ▼
┌─────────────────┐
│    DailyLog     │ ──── One per day
└─────────────────┘

┌─────────────────┐       ┌─────────────────┐
│   WeeklyPlan    │ ────► │   PlannedDay    │ (7 per plan)
│ (one per week)  │       │ (Codable struct)│
└─────────────────┘       └─────────────────┘
                                  │
                                  │ references
                                  ▼
                          ┌─────────────────┐
                          │  PlannedRecipe  │ (Codable snapshot)
                          └─────────────────┘

┌─────────────────┐       ┌─────────────────┐
│  ShoppingList   │ ────► │ShoppingListItem │ (Codable struct)
│ (one per week)  │       └─────────────────┘
└─────────────────┘

Not in SwiftData: OnboardingState (UserDefaults), AssistantAction and related structs (Codable, parsed from AI or in-memory).

📋 Model Definitions

UserProfile

File: Models/UserProfile.swift
Type: SwiftData @Model
Purpose: User profile: onboarding answers, nutrition targets, preferences, segmentation.

Field	Type	Description
`id`	`UUID`	Unique identifier
`name`	`String?`	Display name
`age`	`Int?`	Age (for BMR/targets)
`height`	`Double?`	Height in cm (base unit)
`weight`	`Double?`	Weight in kg (base unit)
`profileImageData`	`Data?`	Profile picture (JPEG)
Onboarding
`goalTypeRaw`	`String?`	GoalType raw
`otherGoalTagsData`	`Data?`	[OtherGoalTag]
`privacyPreferenceRaw`	`String?`	PrivacyPreference
`unitSystemRaw`	`String?`	UnitSystem (metric/imperial)
`sexEstimationRaw`	`String?`	SexEstimation (for BMR)
`activityLevelRaw`	`String?`	ActivityLevel
`trainingDays`	`Int?`	Training days per week
`goalPaceRaw`	`String?`	GoalPace
`trackingModeRaw`	`String?`	TrackingMode
`dietaryPreferencesData`	`Data?`	[DietaryPreference]
`allergiesAvoidsData`	`Data?`	[AllergyType]
`cookingTimeRaw`	`String?`	Legacy unused (was CookingTime preference)
`confidence`	`Int?`	1–5 nutrition/cooking experience (from onboarding skill step)
`snackingFrequencyRaw`	`String?`	SnackingFrequency
`dessertFrequencyRaw`	`String?`	DessertFrequency
Targets
`calorieTarget`	`Int`	Daily calorie goal
`proteinTarget`	`Int`	Protein goal (g)
`carbsTarget`	`Int`	Carbs goal (g)
`fatTarget`	`Int`	Fat goal (g)
Segmentation
`structureNeedScore`	`Int?`	0–10
`performanceOrientationScore`	`Int?`	0–10
`constraintComplexityScore`	`Int?`	0–10
`archetypeRaw`	`String?`	SegmentationArchetype
Timestamps
`createdAt`	`Date`	Creation
`updatedAt`	`Date?`	Last update
`onboardingCompletedAt`	`Date?`	When onboarding finished; used for onboarding gate
Legacy
`language`	`String`	Default “es”
`goal`	`String?`	“lose”, “maintain”, “gain”
`dietTypeRaw`	`String?`	DietType (DietType enum)
`allergiesData`	`Data?`	[String] (legacy)
`maxPrepTimeMinutes`	`Int?`	Legacy unused (was max prep time preference)
(others)		Placeholders for budget, cuisine, meal timing, etc.

Computed: goalType, unitSystem, currentActivityLevel, goalPace, trackingMode, dietaryPreferences, allergiesAvoids, snackingFrequency, dessertFrequency, estimationMode, supportLevel, archetype, hasCompletedOnboarding (= onboardingCompletedAt != nil), hasMinimumDataForPlanning, bmi, displayWeight, displayHeight, legacy allergies, dietType, etc.

Notes:

Singleton: one profile per app (or per CloudKit user); onboarding gate uses hasCompletedOnboarding.
Created/updated by onboarding and SeedDataService.

FoodItem

File: Models/FoodItem.swift
Type: SwiftData @Model
Purpose: Individual food items for quick-add and scanning.

Field	Type	Description
`id`	`UUID`	Unique identifier
`name`	`String`	Food name (e.g., “Pechuga de pollo”)
`brand`	`String?`	Optional brand name
`servingSize`	`String`	Display serving (e.g., “100g”)
`servingGrams`	`Double`	Serving weight in grams
`calories`	`Int`	Calories per serving
`protein`	`Double`	Protein in grams
`carbs`	`Double`	Carbohydrates in grams
`fat`	`Double`	Fat in grams
`category`	`String`	Raw value of `FoodCategory`
`barcode`	`String?`	Optional barcode for scanning
`createdAt`	`Date`	Creation timestamp

Computed Properties:

foodCategory: FoodCategory - Typed getter/setter for category

FoodCategory Enum:

enum FoodCategory: String {
    case protein = "proteína"
    case carb = "carbohidrato"
    case fat = "grasa"
    case produce = "frutas y verduras"
    case other = "otros"
}

Recipe

File: Models/Recipe.swift
Type: SwiftData @Model
Purpose: Complete recipes with ingredients and preparation steps.

Field	Type	Description
`id`	`UUID`	Unique identifier
`title`	`String`	Recipe name
`mealType`	`String`	Raw value of `MealType`
`imageName`	`String`	Asset image name (placeholder)
`servings`	`Int`	Number of servings
`prepTime`	`Int`	Preparation time in minutes
`calories`	`Int`	Total calories per serving
`protein`	`Double`	Protein per serving
`carbs`	`Double`	Carbs per serving
`fat`	`Double`	Fat per serving
`ingredientsData`	`Data?`	JSON-encoded `[Ingredient]`
`stepsData`	`Data?`	JSON-encoded `[String]`
`createdAt`	`Date`	Creation timestamp
`isFavorite`	`Bool`	User favorite flag

Computed Properties:

mealTypeEnum: MealType - Typed getter/setter
ingredients: [Ingredient] - Decoded from ingredientsData
steps: [String] - Decoded from stepsData

MealType Enum:

enum MealType: String {
    case desayuno = "desayuno"  // Breakfast
    case comida = "comida"       // Lunch
    case cena = "cena"           // Dinner
    case snack = "snack"
    case postre = "postre"       // Dessert
}

Ingredient

File: Models/Ingredient.swift
Type: Codable struct
Purpose: Single ingredient within a recipe.

Field	Type	Description
`id`	`UUID`	Unique identifier
`name`	`String`	Ingredient name
`quantity`	`Double`	Amount
`unit`	`String`	Unit (g, ml, unidad, etc.)
`category`	`String`	Raw value of `FoodCategory`

Computed Properties:

displayQuantity: String - Formatted “2 cucharadas”
foodCategory: FoodCategory - Typed getter/setter

DailyLog

File: Models/DailyLog.swift
Type: SwiftData @Model
Purpose: Daily nutrition tracking log.

Field	Type	Description
`id`	`UUID`	Unique identifier
`date`	`Date`	Day (start of day)
`entriesData`	`Data?`	JSON-encoded `[MealEntry]`

Computed Properties (Aggregated):

entries: [MealEntry] - Decoded meal entries
totalCalories: Int - Sum of all logged calories
totalProtein: Double - Sum of all protein
totalCarbs: Double - Sum of all carbs
totalFat: Double - Sum of all fat

Methods:

getEntry(for mealType: MealType) -> MealEntry?
addItem(_ item: LoggedItem, to mealType: MealType)
removeItem(at index: Int, from mealType: MealType)

Aggregation Logic:

var totalCalories: Int {
    entries.reduce(0) { $0 + $1.totalCalories }
}

Each MealEntry sums its items, and each LoggedItem applies servingsMultiplier.

MealEntry

File: Models/MealEntry.swift
Type: Codable struct
Purpose: Collection of logged items for a specific meal.

Field	Type	Description
`id`	`UUID`	Unique identifier
`mealType`	`String`	Raw value of `MealType`
`items`	`[LoggedItem]`	Logged foods/recipes

Computed Properties:

totalCalories, totalProtein, totalCarbs, totalFat

LoggedItem

File: Models/LoggedItem.swift
Type: Codable struct
Purpose: Single logged food or recipe with serving multiplier.

Field	Type	Description
`id`	`UUID`	Unique identifier
`name`	`String`	Display name
`servingsMultiplier`	`Double`	Portion multiplier (default: 1.0)
`baseCalories`	`Int`	Calories before multiplier
`baseProtein`	`Double`	Protein before multiplier
`baseCarbs`	`Double`	Carbs before multiplier
`baseFat`	`Double`	Fat before multiplier
`isRecipe`	`Bool`	True if from recipe
`sourceId`	`UUID?`	Reference to original FoodItem/Recipe

Computed Properties:

var calories: Int {
    Int(Double(baseCalories) * servingsMultiplier)
}

Factory Methods:

static func from(foodItem: FoodItem, multiplier: Double) -> LoggedItem
static func from(recipe: Recipe, multiplier: Double) -> LoggedItem

WeeklyPlan

File: Models/WeeklyPlan.swift
Type: SwiftData @Model
Purpose: 7-day meal plan for a given week.

Field	Type	Description
`id`	`UUID`	Unique identifier
`weekStartDate`	`Date`	Monday of the week
`daysData`	`Data?`	JSON-encoded `[PlannedDay]`

Computed Properties:

days: [PlannedDay] - 7 days (initialized if empty)

Methods:

setRecipe(_ recipe: PlannedRecipe?, for date: Date, mealType: MealType)
getDay(for date: Date) -> PlannedDay?

PlannedDay

File: Models/PlannedDay.swift
Type: Codable struct
Purpose: Single day within a weekly plan.

Field	Type	Description
`id`	`UUID`	Unique identifier
`date`	`Date`	Day date
`breakfastRecipe`	`PlannedRecipe?`	Assigned breakfast
`lunchRecipe`	`PlannedRecipe?`	Assigned lunch
`dinnerRecipe`	`PlannedRecipe?`	Assigned dinner

Computed Properties:

hasAnyMeal: Bool
totalCalories: Int

PlannedRecipe

File: Models/PlannedDay.swift
Type: Codable struct
Purpose: Lightweight recipe snapshot for planning.

Field	Type	Description
`id`	`UUID`	Snapshot identifier
`recipeId`	`UUID`	Original recipe ID
`title`	`String`	Recipe title
`imageName`	`String`	Image asset
`calories`	`Int`	Calories
`protein`	`Double`	Protein
`carbs`	`Double`	Carbs
`fat`	`Double`	Fat
`ingredients`	`[Ingredient]`	For shopping list

Constructor:

init(from recipe: Recipe) {
    // Copies recipe data into snapshot
}

ShoppingList

File: Models/ShoppingList.swift
Type: SwiftData @Model
Purpose: Shopping list for a week’s ingredients.

Field	Type	Description
`id`	`UUID`	Unique identifier
`weekStartDate`	`Date`	Week this list is for
`itemsData`	`Data?`	JSON-encoded `[ShoppingListItem]`

Computed Properties:

items: [ShoppingListItem]
itemsByCategory: [FoodCategory: [ShoppingListItem]]
uncheckedCount, checkedCount

Methods:

toggleItem(withId: UUID)
addItem(_ item: ShoppingListItem)
removeCheckedItems()

ShoppingListItem

File: Models/ShoppingListItem.swift
Type: Codable struct
Purpose: Single item on shopping list.

Field	Type	Description
`id`	`UUID`	Unique identifier
`name`	`String`	Item name
`quantity`	`Double`	Amount
`unit`	`String`	Unit
`category`	`String`	FoodCategory raw value
`isChecked`	`Bool`	Completion status

WeightEntry

File: Models/WeightEntry.swift
Type: SwiftData @Model
Purpose: Weight log entry (profile weight history).

Field	Type	Description
`id`	`UUID`	Unique identifier
`weight`	`Double`	Weight in kg (base unit)
`date`	`Date`	Day of entry (start of day)
`notes`	`String?`	Optional notes
`createdAt`	`Date`	Creation timestamp

Methods: displayWeight(unitSystem:) returns weight in kg or lb based on UnitSystem.

OnboardingState (Not SwiftData)

File: Models/OnboardingState.swift
Type: Codable struct; persisted in UserDefaults
Purpose: Draft state during onboarding so user can resume if app closes.

Stores: currentScreen, optional screens shown, name, privacy policy accepted, goalType, otherGoalTags, privacyPreference, unitSystem, age, sexEstimation, heightCm, weightKg, activityLevel, trainingDays, goalPace, trackingMode, snackingFrequency, dessertFrequency, dietaryPreferences, allergiesAvoids, confidence, targets review response and adjusted values.
Computed: estimationMode, hasDietaryRestrictions, supportLevel, displayWeight, displayHeight.
Persistence: OnboardingState.load(), save(), clear().

OnboardingTypes (Enums)

File: Models/OnboardingTypes.swift
Purpose: Typed enums for onboarding and profile.

Includes: GoalType, OtherGoalTag, PrivacyPreference, UnitSystem, SexEstimation, ActivityLevel, GoalPace, TrackingMode, DietaryPreference, AllergyType, EstimationMode, SupportLevel, TargetsReviewResponse, SnackingFrequency, DessertFrequency, OnboardingScreen, SegmentationArchetype, ProfileCardType.
Also: CalculatedTargets, SegmentationScores (structs).

AssistantAction (Not SwiftData)

File: Models/AssistantAction.swift
Type: Codable enum
Purpose: Actions the AI assistant can trigger in the app.

Case	Payload	Description
`logMeal`	`LogMealAction`	Log a meal (name, calories, protein, carbs, fat, mealType)
`createRecipe`	`CreateRecipeAction`	Create recipe (title, mealType, servings, prepTime, macros, ingredients, steps)
`generateMealPlan`	`GenerateMealPlanAction`	Generate weekly plan (daysCount, preferences, calorieTarget)
`adjustTarget`	`AdjustTargetAction`	Change target (targetType, newValue)
`viewRecipe`	`String`	Recipe title to open
`viewProgress`	—	Open progress view

Supporting structs: LogMealAction, CreateRecipeAction, GenerateMealPlanAction, AdjustTargetAction.
Parsing: ActionParser.parse(from:) reads a trailing structured CALURU_ACTIONS JSON block (not free-text keywords). Invalid or incomplete actions are dropped so chips only appear for confirmed payloads.

🌱 Seed Data

When Seeding Occurs

SeedDataService.seedIfNeeded(context:) is called in MainTabView.task:

.task {
    SeedDataService.seedIfNeeded(context: modelContext)
}

Seeded Content

Entity	Count	Source
UserProfile	1	Created if none; targets from SeedDataService or onboarding
Recipe	20+	`createRecipes()`
FoodItem	45+	`createFoodItems()`
DailyLog	1	Empty log for today
WeeklyPlan	1	Empty plan for this week
ShoppingList	1	Empty list
WeightEntry	0	User-created only

Recipe Categories

Category	Count	Examples
Desayunos	4	Avena con frutas, Huevos revueltos
Comidas	5	Pollo a la plancha, Ensalada César
Cenas	4	Sopa de verduras, Wrap de pollo
Snacks	4	Yogur griego, Hummus con vegetales
Postres	3	Mousse de chocolate, Chia pudding

Food Item Categories

Category	Count	Examples
Proteínas	10	Pollo, Salmón, Huevo
Carbohidratos	10	Arroz, Pasta, Avena
Grasas	7	Aguacate, Almendras, Aceite
Frutas/Verduras	10	Plátano, Brócoli, Tomate
Otros	5	Leche, Miel, Proteína en polvo

🧮 Computed Totals Logic

Daily Calories Calculation

DailyLog.totalCalories
    └── Sum of MealEntry.totalCalories (for each meal type)
            └── Sum of LoggedItem.calories (for each item)
                    └── baseCalories × servingsMultiplier

Progress Calculation

// In HomeViewModel
var calorieProgress: Double {
    Double(consumedCalories) / Double(targetCalories)
}

Weekly Plan Totals

// In NutritionCalculator
static func calculateWeeklyTotals(from plan: WeeklyPlan) -> NutritionSummary {
    var total = NutritionSummary.zero
    for day in plan.days {
        // Add breakfast + lunch + dinner calories/macros
    }
    return total
}

🔗 Data Relationships

One-to-One

App → UserProfile (singleton)

One-to-Many (via JSON encoding)

DailyLog → MealEntry[] → LoggedItem[]
Recipe → Ingredient[]
WeeklyPlan → PlannedDay[]
ShoppingList → ShoppingListItem[]

Snapshot References

PlannedRecipe stores a copy of Recipe data (not a reference)
LoggedItem stores sourceId but no direct relationship

⚠️ Known Data Considerations

No Cascade Deletes: Deleting a Recipe doesn’t update PlannedDay snapshots
JSON Overhead: Large entry lists may have encoding/decoding overhead
No Migrations: Schema changes require manual migration logic
CloudKit Sync: SwiftData uses CloudKit private database; onboarding gate depends on UserProfile.hasCompletedOnboarding syncing (short delay on reinstall)
OnboardingState: Stored in UserDefaults only; not synced across devices

Architecture Guide
Screens Reference - Onboarding flow and profile screens
Services Reference

Caluru

Caluru - Data Model Reference

📊 Entity Relationship Overview

📋 Model Definitions

UserProfile

FoodItem

Recipe

Ingredient

DailyLog

MealEntry

LoggedItem

WeeklyPlan

PlannedDay

PlannedRecipe

ShoppingList

ShoppingListItem

WeightEntry

OnboardingState (Not SwiftData)

OnboardingTypes (Enums)

AssistantAction (Not SwiftData)

🌱 Seed Data

When Seeding Occurs

Seeded Content

Recipe Categories

Food Item Categories

🧮 Computed Totals Logic

Daily Calories Calculation

Progress Calculation

Weekly Plan Totals

🔗 Data Relationships

One-to-One

One-to-Many (via JSON encoding)

Snapshot References

⚠️ Known Data Considerations

📚 Related Documents