feat: initial implementation — all 35 requirements across phases 1-3
Backend (Spring Boot 3.2 / Java 21 / PostgreSQL): - JWT auth with BCrypt password hashing - User profile + Mifflin-St Jeor BMR calculator - Food search + barcode via OpenFoodFacts API with local cache - Meal CRUD with user data isolation and ownership checks - AI photo analysis (OpenAI Vision) with confidence intervals - AI correction feedback loop for personalisation - Flyway DB migrations + RFC-7807 error responses Mobile (React Native / TypeScript): - Full navigation stack (Auth → Tabs → Home stack) - Design tokens (WCAG 2.2 AA colours, 8px grid, 48px touch targets) - 10 screens: Login, Register, Home, Search, Camera, AI Result, Edit Meal, Daily Details, History, Profile - Confidence-aware calorie display (kcal ± range) - Repeat last meal shortcut + macro tracking Docs: - docs/PLAN-AND-REQUIREMENTS.md - docs/traceability.csv (35 requirements, all Implemented)
This commit is contained in:
337
docs/PLAN-AND-REQUIREMENTS.md
Normal file
337
docs/PLAN-AND-REQUIREMENTS.md
Normal file
@@ -0,0 +1,337 @@
|
||||
# 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%)?
|
||||
Reference in New Issue
Block a user