Core Concepts

Households

A household is the top-level entity in OvenLovin. It represents a family or group of people who share meals. Households are implemented as Clerk Organizations, providing:

• Multi-user access control
• Role-based permissions (admin, member)
• Invitation and member management

Each household can have:

• Multiple people with dietary rules
• A library of recipes
• Meal plans
• Shopping lists

People

People are members of a household. Each person can have:

• Name and basic profile information
• Age (for age-appropriate meal suggestions)
• Activity level (affects nutritional recommendations)
• Dietary rules with severity levels

Example People

All ids are UUIDs.

{
  id: "6f1c2a90-8d3e-4b7a-9c12-0e4f5a6b7c8d",
  householdId: "550e8400-e29b-41d4-a716-446655440002",
  displayName: "Parent A",
  rules: [
    {
      kind: "allergen",
      target: "peanut",
      severity: "block",
      note: "Severe peanut allergy"
    }
  ]
}

Dietary Rules

Dietary rules are per-person configurations that define allergies, restrictions, and preferences. Each rule has:

Rule Kinds

Note: All rules are per-person and configured by the family admin. OvenLovin never hard-codes allergen policies.

• allergen - Food allergies (peanut, tree_nut, milk, egg, fish, shellfish, wheat, soy, sesame)
• ingredient - Specific ingredient restrictions (garlic, onions, nightshades)
• ingredient_category - A category of ingredients
• diet - Dietary patterns (vegetarian, vegan, pescatarian, gluten_free, dairy_free)
• tag - A labeled tag (for example spicy)
• custom - A household-defined rule

Severity Levels

Each rule has a severity level that determines how strictly it's enforced:

Shared Facility Setting

Rules can include a sharedFacility flag to warn about products processed in facilities that also handle allergens:

{
  kind: "allergen",
  target: "peanut",
  severity: "warn",
  sharedFacility: "warn",
  note: "Warn if processed in a facility with peanuts"
}

Recipes

When you create a recipe, send each ingredient as { "rawText": "2 cups broccoli" }. The API parses it into name, quantity and unit.

Recipes are the building blocks of meal plans. Each recipe includes:

• Basic info - Title, description, source URL
• Ingredients - List with quantities and units
• Instructions - Step-by-step directions
• Nutrition - Calories, macros, vitamins (from USDA FoodData Central)
• Metadata - Servings, prep time, cook time, cuisine, dietary tags

Recipe Import

OvenLovin supports multiple import methods:

• URL Import - Import from recipe websites with AI-powered extraction
• Photo/OCR - Take a photo of a recipe card or cookbook page
• Voice Input - Dictate a recipe to your AI agent
• Paste/Text - Copy and paste recipe text from any source

Example Recipe

{
  "id": "49e5fbdd-b252-4638-a1b4-e3a5cba25c46",
  "title": "Chocolate Chip Cookies",
  "ingredients": [
    { "rawText": "2.5 cups all-purpose flour" },
    { "rawText": "1 cup butter" },
    { "rawText": "2 cups chocolate chips" }
  ]
}

Meal Plans

A meal plan organizes recipes into a schedule with attendees and rule checking. Each meal plan includes:

• Date range - Start and end dates
• Meals - Breakfast, lunch, dinner, snacks for each day
• Attendees - Which household members will eat each meal
• Rule check results - Per-person findings with severity

Meal Plan Checking

Warning: Safety-critical: Rule checking is deterministic for the same inputs (recipe, attendees, rules) and always names the affected person.

When you check a meal plan, OvenLovin:

1. Loads all recipes in the plan
2. Loads all attendees and their dietary rules
3. Checks each recipe against each attendee's rules
4. Returns per-person findings with severity

Check Status

• complete - All checks passed successfully
• incomplete - Checking could not complete (reasons provided)
• Never returns "no issues" when checking cannot complete

Example Findings

{
  "status": "complete",
  "byEntry": [
    {
      "entryId": "7c2a9d14-5e8b-4f01-a3c6-8b0d1e2f4a5c",
      "date": "2026-10-12",
      "mealSlot": "dinner",
      "recipeTitle": "Peanut Butter Cookies",
      "findings": {
        "block": [
          {
            "personId": "6f1c2a90-8d3e-4b7a-9c12-0e4f5a6b7c8d",
            "personName": "Parent A",
            "severity": "block",
            "ingredientName": "peanut butter",
            "message": "Contains peanuts (peanut butter), so Parent A can't eat this"
          }
        ],
        "warn": [],
        "prefer_avoid": []
      },
      "affectedPeople": ["6f1c2a90-8d3e-4b7a-9c12-0e4f5a6b7c8d"]
    }
  ],
  "byPerson": [
    {
      "personId": "6f1c2a90-8d3e-4b7a-9c12-0e4f5a6b7c8d",
      "personName": "Parent A",
      "findings": {
        "block": [
          {
            "personId": "6f1c2a90-8d3e-4b7a-9c12-0e4f5a6b7c8d",
            "personName": "Parent A",
            "severity": "block",
            "ingredientName": "peanut butter",
            "message": "Contains peanuts (peanut butter), so Parent A can't eat this"
          }
        ],
        "warn": [],
        "prefer_avoid": []
      },
      "affectedEntries": ["7c2a9d14-5e8b-4f01-a3c6-8b0d1e2f4a5c"]
    }
  ],
  "summary": {
    "totalEntries": 1,
    "totalPeople": 1,
    "entriesWithBlocks": 1,
    "entriesWithWarnings": 0,
    "entriesWithPreferAvoid": 0,
    "peopleWithBlocks": 1,
    "peopleWithWarnings": 0,
    "peopleWithPreferAvoid": 0
  }
}

Shopping Lists

Shopping lists aggregate ingredients from a meal plan and organize them by grocery store section. Each shopping list includes:

• Aggregated quantities - Combined amounts for the same ingredient
• Unit conversions - Standardized units (metric/US)
• Allergen warnings - Flagged ingredients based on dietary rules
• Store sections - Produce, dairy, meat, pantry, frozen, etc.

Example Shopping List

{
  "mealPlanId": "2d8f1a6b-5c4e-4a91-9c0e-7c2a1e8f4b3d",
  "weekStart": "2026-10-12",
  "groupBy": "aisle",
  "includeStaples": false,
  "includePantryItems": false,
  "itemCount": 2,
  "ingredients": [
    {
      "key": "all-purpose-flour",
      "name": "all-purpose flour",
      "quantity": 5,
      "unit": "cups",
      "aisle": "Pantry",
      "recipes": []
    },
    {
      "key": "peanut-butter",
      "name": "peanut butter",
      "quantity": 2,
      "unit": "cups",
      "aisle": "Pantry",
      "recipes": []
    }
  ],
  "sections": [
    {
      "name": "Pantry",
      "items": [
        {
          "key": "all-purpose-flour",
          "name": "all-purpose flour",
          "quantity": 5,
          "unit": "cups"
        },
        {
          "key": "peanut-butter",
          "name": "peanut butter",
          "quantity": 2,
          "unit": "cups"
        }
      ]
    }
  ],
  "warnings": [
    {
      "ingredient": "peanut butter",
      "personName": "Parent A",
      "note": "Contains peanuts (peanut butter), so Parent A can't eat this"
    }
  ]
}

Safety Invariants

Critical: These invariants are safety-critical and must never be broken:

1. Rule checking is deterministic for the same inputs (recipe, attendees, rules)
2. Warnings name the affected person and are returned in every relevant API response
3. Recipe edits or rule changes mark affected plans as needs_recheck
4. Incomplete checks are reported as status: incomplete, never "no issues"
5. No hard-coded allergen policies - all rules are per-person config set by the family admin

Next Steps

• Connect Your Agent - Set up Grok Bot, ChatGPT, or Claude Desktop
• API Reference - Explore the REST API and MCP tools