🍲 FlavorSnap

AI-Powered Food Classification Web Application

Snap a picture of your food and let AI identify the dish instantly!

📋 Table of Contents

• 🌟 Features
• 🏗️ Project Structure
• 🛠️ Tech Stack
• 🚀 Quick Start
• 📖 Detailed Setup
• 🤝 Contributing
• 📝 API Documentation
• 🧪 Testing
• 📊 Model Information
• 🐛 Troubleshooting
• 📄 License

🌟 Features

🎯 Core Functionality

• 📸 Image Upload & Preview: Drag-and-drop or click to upload food images
• 🤖 AI-Powered Classification: ResNet18 model trained on Nigerian dishes
• 📊 Confidence Scores: Get prediction confidence percentages
• 🗂️ Automatic Organization: Images saved to predicted class folders
• ⚡ Real-time Processing: Instant classification results

🎨 User Experience

• 📱 Responsive Design: Works seamlessly on desktop, tablet, and mobile
• 🎭 Modern UI: Built with TailwindCSS and React components
• 🔄 Loading States: Visual feedback during processing
• ❌ Error Handling: User-friendly error messages and recovery
• 🌙 Dark Mode Support: Comfortable viewing in any lighting
• 🌍 Internationalization (i18n): Multi-language support (English, French, Arabic, Yoruba) with RTL layout

🔧 Developer Features

• 📡 RESTful API: Clean API endpoints for integration
• 🧪 Comprehensive Testing: Unit, integration, and E2E tests
• 📝 Type Safety: Full TypeScript implementation
• 🐳 Docker Support: Containerized deployment ready
• 📊 Analytics: Classification history and insights

🏗️ Project Structure

flavorsnap/
├── 📁 frontend/                    # Next.js web application
│   ├── 📁 pages/                   # React pages and API routes
│   │   ├── 📄 index.tsx           # Landing page
│   │   ├── 📄 classify.tsx        # Classification interface
│   │   └── 📁 api/                # Backend API endpoints
│   ├── 📁 public/                 # Static assets
│   │   ├── 📁 images/             # Hero images and icons
│   │   └── 📄 favicon.ico
│   ├── 📁 styles/                 # Global CSS and Tailwind
│   ├── 📄 package.json            # Frontend dependencies
│   └── 📄 tsconfig.json           # TypeScript configuration
├── 📁 ml-model-api/               # Flask ML inference API
│   ├── 📄 app.py                  # Main Flask application
│   ├── 📄 requirements.txt        # Python dependencies
│   └── 📄 model_loader.py         # Model loading utilities
├── 📁 contracts/                  # Soroban smart contracts
│   ├── 📁 model-governance/       # Model governance contracts
│   ├── 📁 tokenized-incentive/    # Token incentive system
│   └── 📁 sensory-evaluation/     # Sensory evaluation contracts
├── 📁 dataset/                    # Training and validation data
│   ├── 📁 train/                  # Training images by class
│   ├── 📁 test/                   # Test images
│   └── 📄 data_split.py           # Dataset utilities
├── 📁 models/                     # Trained model files
├── 📁 uploads/                    # User uploaded images
├── 📁 pages/                      # Additional documentation
├── 📄 model.pth                   # Trained PyTorch model (44MB)
├── 📄 food_classes.txt            # List of food categories
├── 📄 train_model.ipynb           # Model training notebook
├── 📄 dashboard.py                # Panel-based dashboard
├── 📄 Cargo.toml                  # Rust workspace configuration
├── 📄 PROJECT_ISSUES.md           # Known issues and roadmap
└── 📄 README.md                   # This file

🛠️ Tech Stack

🎨 Frontend

• Framework: Next.js 15.3.3 with React 19
• Language: TypeScript 5
• Styling: TailwindCSS 4
• Icons: Lucide React
• State Management: React Hooks & Context
• HTTP Client: Axios/Fetch API
• Form Handling: React Hook Form
• Testing: Jest & React Testing Library
• i18n: next-i18next with RTL support

🧠 Machine Learning

• Framework: PyTorch
• Architecture: ResNet18 (ImageNet pretrained)
• Image Processing: Pillow & torchvision
• Model Serving: Flask
• Inference: CPU-optimized for deployment

⚙️ Backend

• API: Flask with RESTful endpoints
• Language: Python 3.8+
• File Storage: Local filesystem (configurable)
• Image Processing: Pillow, OpenCV
• Serialization: JSON

🔗 Blockchain

• Platform: Stellar/Soroban
• Language: Rust
• Smart Contracts: Model governance, incentives
• SDK: Soroban SDK v22.0.6

🛠️ Development Tools

• Version Control: Git
• Package Manager: npm/yarn/pnpm
• Code Quality: ESLint, Prettier
• Containerization: Docker & Docker Compose
• CI/CD: GitHub Actions (planned)

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm/yarn
• Python 3.8+ and pip
• Git
• 4GB+ RAM for model loading

One-Command Setup

# Clone and setup everything
git clone https://github.com/your-username/flavorsnap.git
cd flavorsnap
npm run setup

Manual Setup

1. Clone Repository

git clone https://github.com/your-username/flavorsnap.git
cd flavorsnap

2. Frontend Setup

cd frontend
npm install
cp .env.example .env.local
# Edit .env.local with your configuration
npm run dev

3. Backend Setup

cd ml-model-api
pip install -r requirements.txt
python app.py

4. Access Application

• Frontend: http://localhost:3000
• API: http://localhost:5000

📖 Detailed Setup

Environment Configuration

Create .env.local in the frontend directory:

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:5000
NEXT_PUBLIC_MODEL_ENDPOINT=/predict

# File Upload Settings
MAX_FILE_SIZE=10485760  # 10MB
ALLOWED_FILE_TYPES=jpg,jpeg,png,webp

# Model Configuration
MODEL_CONFIDENCE_THRESHOLD=0.6
ENABLE_CLASSIFICATION_HISTORY=true

# Feature Flags
ENABLE_ANALYTICS=false
ENABLE_DARK_MODE=true

# Development
NODE_ENV=development
DEBUG=true

Python Environment Setup

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r ml-model-api/requirements.txt
pip install torch torchvision pillow flask

Model Setup

The trained model (model.pth) should be in the project root. If you want to train your own model:

jupyter notebook train_model.ipynb
# Follow the notebook instructions

🤝 Contributing

We love contributions! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

🎯 How to Contribute

1. Fork & Clone

git clone https://github.com/your-username/flavorsnap.git
cd flavorsnap

2. Setup Development Environment

npm run dev:setup

3. Create Feature Branch

git checkout -b feature/amazing-feature

4. Make Changes

• Follow the existing code style
• Add tests for new functionality
• Update documentation as needed

5. Test Your Changes

npm run test
npm run lint
npm run build

6. Commit & Push

git commit -m "feat: add amazing feature"
git push origin feature/amazing-feature

7. Create Pull Request

• Provide clear description of changes
• Link relevant issues
• Include screenshots for UI changes

📝 Development Guidelines

Code Style

• TypeScript: Strict mode enabled
• React: Functional components with hooks
• CSS: TailwindCSS utility classes
• Python: PEP 8 compliant
• Rust: rustfmt formatting

Commit Messages

Follow Conventional Commits:

• feat: New features
• fix: Bug fixes
• docs: Documentation changes
• style: Code formatting
• refactor: Code refactoring
• test: Test additions
• chore: Maintenance tasks

Testing Requirements

• Unit tests for all new functions
• Integration tests for API endpoints
• E2E tests for user workflows
• Minimum 80% code coverage

Pull Request Process

1. Update README.md for new features
2. Add/update tests
3. Ensure CI/CD passes
4. Request code review
5. Merge after approval

🏆 Contribution Areas

Frontend

• UI/UX improvements
• New components
• Performance optimizations
• Mobile responsiveness
• Accessibility features

Backend

• API enhancements
• Model optimization
• Security improvements
• Database integration
• Performance tuning

Machine Learning

• Model architecture improvements
• New food categories
• Accuracy enhancements
• Training pipeline
• Model deployment

Documentation

• API documentation
• Tutorials
• Examples
• Translation
• Video guides

📝 API Documentation

Endpoints

POST /predict

Classify uploaded food image.

Request:

curl -X POST \
  http://localhost:5000/predict \
  -F 'image=@/path/to/food.jpg'

Response:

{
  "label": "Moi Moi",
  "confidence": 85.7,
  "all_predictions": [
    { "label": "Moi Moi", "confidence": 85.7 },
    { "label": "Akara", "confidence": 9.2 },
    { "label": "Bread", "confidence": 3.1 }
  ],
  "processing_time": 0.234
}

GET /health

Check API health status.

Response:

{
  "status": "healthy",
  "model_loaded": true,
  "version": "1.0.0"
}

GET /classes

Get list of supported food classes.

Response:

{
  "classes": ["Akara", "Bread", "Egusi", "Moi Moi", "Rice and Stew", "Yam"],
  "count": 6
}

Error Responses

{
  "error": "Invalid image format",
  "code": "INVALID_FILE_TYPE",
  "message": "Only JPG, PNG, and WebP images are supported"
}

🧪 Testing

Running Tests

# Frontend tests
cd frontend
npm run test
npm run test:coverage
npm run test:e2e

# Backend tests
cd ml-model-api
python -m pytest
python -m pytest --cov=app

# Integration tests
npm run test:integration

Test Structure

tests/
├── 📁 frontend/
│   ├── 📁 components/          # Component tests
│   ├── 📁 pages/              # Page tests
│   └── 📁 utils/              # Utility tests
├── 📁 backend/
│   ├── 📁 api/                # API endpoint tests
│   └── 📁 model/              # Model tests
└── 📁 e2e/                    # End-to-end tests

Test Data

Test images are available in tests/fixtures/images/ with proper labels for validation.

📊 Model Information

Architecture

• Base Model: ResNet18 (ImageNet pretrained)
• Input Size: 224x224 RGB images
• Output Classes: 6 Nigerian food categories
• Parameters: 11.7M total, 1.2M trainable

Training Details

• Dataset: 2,400+ images (400 per class)
• Training Split: 80% train, 20% validation
• Epochs: 50 with early stopping
• Optimizer: Adam (lr=0.001)
• Accuracy: 94.2% validation accuracy

Food Classes

1. Akara - Bean cake
2. Bread - Various bread types
3. Egusi - Melon seed soup
4. Moi Moi - Bean pudding
5. Rice and Stew - Rice with tomato stew
6. Yam - Yam dishes

Performance Metrics

• Top-1 Accuracy: 94.2%
• Top-3 Accuracy: 98.7%
• Inference Time: ~200ms (CPU)
• Model Size: 44MB

🐛 Troubleshooting

Common Issues

Model Loading Fails

# Check model path
ls -la model.pth
# Verify file integrity
python -c "import torch; print(torch.load('model.pth').keys())"

Frontend Build Errors

# Clear cache
rm -rf .next node_modules
npm install
npm run build

API Connection Issues

# Check if API is running
curl http://localhost:5000/health
# Verify CORS settings
curl -H "Origin: http://localhost:3000" http://localhost:5000/predict

Memory Issues

# Monitor memory usage
python -c "import torch; print(f'GPU Available: {torch.cuda.is_available()}')"
# Reduce batch size if needed

Debug Mode

Enable debug logging:

DEBUG=true
LOG_LEVEL=debug

Performance Optimization

• Use WebP images for faster uploads
• Implement image compression on client-side
• Cache model predictions for similar images
• Use CDN for static assets

📄 License

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

🙏 Acknowledgments

• PyTorch for the deep learning framework
• Next.js for the React framework
• TailwindCSS for the styling framework
• Stellar/Soroban for blockchain integration
• The Nigerian food community for dataset contributions

📞 Support

• Telegram Group: Join our community
• GitHub Issues: Report bugs
• Email: support@flavorsnap.com

---

⭐ Star this repository if it helped you!

Made with 💚 for Nigerian food lovers