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