An intelligent meal planning system that generates personalized recipes, weekly meal plans, nutritional analysis, and shopping lists using AI agents powered by LangGraph and Google Cloud.
- AI Recipe Generation: Create custom recipes based on dietary preferences, available ingredients, and nutritional goals
- Multi-Agent Architecture: Specialized AI agents for meal planning, nutrition analysis, recipe creation, and validation
- Nutritional Tracking: Automatic calculation of macros and nutritional information for entire recipes
- Recipe Image Generation: AI-generated images for every recipe
- Modern Web Interface: Clean, responsive UI built with React and TypeScript
- REST API: FastAPI backend with automatic OpenAPI documentation
The easiest way to run the entire application:
# Clone the repository
git clone <repo-url>
cd snaptop
# Set up environment variables
cp .env.example .env
# Edit .env and add your API keys
# Start all services
docker-compose up --build
# Or use the Makefile
make devAccess the application:
- Frontend: http://localhost:3000
- Backend API: http://localhost:8000
- API Documentation: http://localhost:8000/docs (Interactive Swagger UI)
See QUICKSTART.md for detailed instructions on running locally without Docker.
snaptop/
├── backend/ # Python FastAPI backend
│ ├── src/
│ │ ├── models/ # Pydantic data models
│ │ ├── server/ # FastAPI server
│ │ ├── agents/ # AI agents (Chef, Planner, etc.)
│ │ ├── langgraph_tools/# LangGraph tools and utilities
│ │ └── common/ # Shared utilities
│ ├── Dockerfile
│ └── README.md # Backend-specific documentation
├── frontend/ # React + TypeScript frontend
│ ├── src/
│ │ ├── RecipeForm.tsx
│ │ ├── RecipeDisplay.tsx
│ │ └── grpcClient.ts # API client (renamed, now uses REST)
│ ├── package.json
│ └── README.md # Frontend-specific documentation
├── bigquery/ # BigQuery schemas and scripts
├── docker-compose.yml # Multi-service orchestration
├── Makefile # Development commands
├── pyproject.toml # Python dependencies
├── QUICKSTART.md # Quick start guide
└── MIGRATION.md # gRPC → FastAPI migration guide
Backend:
- Python 3.12+
- FastAPI - Modern web framework
- Pydantic - Data validation
- LangGraph - AI agent orchestration
- LangChain - LLM integration
- Google Cloud (Vertex AI, BigQuery, Secret Manager)
Frontend:
- React 18
- TypeScript
- Vite - Build tool
- Tailwind CSS - Styling
Infrastructure:
- Docker & Docker Compose
- uv - Fast Python package manager
The system uses specialized AI agents:
- Chef Agent: Generates recipes using web search and nutrition APIs
- Meal Planner: Creates weekly meal plans based on user preferences (TODO)
- Nutritionist: Allocates macro targets per meal (TODO)
- Validator: Checks recipes against constraints and user preferences (TODO)
- QUICKSTART.md - Get up and running quickly
- backend/README.md - Backend development guide
- frontend/README.md - Frontend development guide
- MIGRATION.md - Migration from gRPC to FastAPI
- Docker & Docker Compose (for containerized development)
- Python 3.12+ (for local backend development)
- Node.js 18+ (for local frontend development)
- uv (Python package manager) -
pip install uv
# Code quality (Python)
make format # Format Python code
make fix # Auto-fix linting issues
make lint # Run full lint check
# Development
make dev # Start all services with Docker Compose
make test # Run tests
make clean # Clean up generated files and cachesBackend:
cd snaptop
uv sync # Install dependencies
uv run python -m backend.src.server.fastapi_server
# Server runs on http://localhost:8000Frontend:
cd frontend
npm install
npm run dev
# App runs on http://localhost:3000Create a .env file in the project root:
# Google Cloud
GOOGLE_CLOUD_PROJECT=your-project-id
# API Keys (stored in GCP Secret Manager)
# Add other necessary environment variablesThe FastAPI backend provides the following endpoints:
Recipe Generation:
POST /api/recipes/generate- Generate a new recipe ✅- Input: Recipe description, complexity, nutrition targets, available ingredients
- Output: Complete recipe with ingredients, instructions, nutrition, and AI-generated image
Meal Planning: (TODO - Currently stubs)
POST /api/meals/generate-weekly- Generate weekly meal planPOST /api/recipes/regenerate- Regenerate an existing recipePOST /api/recipes/modify- Modify an existing recipePOST /api/shopping-list/generate- Generate shopping list
Interactive Documentation: Visit http://localhost:8000/docs for the full interactive API documentation (Swagger UI).
curl -X POST "http://localhost:8000/api/recipes/generate" \
-H "Content-Type: application/json" \
-d '{
"description": "A healthy pasta dish with chicken and vegetables",
"complexity": "medium",
"target_macros": {
"calories": 500,
"protein_grams": 35,
"carbs_grams": 45,
"fat_grams": 15
}
}'Run the test suite:
# Using make
make test
# Or directly with pytest
pytest backend/src/tests/# Check if ports are in use
lsof -i :3000,8000
# View service logs
docker-compose logs -f backend
docker-compose logs -f frontend
# Rebuild containers
docker-compose build --no-cache
docker-compose up- Check backend logs:
docker-compose logs -f backend - Verify
.envfile has correct GCP credentials - Ensure all required environment variables are set
- Verify backend is running:
curl http://localhost:8000/ - Check browser console for errors
- Ensure both services are on the same Docker network
- Recipe generation with AI
- FastAPI REST API
- AI-generated recipe images
- Nutrition calculation per serving
- Weekly meal planning
- Shopping list generation
- User profile management
- Recipe modification and regeneration
- BigQuery data persistence
- Recipe search and filtering
ISC
See QUICKSTART.md for development setup instructions.
For issues and questions:
- Review the QUICKSTART.md guide
- Check the MIGRATION.md if you're familiar with the old gRPC version
- Review API docs at http://localhost:8000/docs
Note: This project was recently migrated from gRPC to FastAPI. See MIGRATION.md for details on the architectural changes.