FreshBudget

Inspiration

Food insecurity and budget anxiety are real problems for many people. We wanted to build something that removes the guesswork from eating well on a tight budget; a tool that doesn't just suggest recipes, but actually tells you where the best deals exist in your area.

What it does

FreshBudget lets you set a budget, max time to prep, dietary preferences, intolerances, and nutrition goals (protein, fiber), then generates personalized meal plans with real ingredient pricing pulled live from the APIs of a variety stores. A Gemini-powered ranking layer lets users further sort their meal plans by querying the AI-model with criteria like "high protein and quick to make," and can save their favorite plans to their account to reference later.

How we built it

Frontend: React 19 + TypeScript, built with Vite, styled with custom CSS using a design token system
Backend: Python Flask REST API with Flask-CORS
Recipe data: Spoonacular API (complexSearch with nutrition) with a local file cache to avoid redundant calls
Grocery pricing: Kroger API (OAuth2 client credentials) for live ingredient pricing with in-memory caching; four additional stores (Safeway, Trader Joe's, Whole Foods, Costco) use curated static catalogues
AI ranking: Google Gemini (google-genai) to rank and explain meal plan recommendations based on user-defined criteria
Auth: JWT-based signup/login with bcrypt password hashing via Werkzeug
Database: MongoDB (PyMongo) for persisting user accounts and saved meal plans
Meal plan optimizer: A combinatorial engine that filters recipes by constraints, prices every ingredient, then scores all valid meal combinations against nutrition goals

Challenges we ran into

Kroger API unit conversions — matching Spoonacular ingredient amounts (e.g. "2 cloves garlic") to Kroger package sizes (e.g. "3 ct") required building a full unit conversion system across weight, volume, and count units
Combinatorial explosion — generating all valid meal combinations grows fast; we had to cap the candidate pool and deduplicate combinations to keep response times reasonable
API quota management — Spoonacular charges points per request, especially with addRecipeNutrition=True; we built a persistent file cache keyed by filter params to avoid burning quota on repeated queries
Pricing coverage gaps — not every Spoonacular ingredient maps cleanly to a Kroger product; we had to gracefully handle misses without crashing the optimizer

Accomplishments that we're proud of

A fully working end-to-end pipeline: preferences → real recipe search → live grocery pricing → AI ranking → saved plans
The Kroger OAuth integration working seamlessly with automatic token refresh
A clean, polished UI that feels like a real product, not a hackathon prototype
The combinatorial meal plan optimizer correctly enforcing budget, allergen, and prep time constraints simultaneously
Learning to generate code with Claude. This helped us focus on ideating and letting Claude brings them to life.

What we learned

How to integrate multiple third-party APIs (Spoonacular, Kroger, Gemini) in a single coherent data pipeline
The complexity of unit normalization across culinary and grocery measurement systems
How to use Gemini for structured ranking with natural language input
JWT auth and MongoDB used to secure created users and personal meals/plans

What's next for FreshBudget

User location input to find the nearest grocery store instead of using a hardcoded ZIP code for Kroger
Live pricing for all stores — replace static catalogues with real APIs for Safeway, Whole Foods, etc.
Shopping list export — generate a consolidated grocery list from a saved meal plan
Nutritional tracking — log meals and track daily intake against goals over time
Mobile app — the use case is inherently mobile (planning at the store, on the go)