🍽️ MealFlow

Inventory-Aware Meal Planner + Auto-Shopper

MealFlow is an intelligent meal planning application that connects your recipes, inventory, and shopping needs into one seamless workflow. Plan your weekly meals, track what you have, and automatically generate optimized shopping lists with real pricing.

---

✨ Features

📖 Recipe Management

• Store and organize your favorite recipes
• Automatic ingredient extraction and parsing
• 3 pre-loaded sample recipes for instant testing
• Support for custom servings and instructions

📦 Inventory Tracking

• Real-time inventory management
• Track quantities and units
• Automatic deficit calculation
• Expiry date tracking (optional)

📅 Smart Meal Planning

• Create weekly meal plans based on recipe frequencies
• Intelligent scheduling across the week
• Visual meal calendar
• Automatic ingredient aggregation

🛒 Auto-Generated Shopping Lists

• Automatically calculates what you need to buy
• Smart package size optimization to minimize waste
• Real-time pricing from marketplace APIs
• De-duplication of duplicate items
• Cost estimation before purchase

🔒 Privacy & Security

• All data encrypted locally using Fernet encryption
• No data leaves your machine (except sandbox API calls)
• Secure key storage with proper file permissions
• Privacy-first design philosophy

🎨 Modern UI

• Beautiful gradient design with glass-morphism effects
• Responsive layout for all devices
• Smooth animations and transitions
• Professional Inter font typography
• Intuitive navigation

---

🚀 Quick Start

Prerequisites

• Python 3.11 or higher
• pip package manager

Installation

1. Clone the repository

git clone <your-repo-url>
cd mealflow

2. Install dependencies

pip install -r requirements.txt

3. Run the application

python3 src/app.py

4. Open your browser

http://127.0.0.1:5000

That's it! The app comes with 3 sample recipes pre-loaded for testing.

---

📖 How to Use

1️⃣ Explore Sample Recipes

Navigate to Recipes to see the pre-loaded recipes:

• 🍝 Spaghetti Carbonara
• 🍗 Chicken Stir Fry
• 🥗 Greek Salad

Or add your own custom recipes!

2️⃣ Add Inventory Items

Go to Inventory and add items you currently have:

Item: eggs
Quantity: 6
Unit: unit

3️⃣ Create a Meal Plan

Visit Meal Planner and select how many times per week you want each recipe:

Spaghetti Carbonara: 2 times/week
Chicken Stir Fry: 1 time/week
Greek Salad: 2 times/week

Click Generate Meal Plan to see:

• Your weekly meal schedule
• Shopping needs (what you're missing)

4️⃣ Generate Shopping Cart

Click Generate Shopping Cart to:

• See optimized product selections
• View real pricing for each item
• Get total cost estimate
• Place sandbox order (no real purchase)

---

🏗️ Project Structure

mealflow/
├── src/
│   ├── app.py                    # Flask web application
│   ├── main.py                   # CLI entry point (demo mode)
│   ├── core/
│   │   ├── recipe.py            # Recipe management & parsing
│   │   ├── inventory.py         # Inventory tracking
│   │   ├── planner.py           # Meal planning logic
│   │   └── cart.py              # Shopping cart generation
│   ├── integrations/
│   │   └── marketplace.py       # Amazon/Walmart sandbox API
│   ├── storage/
│   │   └── db.py                # Encrypted local storage
│   ├── templates/               # HTML templates
│   │   ├── index.html
│   │   ├── recipes.html
│   │   ├── inventory.html
│   │   ├── planner.html
│   │   └── cart.html
│   └── static/
│       └── style.css            # Modern UI styles
├── data/                        # Encrypted data storage
│   ├── .key                     # Encryption key (auto-generated)
│   ├── recipes.enc              # Encrypted recipes
│   └── inventory.enc            # Encrypted inventory
├── requirements.txt             # Python dependencies
└── README.md                    # This file

---

🛠️ Technology Stack

• Backend: Flask 3.0+ (Python web framework)
• Storage: Cryptography (Fernet encryption)
• Frontend: Vanilla JavaScript, HTML5, CSS3
• Styling: Custom CSS with modern design patterns
• APIs: Requests library for marketplace integration

---

🔐 Security Features

Local Encryption

All sensitive data (recipes, inventory) is encrypted using Fernet symmetric encryption:

• 128-bit AES encryption in CBC mode
• HMAC for authentication
• Automatic key generation and secure storage

Data Privacy

• No cloud storage - everything stays on your machine
• Marketplace API calls use sandbox mode by default
• User approval required before any order placement
• Encryption key stored with restricted permissions (chmod 600)

---

🎯 Use Cases

For Home Cooks

• Plan weekly meals efficiently
• Never forget ingredients at the store
• Minimize food waste with smart planning
• Track what you have vs. what you need

For Meal Preppers

• Batch plan multiple meals
• Optimize grocery shopping trips
• Calculate exact quantities needed
• Manage inventory across prep sessions

For Budget-Conscious Shoppers

• See total costs before shopping
• Optimize package sizes to reduce waste
• Compare prices across products
• Plan meals within budget

---

🧪 Testing & Development

Run Demo Mode (CLI)

python3 src/main.py demo

This runs a complete workflow demonstration showing:

• Recipe addition
• Inventory checking
• Meal plan creation
• Shopping cart generation
• Order placement

Debug Mode

The Flask app runs in debug mode by default:

• Auto-reload on file changes
• Detailed error messages
• Interactive debugger

---

🔮 Future Enhancements

• Real Amazon/Walmart API integration
• Nutritional information tracking
• Recipe import from URLs
• Mobile app version
• Multi-user support
• Recipe recommendations based on inventory
• Price history tracking
• Meal prep scheduling
• Dietary restriction filters
• Recipe rating system

---

📝 API Endpoints

Recipes

• GET /recipes - View all recipes
• POST /api/recipes - Add new recipe
• GET /api/recipes - Get recipes as JSON

Inventory

• GET /inventory - View inventory
• POST /api/inventory - Add inventory item
• GET /api/inventory - Get inventory as JSON

Meal Planning

• GET /planner - Meal planner page
• POST /api/plan - Create meal plan

Shopping Cart

• GET /cart - Shopping cart page
• POST /api/cart/generate - Generate cart from deficit
• POST /api/order - Place order (sandbox)

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• Flask framework for the excellent web framework
• Cryptography library for secure encryption
• Inter font family for beautiful typography
• The open-source community for inspiration

---

📧 Contact & Support

For questions, issues, or suggestions:

• Open an issue on GitHub
• Check existing documentation
• Review the code comments

---

🎉 Getting Started Checklist

• Install Python 3.11+
• Install dependencies (pip install -r requirements.txt)
• Run the app (python3 src/app.py)
• Open browser to http://127.0.0.1:5000
• Explore the 3 pre-loaded sample recipes
• Add some inventory items
• Create your first meal plan
• Generate a shopping cart
• Place a sandbox order

Happy meal planning! 🍽️✨