MealMate - Intelligent Meal Planning Application

Overview

MealMate is a full-stack web application designed to streamline meal planning, recipe management, and shopping list generation. Built with modern web technologies, it offers an intuitive interface for organizing your culinary life with AI-powered recipe parsing and intelligent meal suggestions.

✨ Key Features

🍽️ Meal Planning

• Weekly Meal Planner: Visual calendar interface for planning lunch and dinner for weekdays
• Drag & Drop Interface: Intuitive drag-and-drop functionality to assign recipes to meal slots
• Optimistic Updates: Instant UI feedback with automatic rollback on errors
• Customizable Servings: Adjust serving sizes for meal planning

📚 Recipe Management

• AI-Powered Recipe Parsing: Convert recipe text into structured format using Mistral AI
• URL Recipe Scraping: Import recipes directly from web URLs
• Recipe Collections: Organize recipes into custom collections
• Bulk Operations: Import, export, and manage multiple recipes efficiently
• Recipe Sharing: Share recipes via secure links with expiration dates
• Favorites & Ratings: Mark favorites and rate recipes (1-5 stars)
• Advanced Search: Filter by dietary tags, difficulty, prep time, and more

🛒 Shopping Lists

• Auto-Generation: Generate shopping lists from your weekly meal plans
• Cost Estimation: Automatic cost calculation for shopping items
• Interactive Lists: Check off items as you shop
• PDF Export: Export shopping lists and recipes for offline use

💡 Smart Features

• Nutrition Analysis: Detailed nutritional information for recipes
• Dietary Filtering: Support for vegetarian, vegan, gluten-free, keto, and more
• Bulk Import/Export: Comprehensive data backup and migration tools
• Smart Suggestions: AI-powered meal recommendations (planned feature)

🏗️ Architecture

Frontend

• React 18 with TypeScript for type-safe development
• Vite for lightning-fast development and optimized builds
• Tailwind CSS for utility-first styling
• Radix UI for accessible, headless UI components
• React Query (TanStack) for server state management
• React Hook Form with Zod validation
• Wouter for lightweight client-side routing

Backend

• Express.js with TypeScript for robust API development
• PostgreSQL with Drizzle ORM for type-safe database operations
• Neon Database for serverless PostgreSQL deployment
• Zod for runtime validation and type inference
• Mistral AI integration for intelligent recipe parsing
• Winston for structured logging and monitoring

Database Schema

• Recipes: Core recipe data with JSONB ingredients
• Collections: Custom recipe organization
• Meal Plans: Weekly meal scheduling
• Shopping Lists: Generated from meal plans
• Recipe Sharing: Secure link management

🚀 Getting Started

Prerequisites

• Node.js (v18 or higher)
• PostgreSQL database (local or cloud)
• Mistral AI API key for recipe parsing

Installation

1. Clone the repository

   git clone <repository-url>
   cd MealMate

2. Install dependencies

   npm install

3. Environment Configuration Create a .env file in the project root:

   # Database Configuration
   DATABASE_URL=postgresql://username:password@localhost:5432/mealmate
   
   # AI Integration
   MISTRAL_API_KEY=your_mistral_api_key_here
   
   # Server Configuration
   PORT=5000
   NODE_ENV=development
   
   # Session Security
   SESSION_SECRET=your_secure_session_secret

4. Database Setup

   # Initialize database with schema and sample data
   npm run db:init
   
   # Or run migrations manually
   npm run db:migrate

5. Development Server

   npm run dev

   Access the application at http://localhost:5000

📋 Available Scripts

Development

• npm run dev - Start development server with hot reload
• npm run check - TypeScript type checking
• npm test - Run test suite
• npm run test:watch - Run tests in watch mode
• npm run test:coverage - Generate test coverage report

Database Operations

• npm run db:generate - Generate migration files from schema changes
• npm run db:push - Push schema directly to database (development)
• npm run db:migrate - Run database migrations (production)
• npm run db:studio - Open Drizzle Studio GUI
• npm run db:init - Initialize database with schema and sample data

Production

• npm run build - Build for production
• npm start - Start production server

🗂️ Project Structure

MealMate/
├── client/                 # Frontend React application
│   ├── src/
│   │   ├── components/     # Reusable UI components
│   │   ├── hooks/          # Custom React hooks
│   │   ├── lib/            # Utilities and configurations
│   │   └── pages/          # Route components
├── server/                 # Backend Express application
│   ├── routes.ts           # API route definitions
│   ├── storage.ts          # Database access layer
│   ├── recipe-parser.ts    # AI-powered recipe parsing
│   └── ...                 # Additional server modules
├── shared/                 # Shared TypeScript types and schemas
└── migrations/             # Database migration files

🔧 Configuration

Path Aliases

• @/ → client/src/
• @shared/ → shared/
• @server/ → server/
• @client/ → client/src/
• @assets/ → attached_assets/

Environment Variables

Variable	Description	Required
DATABASE_URL	PostgreSQL connection string	Yes
MISTRAL_API_KEY	Mistral AI API key for recipe parsing	Yes
PORT	Server port (default: 5000)	No
NODE_ENV	Environment mode	No
SESSION_SECRET	Secret for session management	Yes

🚀 Recent Improvements

Enhanced Drag & Drop System

• Optimistic Updates: Immediate visual feedback during drag operations
• Error Handling: Automatic rollback on failed operations
• Loading States: Visual indicators during async operations
• Improved UX: Better visual feedback and hover states

Performance Optimizations

• React Query Integration: Efficient server state management
• Optimized Cache Invalidation: Precise cache updates for related data
• Memory Management: Proper cleanup and error boundaries

📊 API Endpoints

Recipes

• GET /api/recipes - List recipes with filtering
• POST /api/recipes - Create new recipe
• POST /api/recipes/parse - AI-powered text parsing
• POST /api/recipes/parse-url - Import from URL
• PUT /api/recipes/:id/favorite - Toggle favorite status

Meal Planning

• GET /api/meal-plans - Get meal plans for date range
• POST /api/meal-plans - Create/update meal plan
• DELETE /api/meal-plans/:id - Remove meal plan

Shopping Lists

• GET /api/shopping-list - Generate shopping list for week
• PUT /api/shopping-list/:id/check - Toggle item checked state

Collections & Sharing

• GET /api/collections - List recipe collections
• POST /api/recipes/:id/share - Create shareable link
• GET /api/shared/:shareId - Access shared recipe

🔒 Security Features

• Input Validation: Comprehensive validation using Zod schemas
• SQL Injection Protection: Parameterized queries with Drizzle ORM
• XSS Prevention: HTML sanitization for user inputs
• Rate Limiting: API endpoint protection
• Secure Sessions: Express session management
• CORS Configuration: Properly configured cross-origin requests

📱 Mobile Support

• Responsive Design: Mobile-first approach with Tailwind CSS
• Touch Interactions: Optimized for touch devices
• Progressive Web App: Service worker support (planned)

🧪 Testing

• Jest for unit and integration tests
• Testing Library for React component testing
• Supertest for API endpoint testing
• Coverage Reports with detailed metrics

🚀 Deployment

Production Build

npm run build
npm start

Docker Support

docker build -t mealmate .
docker run -p 5000:5000 mealmate

Environment Setup

• Configure production database
• Set secure session secrets
• Enable HTTPS in production
• Configure proper CORS settings

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

📄 License

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

🆘 Troubleshooting

Common Issues

Database Connection Issues

• Verify DATABASE_URL in .env file
• Ensure PostgreSQL is running
• Check database permissions

Recipe Parsing Failures

• Verify MISTRAL_API_KEY is valid
• Check network connectivity
• Review API rate limits

Build Failures

• Clear node_modules and reinstall
• Check Node.js version compatibility
• Verify all environment variables

Getting Help

• Check the CLAUDE.md file for detailed development guidance
• Review server logs for error details
• Use the health check endpoint: GET /api/health

🔮 Roadmap

• Mobile app development
• Advanced nutrition tracking
• Social features and recipe sharing
• AI-powered meal suggestions
• Integration with grocery delivery services
• Recipe video support
• Advanced meal planning templates

---

Built with ❤️ using modern web technologies for a seamless meal planning experience.