Skip to content

README.md

Latest commit

 

History

History
390 lines (289 loc) · 11.8 KB

README.md

File metadata and controls

390 lines (289 loc) · 11.8 KB

🍳 ImhotepChef

Where Culinary Magic Meets Modern Technology

Django React PostgreSQL Docker

A modern, AI-powered recipe management platform that transforms your ingredients into culinary masterpieces

🚀 Quick Start • ✨ Features • 🛠️ Tech Stack • 📱 Demo • 🤝 Contributing

✨ Features

🔍 AI-Powered Recipe Generation - Transform your available ingredients into delicious recipes using advanced AI
👤 Smart User Profiles - Personalized cooking experience with user preferences and dietary restrictions
📚 Recipe History - Keep track of your culinary adventures with comprehensive recipe history
🔐 Secure Authentication - Multi-authentication system with Google OAuth and JWT tokens
📧 Email Verification - Secure account verification and password recovery system
📱 Responsive Design - Beautiful, mobile-first interface that works on all devices
🎨 Modern UI/UX - Clean, intuitive design built with Tailwind CSS
⚡ Real-time Updates - Instant recipe generation and seamless user experience

🛠️ Tech Stack

Backend

  • Django REST Framework - Robust API development
  • PostgreSQL - Reliable data persistence
  • JWT Authentication - Secure token-based auth
  • Google AI (Gemini) - Advanced recipe generation
  • Docker - Containerized deployment

Frontend

  • React 19 - Modern component-based UI
  • Vite - Lightning-fast development
  • Tailwind CSS - Utility-first styling
  • Axios - Seamless API communication
  • React Router - Dynamic navigation

📱 Demo

🏠 Homepage

Beautiful landing page introducing users to the magic of AI-powered cooking

🔐 Authentication System

  • Register/Login - Secure user authentication
  • Google OAuth - One-click social login
  • Email Verification - Secure account activation
  • Password Recovery - Easy password reset process

🍽️ Recipe Generation

Input your available ingredients and let our AI chef create personalized recipes just for you!

👤 User Dashboard

  • Profile Management - Update personal information
  • Recipe History - Browse your culinary journey
  • Usage Statistics - Track your monthly recipe generation

🚀 Quick Start for Contributors

Get cooking in less than 2 minutes! 🚀

🔧 Prerequisites

⚡ Setup (One Command!)

1. Clone & Navigate

git clone https://github.com/Kbassem10/ImhotepChef.git
cd ImhotepChef

2. Set Up Environment Variables 🔑 Create a .env file in the backend/ImhotepChef directory with your Gemini API keys:

# Navigate to backend directory
cd backend/ImhotepChef

# Create .env file with required Gemini API keys
cat > .env << 'EOF'
# Gemini API Keys (Required - Get from https://aistudio.google.com/app/apikey)
GEMINI_API_KEY_1=your_first_gemini_api_key_here
GEMINI_API_KEY_2=your_second_gemini_api_key_here
EOF

# Also set up frontend environment variables
cd ../../frontend/ImhotepChef
cp ../env.example .env
# Edit .env if needed - default VITE_API_URL=http://localhost:8000 should work

# Return to project root
cd ../..

🚨 Important: You must have at least 1 Gemini API key and up to 2 API keys for the AI recipe generation to work. Get your free API keys from Google AI Studio.

📝 Note: The frontend .env file should contain VITE_API_URL=http://localhost:8000 to match the Docker backend port.

3. Launch the Magic ✨

docker compose up --build

That's it! 🎉 Your culinary assistant is ready!

🎯 What This Does

✅ Database Setup - PostgreSQL container (port 5430)
✅ Backend Magic - Django REST API (http://localhost:8000)
✅ Frontend Beauty - React application (http://localhost:3000)
✅ Admin Panel - Django admin with demo credentials
✅ Auto-Migration - Database schema setup
✅ Hot Reload - Live code changes

🌐 Access Points

Service URL Description
🎨 Frontend http://localhost:3000 Main application interface
⚡ Backend API http://localhost:8000 REST API endpoints
🔧 Django Admin http://localhost:8000/admin/ Admin panel (admin/admin123)
🗄️ Database localhost:5430 PostgreSQL instance

🔧 Manual Setup (Alternative)

Prefer hands-on control? Follow these detailed steps!

📋 Prerequisites for Manual Setup

📝 Step-by-Step Manual Setup

1️⃣ Clone the Repository

git clone https://github.com/Kbassem10/ImhotepChef.git
cd ImhotepChef

2️⃣ Set Up PostgreSQL Database

# 🚀 Start PostgreSQL service
sudo systemctl start postgresql  # Linux
# or
brew services start postgresql   # macOS

# 🗄️ Create database and user
sudo -u postgres psql
CREATE DATABASE imhotepchef_db;
CREATE USER imhotepchef_user WITH PASSWORD 'imhotepchef_password';
GRANT ALL PRIVILEGES ON DATABASE imhotepchef_db TO imhotepchef_user;
\q

3️⃣ Set Up Backend (Django)

# 📂 Navigate to backend directory
cd backend/ImhotepChef

# 🐍 Create virtual environment
python -m venv venv

# ⚡ Activate virtual environment
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate     # Windows

# 📦 Install dependencies
pip install -r requirements.txt

# 🔄 Create environment variables (create .env file)
echo "DEBUG=True
DATABASE_NAME=imhotepchef_db
DATABASE_USER=imhotepchef_user
DATABASE_PASSWORD=imhotepchef_password
DATABASE_HOST=localhost
DATABASE_PORT=5432
SECRET_KEY=your-secret-key-here" > .env

# 🗄️ Run migrations
python manage.py makemigrations
python manage.py migrate

# 👤 Create superuser
python manage.py createsuperuser

# 🚀 Start development server
python manage.py runserver

4️⃣ Set Up Frontend (React)

# 🆕 Open new terminal and navigate to frontend directory
cd frontend/ImhotepChef

# 📦 Install dependencies
npm install

# 🌐 Create environment variables (create .env file)
# IMPORTANT: Make sure this port matches your Django backend port (8000)
echo "VITE_API_URL=http://localhost:8000" > .env

# Alternative: Copy from example and edit
# cp ../env.example .env

# 🚀 Start development server
npm run dev

🚨 Important: The VITE_API_URL must point to your Django backend server. Default is http://localhost:8000. Make sure your Django server is running on port 8000 with python manage.py runserver.

5️⃣ Access the Application

Service URL Status
🎨 Frontend http://localhost:3000 ✅ Ready
⚡ Backend API http://localhost:8000 ✅ Ready
🔧 Django Admin http://localhost:8000/admin ✅ Ready

💻 Manual Development Workflow

🚀 Starting the application:

# Terminal 1 - Backend
cd backend/ImhotepChef
source venv/bin/activate
python manage.py runserver  # This runs on port 8000

# Terminal 2 - Frontend  
cd frontend/ImhotepChef
# Make sure .env file exists with VITE_API_URL=http://localhost:8000
npm run dev

⏹️ Stopping the application:

  • Press Ctrl+C in both terminals
  • Deactivate virtual environment: deactivate

🔧 Environment File Setup:

# Frontend environment setup (if not done during initial setup)
cd frontend/ImhotepChef
cp ../env.example .env
# Edit .env to ensure VITE_API_URL=http://localhost:8000

⚙️ Development

🔧 Development Mode Features:

  • 🔄 Hot reloading for both frontend and backend
  • 📁 Volume mounting for live code changes
  • 🐛 Debug mode enabled
  • 🎨 Live CSS updates with Tailwind
  • ⚡ Fast refresh in React

🛑 Stop the application:

docker compose down

📜 View logs:

docker compose logs -f

🔄 Rebuild after dependency changes:

docker compose up --build

🚨 Troubleshooting

🔌 Port Conflicts

Issue: "address already in use" errors

💡 Solution:

# Check what's using the ports
sudo lsof -i :3000  # Frontend port
sudo lsof -i :8000  # Backend port  
sudo lsof -i :5430  # Database port

# Stop conflicting services
sudo systemctl stop postgresql  # Linux
brew services stop postgresql   # macOS

🛠️ Manual Setup Issues

Problem Solution
🗄️ Database connection failed Verify PostgreSQL is running & credentials are correct
🐍 Python import errors Ensure virtual environment is activated
📦 Node.js version issues Update to Node.js 20+
🔐 Permission denied Check file permissions and user access

🐳 Docker Setup Issues

Problem Solution
🚀 Container build fails Run docker system prune -a and retry
🗄️ Database connection timeout Wait for health check to complete
📱 Frontend not loading Check if port 3000 is available
⚡ Hot reload not working Restart container with docker compose restart
🔧 API calls failing Verify frontend .env has VITE_API_URL=http://localhost:8000
🔑 Environment variables not working Ensure both backend and frontend .env files are created
🌐 Backend port issues Confirm Django is running on port 8000 (check docker-compose.yml)

📝 Environment Configuration Notes

For Docker Setup:

  • Backend runs on: http://localhost:8000
  • Frontend runs on: http://localhost:3000
  • Frontend .env should have: VITE_API_URL=http://localhost:8000

For Manual Setup:

  • Copy frontend/.env.example to frontend/ImhotepChef/.env
  • Ensure Django runs with: python manage.py runserver (port 8000)
  • Verify frontend .env points to correct backend port

🤝 Contributing

We welcome contributions from developers of all skill levels!

🎯 How to Contribute

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

🐛 Found a Bug?

Open an issue with:

  • 📝 Clear description
  • 🔄 Steps to reproduce
  • 💻 System information
  • 📸 Screenshots (if applicable)

💡 Have an Idea?

We'd love to hear it! Open an issue with the enhancement label.

📄 License

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

🌟 Show Your Support

If you find ImhotepChef helpful, please consider:

  • ⭐ Starring this repository
  • 🍴 Forking to contribute
  • 🐛 Reporting issues
  • 💡 Suggesting new features

Made with ❤️ by the ImhotepChef Team

Happy Coding & Happy Cooking! 👨‍🍳✨

⬆ Back to Top