calorie-counter/idea/mvpDataStructAndWorkflows.md

Perfect — this is exactly the kind of product where a **clean MVP design = 80% of success**.

I’ll give you **copy‑paste ready PRD, data model, APIs, and UI flows** — structured so you could literally start building (or drop into Notion / repo).

***

# 🧾 1. MVP PRD (Feature Set)

## 🎯 Product Vision

> “The easiest way to track calories with minimal effort and acceptable accuracy using AI + smart defaults.”

***

## 👤 Target User

* Busy professionals (like you 😄)
* Eat mixed: home + restaurant + packaged food
* Want **low friction**, not perfect precision

***

## ✅ MVP Scope (STRICT — avoid scope creep)

### Core Features

### 1. Meal Logging (3 methods)

#### ✅ A. Quick Add (manual)

* Search food
* Select portion (grams / default servings)
* Add to day

#### ✅ B. Barcode scan

* Scan product → auto-fill nutrition

#### ✅ C. Photo (AI assist, NOT full auto)

* Take picture
* App suggests:
  * detected food(s)
  * estimated portions
* User must confirm/edit

👉 Important: **User confirmation required (trust + accuracy)**

***

### 2. Daily Tracking

* Calories consumed (main KPI)
* Optional:
  * protein / carbs / fat
* Remaining calories (based on goal)

***

### 3. User Profile

* Age, weight, height
* Goal:
  * lose / maintain / gain
* Daily calorie target (calculated)

(BMR-based baseline — like MyFitnessPal approach)

***

### 4. History & Reuse

* Recent foods
* Repeat last meal (1 tap)

***

### 5. Correction Loop (THIS IS YOUR SECRET WEAPON)

* User edits AI result
* Store correction
* Improve next suggestions

***

## ❌ NOT in MVP (important discipline)

* No social features
* No meal plans
* No wearable integrations
* No deep health analytics

***

# 🧠 2. Data Model (clean + scalable)

Use something like **Postgres (or Firestore if you go fast)**.

***

## Core Entities

### User

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

***

### FoodItem (normalized DB)

```json
{
  "id": "uuid",
  "name": "Chicken breast",
  "source": "openfoodfacts|custom|ai",
  "caloriesPer100g": 165,
  "macros": {
    "protein": 31,
    "fat": 3.6,
    "carbs": 0
  }
}
```

***

### MealEntry

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

***

### PhotoAnalysis (AI trace — VERY IMPORTANT)

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

***

### UserFoodMemory (optimization layer)

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

👉 This enables:

* auto-fill frequent meals
* personalization

***

# 🔌 3. API Design (clean + realistic)

Assume REST (simple for MVP)

***

## Auth

```
POST /auth/register
POST /auth/login
```

***

## User

```
GET /user/profile
PUT /user/profile
```

***

## Food Search

```
GET /foods?query=chicken
```

Response:

```json
[
  {
    "id": "uuid",
    "name": "Chicken breast",
    "caloriesPer100g": 165
  }
]
```

***

## Barcode

```
GET /foods/barcode/{code}
```

***

## Meal Logging

```
POST /meals
```

```json
{
  "date": "2026-05-16",
  "items": [
    {
      "foodItemId": "uuid",
      "grams": 200
    }
  ],
  "source": "manual"
}
```

***

## Daily Overview

```
GET /meals/daily?date=2026-05-16
```

Response:

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

***

## Photo Analysis (AI entry point)

```
POST /ai/analyze-meal
```

Request:

* image

Response:

```json
{
  "suggestions": [
    {
      "name": "pasta",
      "grams": 250,
      "confidence": 0.78
    }
  ]
}
```

***

## Feedback Loop

```
POST /ai/correction
```

```json
{
  "analysisId": "uuid",
  "corrections": [...]
}
```

***

# 📱 4. UI Flows (VERY IMPORTANT — UX is everything)

I’ll give you **clear flows you can directly translate into screens**

***

## 🏠 Home Screen (Daily Dashboard)

```
------------------------------------
Calories: 1800 / 2200
Remaining: 400

[ + Add Meal ]

Today:
- Breakfast (450 kcal)
- Lunch (800 kcal)
- Dinner (550 kcal)
------------------------------------
```

***

## ➕ Add Meal (entry selector)

```
Choose how to log:

[ 📷 Take Photo ]
[ 🔍 Search Food ]
[ 📦 Scan Barcode ]
```

👉 Always start here — reduces friction.

***

## 📷 Photo Flow

### Step 1 — Capture

```
[ Camera View ]
[ Snap ]
```

***

### Step 2 — AI Suggestion (critical UX moment)

```
We detected:

- Rice (150g)
- Chicken (120g)

[ Edit ]   [ Confirm ]
```

***

### Step 3 — Edit

```
Rice: 150g → [ adjust slider ]
Chicken: 120g → [ adjust ]
[ + Add item ]

[ Save Meal ]
```

***

## 🔍 Manual Search Flow

```
Search: "chicken"

Results:
- Chicken breast
- Chicken thigh

→ Select
→ Choose grams
→ Add
```

***

## 📊 Daily Details Screen

```
Total: 1800 kcal

Macros:
Protein: 120g
Carbs: 180g
Fat: 60g

Meals:
- Breakfast
- Lunch
- Dinner
```

***

## 🔁 Repeat Meal (killer UX shortcut)

On Home:

```
[ Repeat yesterday's lunch ]
```

***

# 🎯 5. Architecture Decisions (important for you)

Given your background:

### Backend

* FastAPI or Spring Boot (you’re Java → maybe Spring Boot)

### Frontend

* React Native (fast MVP)

### AI

* Start with API-based (no custom model)
* Later optimize

***

# 🚀 6. What makes YOUR app better (MVP differentiation)

Focus on:

✅ Minimal friction  
✅ Smart defaults  
✅ Learning user habits

NOT:
❌ Better AI model  
❌ More features

***

# ✅ Next logical step

If you want, I can next:

👉 Turn this into **actual repo structure + starter code (backend + mobile)**  
👉 Or design **clickable UI wireframes (Figma-style)**

Just tell me which direction 👍