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)

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

# 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"

pip install -r requirements.txt

"Database is locked"

# Stop the app, delete database, restart
rm calorie_tracker.db
python app.py
python seed_data.py

Filipino foods not showing

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:

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!