# 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%)?