385 lines
8.7 KiB
Markdown
385 lines
8.7 KiB
Markdown
# Calorie Tracker - Filipino Food Edition 🍽️
|
|
|
|
A web application for tracking calories, macros, and water intake with special focus on Filipino foods. Perfect for weight loss and muscle gain goals!
|
|
|
|
## Features
|
|
|
|
✅ **Macro Tracking**: Track calories, protein, carbs, and fat
|
|
✅ **Filipino Food Database**: Pre-loaded with 25+ common Filipino foods
|
|
✅ **Water Intake Tracking**: Quick-add water logging
|
|
✅ **Weight Tracking**: Daily weight logs with trend analysis
|
|
✅ **Meal Planning**: Plan meals ahead (coming soon!)
|
|
✅ **Smart Suggestions**: Get food recommendations based on remaining macros
|
|
✅ **API Integration**: Search international foods via API Ninjas
|
|
✅ **Beautiful UI**: Red/blue color scheme inspired by Filipino flag
|
|
✅ **Charts & Trends**: Visualize your progress with Chart.js
|
|
|
|
## Filipino Foods Included
|
|
|
|
- **Kanin (Rice)**: White rice, Sinangag
|
|
- **Ulam (Main Dishes)**: Adobo, Sinigang, Sisig, Bicol Express, Kare-kare, Menudo, Lechon Kawali
|
|
- **Sabaw (Soups)**: Tinola, Nilaga, Bulalo
|
|
- **Gulay (Vegetables)**: Pinakbet, Laing, Ginisang Monggo
|
|
- **Almusal (Breakfast)**: Tapsilog, Longsilog, Tocilog
|
|
- **Meryenda (Snacks)**: Pandesal, Turon, Bibingka, Puto, Lumpia
|
|
|
|
## 🐳 Docker Support
|
|
|
|
Want to self-host this on CasaOS or your own server?
|
|
👉 **[Read the Docker Guide](../README_DOCKER.md)**
|
|
|
|
## Tech Stack
|
|
|
|
|
|
- **Backend**: Flask (Python)
|
|
- **Database**: SQLite
|
|
- **Frontend**: HTML, Tailwind CSS, Vanilla JavaScript
|
|
- **Charts**: Chart.js
|
|
- **API**: API Ninjas Nutrition API
|
|
|
|
## Installation
|
|
|
|
### Prerequisites
|
|
|
|
- Python 3.10 or higher
|
|
- pip (Python package manager)
|
|
|
|
### Step 1: Clone or Download
|
|
|
|
```bash
|
|
cd calorie_tracker_app
|
|
```
|
|
|
|
### Step 2: Create Virtual Environment
|
|
|
|
```bash
|
|
python -m venv venv
|
|
|
|
# On Windows:
|
|
venv\Scripts\activate
|
|
|
|
# On Mac/Linux:
|
|
source venv/bin/activate
|
|
```
|
|
|
|
### Step 3: Install Dependencies
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### Step 4: Get API Key (Optional but Recommended)
|
|
|
|
1. Go to [API Ninjas](https://api-ninjas.com/api/nutrition)
|
|
2. Sign up for a free account
|
|
3. Get your API key (50 requests/day free tier)
|
|
4. Create `.env` file:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Edit `.env` and add your API key:
|
|
```
|
|
API_NINJAS_KEY=your_api_key_here
|
|
SECRET_KEY=your_secret_key_here
|
|
```
|
|
|
|
### Step 5: Initialize Database
|
|
|
|
Run the app for the first time:
|
|
|
|
```bash
|
|
# Windows (Double click run_app.bat OR run):
|
|
venv\Scripts\python app.py
|
|
|
|
# Mac/Linux:
|
|
./venv/bin/python app.py
|
|
```
|
|
|
|
This will create the database. Then in another terminal, seed Filipino foods:
|
|
|
|
```bash
|
|
# Windows (Double click seed_db.bat OR run):
|
|
venv\Scripts\python seed_data.py
|
|
|
|
# Mac/Linux:
|
|
./venv/bin/python seed_data.py
|
|
```
|
|
|
|
### Step 6: Run the Application
|
|
|
|
```bash
|
|
# Windows (Double click run_app.bat OR run):
|
|
venv\Scripts\python app.py
|
|
|
|
# Mac/Linux:
|
|
./venv/bin/python app.py
|
|
```
|
|
|
|
Open your browser and go to: `http://localhost:5001`
|
|
|
|
## Usage
|
|
|
|
### First Time Setup
|
|
|
|
1. **Register**: Create an account at `/register`
|
|
2. **Login**: Sign in with your credentials
|
|
3. **Set Goals**: Go to Goals page and enter:
|
|
- Age, gender, height, weight
|
|
- Activity level
|
|
- Goal type (weight loss, muscle gain, or recomp)
|
|
- Target weight
|
|
|
|
The app will automatically calculate your:
|
|
- BMR (Basal Metabolic Rate)
|
|
- TDEE (Total Daily Energy Expenditure)
|
|
- Calorie target
|
|
- Macro targets
|
|
|
|
### Daily Tracking
|
|
|
|
#### Add a Meal
|
|
1. Click "Add Meal" button
|
|
2. Select date, meal type, and time
|
|
3. Search for foods (Filipino or international)
|
|
4. Add foods and adjust servings
|
|
5. See real-time nutrition summary
|
|
6. Save meal
|
|
|
|
#### Log Water
|
|
- Quick buttons on dashboard: +250ml, +500ml
|
|
- Or use custom amount
|
|
|
|
#### Log Weight
|
|
- Enter weight on dashboard
|
|
- Track daily to see trends
|
|
|
|
### Food Search
|
|
|
|
The app searches in this order:
|
|
1. **Filipino foods** (local database) - fastest
|
|
2. **Cached foods** (previously searched)
|
|
3. **API Ninjas** (if API key configured)
|
|
4. **Manual entry** (if food not found)
|
|
|
|
Search supports both English and Tagalog:
|
|
- "Adobo" or "Chicken Adobo"
|
|
- "Kanin" or "Rice"
|
|
- "Sinigang" works
|
|
|
|
### Understanding the Dashboard
|
|
|
|
#### Top Cards
|
|
- **Calories**: Shows consumed vs target with progress bar
|
|
- **Protein**: Your protein intake vs target
|
|
- **Carbs & Fat**: Dual progress bars
|
|
- **Water & Weight**: Quick water logging + today's weight
|
|
|
|
#### Macro Distribution
|
|
- Pie chart showing protein/carbs/fat percentages
|
|
- Ideal for recomp: 30-35% protein, 40-45% carbs, 20-25% fat
|
|
|
|
#### Smart Suggestions
|
|
Based on remaining macros, suggests:
|
|
- High protein foods if protein is low
|
|
- Carb sources if carbs are low
|
|
- Balanced meals if everything is balanced
|
|
|
|
#### Today's Meals
|
|
- Shows all logged meals
|
|
- Color-coded by meal type
|
|
- Displays nutrition breakdown
|
|
|
|
#### Weekly Trends
|
|
- 7-day calorie trend vs target
|
|
- 7-day weight trend
|
|
|
|
## Database Schema
|
|
|
|
### Tables
|
|
- `users` - User accounts
|
|
- `food_items` - All foods (Filipino + API)
|
|
- `meals` - Meal entries
|
|
- `meal_foods` - Foods in each meal
|
|
- `water_logs` - Water intake
|
|
- `weight_logs` - Weight tracking
|
|
- `meal_plans` - Future meal planning
|
|
- `user_goals` - Macro targets
|
|
- `daily_summary` - Daily totals
|
|
- `api_cache` - API response caching
|
|
|
|
## API Rate Limits
|
|
|
|
**Free Tier (API Ninjas)**:
|
|
- 50 requests per day
|
|
- App caches all results
|
|
- Once cached, no API calls needed
|
|
|
|
**Tips to conserve API calls**:
|
|
- Use Filipino foods when possible (no API calls)
|
|
- Search once, use favorites
|
|
- API searches are cached for 30 days
|
|
|
|
## Customization
|
|
|
|
### Adding Custom Foods
|
|
|
|
1. Go to Foods page
|
|
2. Click "Add Custom Food"
|
|
3. Enter nutrition information
|
|
4. Save
|
|
|
|
### Adjusting Targets
|
|
|
|
Go to Goals page to adjust:
|
|
- Daily calorie target
|
|
- Macro targets (protein/carbs/fat)
|
|
- Water intake goal
|
|
- Weight goal
|
|
|
|
### Meal Templates (Coming Soon!)
|
|
|
|
Save common meal combinations:
|
|
- "My typical breakfast"
|
|
- "Post-workout meal"
|
|
- "Quick lunch"
|
|
|
|
## Tips for Body Recomposition
|
|
|
|
### Protein Priority
|
|
- 2.0-2.4g per kg body weight
|
|
- Example: 70kg person = 140-168g daily
|
|
- Spread across all meals
|
|
|
|
### Carb Timing
|
|
- Higher carbs on training days
|
|
- Lower carbs on rest days
|
|
|
|
### Calorie Cycling
|
|
- Training days: Maintenance (+100 cal)
|
|
- Rest days: Deficit (-300 to -500 cal)
|
|
|
|
### Track Weight Daily
|
|
- Weigh same time each day (morning, after bathroom)
|
|
- Look at weekly average, not daily fluctuations
|
|
- Aim for 0.5-1% body weight loss per week
|
|
|
|
## Troubleshooting
|
|
|
|
### Database Locked Error
|
|
```bash
|
|
# Stop the app, then:
|
|
rm calorie_tracker.db
|
|
python app.py
|
|
python seed_data.py
|
|
```
|
|
|
|
### API Not Working
|
|
- Check if API key is in `.env` file
|
|
- Verify API key is valid
|
|
- App works without API (Filipino foods + manual entry)
|
|
|
|
### Foods Not Showing
|
|
```bash
|
|
python seed_data.py
|
|
```
|
|
|
|
### Port Already in Use
|
|
```bash
|
|
# Change port in app.py:
|
|
app.run(debug=True, host='0.0.0.0', port=5001)
|
|
```
|
|
|
|
## Future Enhancements
|
|
|
|
- [ ] Meal planner with calendar view
|
|
- [ ] Barcode scanning (Open Food Facts API)
|
|
- [ ] Recipe builder
|
|
- [ ] Meal templates
|
|
- [ ] Export to CSV/PDF
|
|
- [ ] Photo food logging
|
|
- [ ] Workout integration
|
|
- [ ] Body measurements tracking
|
|
- [ ] Progress photos
|
|
- [ ] Mobile app version
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
calorie_tracker_app/
|
|
├── app.py # Main Flask application
|
|
├── models.py # Database models
|
|
├── config.py # Configuration
|
|
├── api_client.py # API integration
|
|
├── utils.py # Helper functions
|
|
├── seed_data.py # Filipino foods data
|
|
├── requirements.txt # Python dependencies
|
|
├── .env.example # Environment variables template
|
|
├── templates/ # HTML templates
|
|
│ ├── base.html
|
|
│ ├── dashboard.html
|
|
│ ├── add_meal.html
|
|
│ ├── login.html
|
|
│ ├── register.html
|
|
│ ├── foods.html
|
|
│ ├── meal_planner.html
|
|
│ ├── progress.html
|
|
│ └── goals.html
|
|
└── static/ # CSS, JS, images
|
|
├── css/
|
|
├── js/
|
|
└── images/
|
|
```
|
|
|
|
## Contributing
|
|
|
|
This is a personal project, but suggestions are welcome!
|
|
|
|
## License
|
|
|
|
MIT License - Feel free to use and modify for your own needs.
|
|
|
|
## Credits
|
|
|
|
- **API Ninjas** for nutrition data
|
|
- **Tailwind CSS** for styling
|
|
- **Chart.js** for visualizations
|
|
- **Filipino food data** compiled from various nutrition sources
|
|
|
|
## Support
|
|
|
|
For issues or questions:
|
|
1. Check this README
|
|
2. Check the troubleshooting section
|
|
3. Review the code comments
|
|
|
|
---
|
|
|
|
**Made with ❤️ for Filipino food lovers and fitness enthusiasts!**
|
|
|
|
## Quick Start Summary
|
|
|
|
```bash
|
|
# 1. Setup
|
|
python -m venv venv
|
|
source venv/bin/activate # or venv\Scripts\activate on Windows
|
|
pip install -r requirements.txt
|
|
|
|
# 2. Configure (optional)
|
|
cp .env.example .env
|
|
# Add your API key to .env
|
|
|
|
# 3. Initialize
|
|
python app.py # Creates database
|
|
python seed_data.py # Adds Filipino foods
|
|
|
|
# 4. Run
|
|
python app.py
|
|
|
|
# 5. Open browser
|
|
# Go to http://localhost:5000
|
|
```
|
|
|
|
Enjoy tracking your nutrition! 🎉
|