Macro Tracking Feature

Overview

A comprehensive food logging and macro tracking system that allows users to track their daily nutrition intake from multiple sources: USDA database foods, barcode-scanned products, AI-analyzed food photos, and scheduled meal plans.

Core Functionality

1. Food Logging & Tracking

2. Food Search & Discovery

3. Barcode Scanning

4. AI Food Analysis

5. Meal Plan Scheduling

Food Types & Their Differences

| Type | Source | Food ID | Portion Options | Use Case | |------|--------|---------|----------------|----------| | branded | USDA FDC (branded foods) | Database food ID | Multiple predefined portions | Packaged products with barcodes | | foundation_foods | USDA FDC (foundation) | Database food ID | Multiple predefined portions | Basic whole foods (e.g., chicken breast) | | sr_legacy | USDA SR Legacy | Database food ID | Multiple predefined portions | Legacy standard reference foods | | external | Edamam API | Database food ID | API-provided + 100g default | Barcode scanned items not in USDA | | ai-generated | AI image analysis | null | Estimated portions | Photo-analyzed foods | | recipe | Scheduled meal plans | mealPlanDayRecipeId | Serving | Meal plan recipes |

Key Distinctions:

Database Schema

Food (Core food items table)

FoodPortion (Serving size definitions)

UserFoodLog (User's food diary)

ExternalFoodMapping (Barcode tracking)

ScheduledMealPlan (Meal plan scheduling)

ScheduledMealDeletion (Overlap handling)

UserMacroTrackingDay (Day completion)

API Endpoints & File Organization

_macro-tracking+/
├── api.mobile.macro-tracking.food-item/          # Food search
│   ├── food-search.db.server.ts                  # FTS queries
│   ├── food-search.service.server.ts             # Ranking logic
│   └── route.ts
│
├── api.mobile.macro-tracking.barcode/            # Barcode scanning
│   ├── barcode.db.server.ts                      # External food creation
│   ├── barcode.service.server.ts                 # Edamam integration
│   └── route.tsx
│
├── api.mobile.macro-tracking.analyze-image/      # AI analysis
│   ├── analyze-image.service.server.ts           # Gemini AI integration
│   └── route.ts
│
├── api.mobile.macro-tracking.log/                # Create food logs
│   ├── log.db.server.ts                          # Validation queries
│   ├── log.service.server.ts                     # Log creation logic
│   └── route.ts
│
├── api.mobile.macro-tracking.log.$logId/         # Edit/delete logs
│   ├── log-edit.db.server.ts
│   ├── log-edit.service.server.ts
│   └── route.tsx
│
├── api.mobile.macro-tracking.logs/               # Get logs by date
│   ├── logs.db.server.ts                         # Main caching layer
│   └── route.ts
│
├── api.mobile.macro-tracking.suggestions/        # Quick-add suggestions
│   ├── suggestions.db.server.ts
│   ├── suggestions.service.server.ts             # Deduplication
│   └── route.ts
│
├── api.mobile.macro-tracking.day-completion/     # Mark day complete
│   ├── day-completion.db.server.ts
│   ├── day-completion.service.server.ts
│   └── route.ts
│
├── api.mobile.macro-tracking.meal-plan.*/        # Meal plan scheduling
│   ├── schedule/                                 # Create schedule
│   ├── scheduled/                                # Get scheduled meals
│   ├── dates/                                    # Get scheduled dates
│   ├── delete-scheduled/                         # Mark meal as deleted
│   └── previous-recipes/                         # Recipe history
│
├── helpers/
│   └── macro-tracking-types.ts                   # Zod schemas & types
│
├── macro-tracking-cache-keys.ts                  # Centralized cache keys
├── macro-tracking.service.server.ts              # Shared utilities
└── CACHING-STRATEGY.md                           # Caching documentation

Caching Strategy

Two-Tier System

  1. Redis (via Cachified) - High-frequency data

  2. Prisma Accelerate - Stable data

Invalidation Patterns

Key Benefits

See CACHING-STRATEGY.md for detailed documentation.

Type Safety

All data flows through Zod schemas:

Example:

export const loggedFoodItemSchema = z.discriminatedUnion("type", [
  foodLogEntrySchema,        // Database foods
  recipeLogEntrySchema,      // Recipes
  aiGeneratedLogEntrySchema, // AI items
]);

User Flows

1. Search & Log Flow

  1. User searches for "chicken breast"
  2. FTS query returns ranked results
  3. User selects food and portion
  4. Log created with denormalized macros
  5. Redis cache invalidated for that date

2. Barcode Scan Flow

  1. User scans barcode
  2. Check ExternalFoodMapping for existing item
  3. If not found, fetch from Edamam API
  4. Create Food + FoodPortion + ExternalFoodMapping
  5. Return food item for logging

3. AI Analysis Flow

  1. User uploads food photo
  2. Gemini identifies food name (2.0 Flash)
  3. Gemini estimates macros per component (2.5 Flash)
  4. Returns array of ai-generated food items
  5. User can log items individually or as group

4. Meal Plan Schedule Flow

  1. User schedules meal plan for date range
  2. System checks for overlaps
  3. Creates ScheduledMealPlan entry
  4. Generates ScheduledMealDeletion for conflicts
  5. User sees scheduled meals in suggestions

Testing Notes

Related Documentation