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

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

### FoodItem (normalised DB)

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

### MealEntry

```json
{
  "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)

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

### UserFoodMemory (personalisation layer)

```json
{
  "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:
```json
{
  "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:
```json
{
  "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%)?