calorie_tracker/QUICK_START.md

# 🚀 Quick Start Guide - Calorie Tracker App

## What You Have

A complete **Flask web application** for tracking calories, macros, water intake, and weight with focus on Filipino foods!

### ✅ Features Implemented

1. **User Authentication** - Register/Login system
2. **Dashboard** - Beautiful overview with cards, charts, and progress bars
3. **Macro Tracking** - Calories, Protein, Carbs, Fat
4. **Filipino Food Database** - 25+ pre-loaded foods (Adobo, Sinigang, Tapsilog, etc.)
5. **Food Search** - Search Filipino and international foods
6. **API Integration** - API Ninjas for 1M+ foods
7. **Water Tracking** - Quick-add buttons (250ml, 500ml)
8. **Weight Tracking** - Daily logs with trends
9. **Smart Suggestions** - AI recommendations based on remaining macros
10. **Charts & Trends** - 7-day calorie and weight trends
11. **Meal Logging** - Add meals with multiple foods
12. **Responsive Design** - Works on mobile and desktop
13. **Filipino Flag Colors** - Red/Blue theme

---

## 🏃 How to Run It

### Option 1: Quick Start (5 minutes)

```bash
# 1. Open terminal in the calorie_tracker_app folder
cd calorie_tracker_app

# 2. Create virtual environment
python -m venv venv

# 3. Activate it
# On Mac/Linux:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

# 4. Install packages
pip install -r requirements.txt

# 5. Run the app
# Windows (Double click run_app.bat OR run):
venv\Scripts\python app.py

# Mac/Linux:
./venv/bin/python app.py
```

## ❓ Troubleshooting

### "pip: command not found"
If you see this error, it means the virtual environment is not activated.
1. Make sure you are in the `calorie_tracker_app` folder.
2. Run `venv\Scripts\activate` (Windows) or `source venv/bin/activate` (Mac/Linux).
3. Try `python -m pip install -r requirements.txt` instead.

### "ModuleNotFoundError"
If Python can't find modules (Flask, etc.), make sure you activated the virtual environment before running the app.

The app will:
- Create the database automatically
- Start on http://localhost:5001

### Option 2: With API Key (Recommended)

```bash
# Do steps 1-4 from above, then:

# 5. Get free API key
# Go to: https://api-ninjas.com/api/nutrition
# Sign up (free)
# Copy your API key

# 6. Create .env file
cp .env.example .env

# 7. Edit .env and add your key
# API_NINJAS_KEY=your_key_here

# 8. Seed Filipino foods
# Windows (Double click seed_db.bat OR run):
venv\Scripts\python seed_data.py

# Mac/Linux:
./venv/bin/python seed_data.py

# 9. Run the app
python app.py
```

---

## 📱 Using the App

### First Time

1. Go to http://localhost:5000
2. Click "Register"
3. Create account (username + password)
4. Login
5. Go to "Goals" page
6. Enter:
   - Age: 25
   - Gender: Male/Female
   - Height: 170 cm
   - Weight: 70 kg
   - Activity: Moderate
   - Goal: Recomp (for weight loss + muscle gain)
   - Target weight: 65 kg
7. Click Save

**The app automatically calculates:**
- Your BMR (Basal Metabolic Rate)
- Your TDEE (Total Daily Energy Expenditure)
- Calorie target (TDEE - 500 for weight loss)
- Macro targets (Protein: 154g, Carbs: 175g, Fat: 63g)

### Daily Use

#### Morning Routine
1. **Log Weight** - Enter on dashboard
2. **Log Water** - Click +250ml or +500ml

#### Adding Meals
1. Click "Add Meal"
2. Select breakfast/lunch/dinner/snack
3. Search for food (e.g., "adobo", "kanin", "sinigang")
4. Click food to add
5. Adjust servings (0.5, 1, 1.5, 2, etc.)
6. See real-time nutrition summary
7. Click "Save Meal"

#### Dashboard Shows
- Calories consumed vs target
- Macros (protein/carbs/fat) with progress bars
- Water intake (glass icons)
- Today's weight
- All meals logged
- Charts showing trends

---

## 🍛 Filipino Foods Available

### Search these (English or Tagalog):

**Breakfast**
- Tapsilog (beef tapa + rice + egg)
- Longsilog (longganisa + rice + egg)
- Tocilog (tocino + rice + egg)

**Main Dishes**
- Chicken Adobo / Adobong Manok
- Pork Sinigang / Sinigang na Baboy
- Chicken Tinola / Tinolang Manok
- Bicol Express
- Sisig
- Menudo
- Kare-Kare
- Lechon Kawali

**Soups**
- Bulalo
- Nilaga

**Vegetables**
- Pinakbet
- Laing
- Ginisang Monggo

**Snacks**
- Pandesal
- Turon
- Bibingka
- Puto
- Lumpia

**Rice**
- White Rice / Kanin
- Fried Rice / Sinangag

---

## 💡 Tips for Success

### Body Recomposition Strategy

**Your goals: Weight loss + Muscle gain**

1. **Protein Priority**
   - Eat 2.2g protein per kg body weight
   - Example: 70kg = 154g protein daily
   - Spread across 4-5 meals

2. **Calorie Deficit**
   - 300-500 calories below TDEE
   - App calculates this automatically
   - Lose 0.5-1 kg per week

3. **Track Daily**
   - Weight: Same time every morning
   - Food: Log everything (even snacks)
   - Water: Aim for 2+ liters

4. **Weekly Check-in**
   - Look at 7-day average weight
   - Adjust calories if needed
   - Progress page shows trends

### Food Search Tips

1. **Try Filipino first** (no API needed):
   - "adobo", "sinigang", "sisig"
   - "kanin", "pandesal", "lumpia"

2. **Search Tagalog names**:
   - Works for Filipino foods
   - "Adobong Manok", "Sinigang na Baboy"

3. **International foods** (needs API):
   - "chicken breast", "brown rice"
   - "protein shake", "banana"

4. **Be specific**:
   - Instead of "lunch", search "chicken rice"
   - Instead of "food", search actual dish

### Maximize Free API Tier

API Ninjas free tier: 50 requests/day

**The app helps you save API calls:**
- Filipino foods = 0 API calls (local database)
- Cached foods = 0 API calls (saved from previous searches)
- Only new international foods use API

**Tips:**
- Use Filipino foods when possible
- Foods are cached after first search
- Mark favorites to find them quickly

---

## 📊 Understanding Your Dashboard

### Calorie Card
- **Green progress bar** = On track
- **Red progress bar** = Over target
- Shows remaining calories

### Protein Card
- Goal: Hit target every day
- Important for muscle building
- Prevents muscle loss during deficit

### Carbs & Fat Cards
- Carbs = Energy for workouts
- Fat = Hormones & satiety
- Both important, don't eliminate

### Water Tracking
- 8 glasses = 2 liters (goal)
- Blue drops fill up
- Quick add: +250ml, +500ml buttons

### Weight Card
- Log daily for best results
- Shows change from yesterday
- Green ⬇ = weight down (good for weight loss)
- Red ⬆ = weight up

### Smart Suggestions
Based on what you've eaten:
- Need protein? → Suggests Tinola, Grilled Fish
- Need carbs? → Suggests Rice, Pandesal
- Need fat? → Suggests Sisig, Bicol Express
- Balanced? → No suggestions (you're good!)

### Charts
- **Calorie Trend**: Shows if you're consistent
- **Weight Trend**: Shows if you're losing weight
- Both use 7-day data

---

## 🔧 Troubleshooting

### "No module named flask"
```bash
pip install -r requirements.txt
```

### "Database is locked"
```bash
# Stop the app, delete database, restart
rm calorie_tracker.db
python app.py
python seed_data.py
```

### Filipino foods not showing
```bash
python seed_data.py
```

### API not working
- Check .env file has API key
- App still works without API (Filipino foods + manual entry)

### Port 5000 in use
Edit app.py, last line:
```python
app.run(debug=True, host='0.0.0.0', port=5001)  # Change to 5001
```

---

## 📁 Project Files

```
calorie_tracker_app/
├── app.py              # Main application (Flask routes)
├── models.py           # Database tables
├── api_client.py       # API integration
├── utils.py            # Helper functions (BMR, TDEE calculations)
├── seed_data.py        # Filipino foods data
├── config.py           # Settings
├── requirements.txt    # Python packages
├── .env.example        # API key template
├── README.md           # Full documentation
└── templates/          # HTML pages
    ├── dashboard.html  # Main page ✅
    ├── add_meal.html   # Add meals ✅
    ├── login.html      # Login page ✅
    ├── register.html   # Register page ✅
    ├── foods.html      # Food database (basic)
    ├── goals.html      # Goals/settings (basic)
    ├── progress.html   # Charts (placeholder)
    └── meal_planner.html # Future feature
```

---

## 🎯 What's Working Now

✅ Full user system (register/login)
✅ Dashboard with all stats
✅ Add meals with multiple foods
✅ Food search (Filipino + API)
✅ Water tracking
✅ Weight tracking
✅ Macro calculations
✅ Smart suggestions
✅ Charts and trends
✅ Responsive design

## 🚧 To Be Enhanced

These are basic but functional:
- Foods page (shows foods, can be enhanced with filters)
- Goals page (works but could be prettier)
- Progress page (placeholder, can add more charts)
- Meal planner (not implemented yet)

---

## 🎉 You're Ready!

### Next Steps:

1. **Run the app** (see instructions above)
2. **Register** an account
3. **Set your goals** (Goals page)
4. **Add your first meal** (try searching "tapsilog"!)
5. **Track for a week** to see trends

### Pro Tip:
Log your meals right after eating. It's easier to remember and takes only 30 seconds!

---

## 📞 Need Help?

1. Check README.md for detailed docs
2. Check this Quick Start guide
3. Look at the code comments
4. All functions are documented

---

**Enjoy tracking your journey to better health! 💪🇵🇭**

Made with ❤️ for Filipino food lovers!