first commit
This commit is contained in:
Jp
397
QUICK_START.md
Normal file
397
QUICK_START.md
Normal file
@@ -0,0 +1,397 @@
|
||||
# 🚀 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!
|
||||
Reference in New Issue
Block a user