calorie-counter/docs/PLAN-AND-REQUIREMENTS.md

Calorie Counter App — Plan & Requirements

Version: 1.0
Date: 2026-05-18
Status: Draft — awaiting review

---

1. Product Vision

"The easiest way to track calories with minimal effort and acceptable accuracy, using AI + smart defaults."

Core principle: Consistent estimation beats absolute precision. Users should trust the app enough to use it daily — not abandon it because it demands too much.

KPI: Log a meal in under 10 seconds.

---

2. Target Users

Primary: Busy professionals who eat a mix of home-cooked, restaurant, and packaged food. They want low friction, not lab-grade accuracy.

---

3. MVP Feature Scope

IN scope

Feature	Description
Manual food search	Search food DB, select portion, add to day
Barcode scan	Scan product → auto-fill nutrition
Photo logging (AI assist)	Snap photo → AI suggests items + portions → user confirms/edits
Daily calorie tracking	Consumed vs. target, remaining calories
Macro tracking	Protein / carbs / fat (optional display)
User profile	Age, weight, height, goal → auto-calculated daily target (BMR)
History view	Calorie totals per day
Repeat last meal	One-tap shortcut on home screen
AI correction loop	User edits AI result → stored to improve future suggestions

OUT of scope (MVP)

• Social features
• Meal plans
• Wearable integrations
• Deep health analytics
• Custom ML model training

---

4. Differentiation Strategy

Three features that separate this from MyFitnessPal etc:

1. Confidence-aware calories — show 500 kcal ± 80 kcal (confidence 85%) instead of a false-precision single number
2. Personal food memory — app learns your typical portions, pre-fills next time
3. AI correction loop — every manual correction improves future suggestions, building a personalised model layer over time

---

5. Technical Architecture

Stack decision

Layer	Technology
Mobile	React Native
Backend	Spring Boot (Java)
Database	PostgreSQL
Food DB	Open Food Facts API (free, open)
AI service	OpenAI Vision API (MVP) → custom fine-tuned model (later)
Auth	JWT-based auth

Architecture diagram

Mobile App (React Native)
        │
   REST API
        │
   Backend (Spring Boot / FastAPI)
        │
   ┌────────────────────────────────┐
   │ Food DB (OpenFoodFacts cache)  │
   │ AI Service (Vision API)        │
   │ User Data (Postgres)           │
   └────────────────────────────────┘

Key design decision: Cache food DB locally for performance. Normalize all food entries to a common schema regardless of source (OpenFoodFacts / barcode / AI / manual).

---

6. Data Model

User

{
  "id": "uuid",
  "email": "string",
  "createdAt": "timestamp",
  "profile": {
    "age": 30,
    "weightKg": 80,
    "heightCm": 180,
    "goal": "lose | maintain | gain",
    "dailyCaloriesTarget": 2200
  }
}

FoodItem (normalised DB)

{
  "id": "uuid",
  "name": "Chicken breast",
  "source": "openfoodfacts | custom | ai",
  "caloriesPer100g": 165,
  "macros": {
    "proteinG": 31,
    "fatG": 3.6,
    "carbsG": 0
  }
}

MealEntry

{
  "id": "uuid",
  "userId": "uuid",
  "date": "2026-05-16",
  "mealType": "breakfast | lunch | dinner | snack",
  "items": [
    {
      "foodItemId": "uuid",
      "quantityGrams": 200,
      "calories": 330
    }
  ],
  "source": "manual | barcode | photo",
  "confidence": 0.82
}

PhotoAnalysis (AI audit trail)

{
  "id": "uuid",
  "userId": "uuid",
  "imageUrl": "string",
  "detectedItems": [
    { "name": "rice", "estimatedGrams": 150, "confidence": 0.76 }
  ],
  "userCorrections": [
    { "name": "rice", "correctedGrams": 180 }
  ]
}

UserFoodMemory (personalisation layer)

{
  "userId": "uuid",
  "foodName": "coffee with milk",
  "avgPortionGrams": 250,
  "lastUsed": "timestamp"
}

---

7. API Design

Auth

POST /auth/register
POST /auth/login

User

GET  /user/profile
PUT  /user/profile

Food

GET  /foods?query=chicken
GET  /foods/barcode/{code}

Meals

POST /meals
GET  /meals/daily?date=YYYY-MM-DD
GET  /meals/{id}
PUT  /meals/{id}
DELETE /meals/{id}

GET /meals/daily response:

{
  "totalCalories": 1800,
  "target": 2200,
  "remaining": 400,
  "meals": [...]
}

AI

POST /ai/analyze-meal       ← multipart image upload
POST /ai/correction         ← submit user correction

POST /ai/analyze-meal response:

{
  "analysisId": "uuid",
  "suggestions": [
    { "name": "pasta", "grams": 250, "confidence": 0.78 }
  ]
}

---

8. UI / UX Requirements

Screen map

Bottom Nav:  [ Home ]  [ History ]  [ Profile ]
FAB:         [ + Add Meal ]  (accessible from Home)

Screens

Screen	Key elements
Home	Calorie progress card, meal list (Breakfast/Lunch/Dinner), repeat shortcut, FAB
Add Meal (bottom sheet)	Photo / Search / Barcode options
Camera	Full-screen preview, capture button
AI Result	Detected items with portions + confidence %, Edit and Confirm CTAs
Edit Meal	Per-item sliders (0–500g), real-time calorie total, Save button
Manual Search	Search input, results list with kcal/100g, portion selector
Daily Details	Calorie total, macro breakdown, meal list
History	Per-day calorie totals (scrollable list)
Profile	Weight / height / goal / daily target, Edit button

Critical UX rules (non-negotiable)

1. Always require user confirmation before saving AI-detected meals — never auto-save
2. 1-tap access to Add Meal from Home screen
3. Sliders over number inputs for portion adjustment — faster, fewer errors
4. Calories update in real-time while adjusting portions
5. Confidence score visible on AI suggestions (supports honest accuracy framing)

Accessibility

• All interactive elements keyboard/touch accessible
• Minimum touch target 48×48px
• Contrast ratio ≥ 4.5:1 (WCAG 2.2 AA)
• alt text on all food images / icons

---

9. Design System (summary)

Colours

Token	Value
Primary/Green	#22C55E
Primary/Dark	#16A34A
Error/Red	#EF4444
Warning/Yellow	#F59E0B
Gray/900 (text)	#0F172A
Background	#FFFFFF
Background/Muted	#F8FAFC

Typography (Inter / SF Pro)

• Heading/Large: 24px SemiBold
• Body/Large: 16px Regular
• Caption: 12px Regular
• Number/Kcal: 28px Bold

Spacing: 8px grid (4 / 8 / 16 / 24 / 32 / 48px)

Key components

Button, MealItemRow, FoodRow, CalorieCard, AISuggestionCard, PortionSlider, ProgressBar, FAB

---

10. Phased Delivery Plan

Phase 1 — Core MVP (2–3 weeks)

• User auth (register / login)
• User profile + BMR-based calorie target
• Food search (OpenFoodFacts API)
• Manual meal logging
• Barcode scan → auto-fill
• Daily calorie dashboard
• Meal history

Phase 2 — AI Layer

• Photo capture screen
• OpenAI Vision API integration (/ai/analyze-meal)
• AI result confirmation screen
• Per-item portion sliders (Edit Meal screen)
• AI correction storage

Phase 3 — Intelligence + Polish

• Confidence-aware display (kcal ± range)
• UserFoodMemory — personalised portion defaults
• "Repeat last meal" shortcut
• Macro tracking display (protein/carbs/fat)
• Fine-tune AI suggestions based on user corrections

---

11. Open Questions (to resolve before development)

1. Backend language: Spring Boot (Java — familiar) or FastAPI (Python — easier AI integration)?
2. Auth provider: Self-managed JWT, Firebase Auth, or Auth0?
3. Database: Postgres (more control) or Firestore (faster to start)?
4. Image storage: Firebase Storage or S3 for photo uploads?
5. AI provider: OpenAI Vision API only, or also evaluate Google Vision / custom model from day 1?
6. Platforms: iOS only, Android only, or both from day 1?
7. Confidence display: Show to users always, or only when below a threshold (e.g. < 80%)?