Optimeal AI Development Assistant
A specialized development assistant for the Optimeal AI (FitSpice/Homeland Meals) project - a full-stack nutrition and recipe application focused on South Asian cuisine with AI-powered food analysis, recipe conversion, and interactive cooking co-pilot.
What This Skill Does
Guides development work on the Optimeal AI codebase, which combines React 19 frontend with FastAPI backend, MongoDB storage, and custom Groq LLM integration for nutritional analysis, recipe intelligence, and conversational cooking assistance.
Project Architecture
Frontend Stack
**Framework:** React 19 with React Router for navigation**Styling:** Tailwind CSS with Craco build configuration**State:** Context-based management for meal tray functionality**Data:** Static JSON files for recipes and ingredient pricing**API Client:** Axios for backend communicationBackend Stack
**Framework:** FastAPI with RESTful API design (`/api` prefix)**Database:** MongoDB with Pydantic models for validation**AI Integration:** Custom Groq API wrapper using Llama-3.1-8b-instant model**Features:** Co-pilot chat, food image analysis, recipe conversionDevelopment Instructions
1. Environment Setup
**Before making changes:**
Verify `.env` files exist in both `/frontend` and `/backend` directoriesBackend requires: MongoDB connection string, Groq API key, CORS settingsFrontend requires: Backend API URL configuration2. Development Workflow
**Frontend changes:**
```bash
cd frontend
yarn install # Install dependencies
yarn start # Development server (hot reload)
yarn build # Production build
yarn test # Run test suite
npm run lint # ESLint validation
```
**Backend changes:**
```bash
cd backend
pip install -r requirements.txt
uvicorn server:app --reload --host 0.0.0.0 --port 8000
Code quality checks
black . # Format code
isort . # Sort imports
flake8 . # Lint
mypy . # Type checking
```
**Integration testing:**
```bash
python backend_test.py # Run comprehensive API tests
```
3. Key API Endpoints
**Core Nutrition & Analysis:**
`POST /api/profile` - Create user profile with BMR calculation (Mifflin-St Jeor equation) and calorie targets`POST /api/analyze-food` - Upload food image for AI nutritional analysis via Groq LLM`POST /api/recipe` - Create recipe with AI-powered traditional → quick version conversion`GET /api/daily-stats/{user_id}/{date}` - Fetch daily nutrition and fitness statistics`GET /api/ingredient-substitutions/{ingredient}` - Get Western grocery substitutions for South Asian ingredients**AI Co-pilot Features:**
`POST /api/copilot/chat` - Interactive cooking assistant with ChatGPT-style interface`POST /api/copilot/recipe-suggestions` - AI recipe suggestions based on available ingredients`POST /api/copilot/cooking-guidance` - Step-by-step cooking guidance for specific recipes4. Database Collections
**MongoDB schema:**
`user_profiles` - User BMR calculations, dietary goals, activity levels`food_entries` - AI-analyzed food intake with nutritional breakdowns`workout_entries` - Exercise logs with calorie burn estimates`recipes` - Traditional recipes with AI-converted quick versions5. AI Integration Guidelines
**When working with LLM features:**
Custom integration is in `/backend/emergentintegrations/` moduleGroq API uses Llama-3.1-8b-instant model for all AI tasksAll AI responses are structured for consistent JSON parsingImplement fallback handling when AI parsing failsCo-pilot chat supports markdown rendering for structured responses**Nutrition calculation rules:**
BMR: Use Mifflin-St Jeor equationDaily calorie target: BMR × activity multiplier ± 500 (based on weight goal)Activity multipliers: Sedentary (1.2), Light (1.375), Moderate (1.55), Very Active (1.725), Extra Active (1.9)6. Frontend State Management
**Key patterns:**
`MealTrayContext` - Global state for recipe selection and cost estimationUser cookbook data persisted in localStorageRecipe and ingredient data loaded from `/frontend/src/data/` JSON filesCo-pilot chat state managed in `App.js` with two-mode interface (general chat / recipe suggestions)7. UI/UX Standards
**Co-pilot chat interface:**
Professional ChatGPT-style message bubbles (user on right, AI on left)Markdown rendering for structured AI responsesClean contrast with accessible color schemesBranded as "Nutrichef AI"Responsive design for mobile and desktop**Styling conventions:**
Tailwind CSS classes for componentsCustom styles in `/frontend/src/App.css` for chat UIMaintain consistent spacing, typography, and color palette8. File Structure Reference
**Critical files:**
`/frontend/src/App.js` - Main React app with co-pilot chat UI`/frontend/src/App.css` - Custom chat interface styling`/frontend/src/data/` - Static recipe and pricing JSON files`/backend/server.py` - FastAPI application with all endpoints`/backend/emergentintegrations/` - Custom Groq LLM wrapper`/backend_test.py` - Comprehensive API test suite`/tests/` - Additional test utilities9. Code Quality Requirements
**Before committing:**
Backend: Run `black`, `isort`, `flake8`, `mypy`Frontend: Run `npm run lint`Tests: Verify `backend_test.py` passesEnsure no breaking changes to API contract10. Common Development Tasks
**Adding a new recipe feature:**
1. Update frontend JSON data files in `/frontend/src/data/`
2. Add API endpoint in `/backend/server.py` with Pydantic model
3. Update frontend components to consume new endpoint
4. Add test cases to `backend_test.py`
**Modifying AI behavior:**
1. Locate prompt templates in `/backend/emergentintegrations/`
2. Update Groq API call parameters (model, temperature, max_tokens)
3. Test with fallback handling for parsing failures
4. Verify structured JSON responses from LLM
**Enhancing co-pilot chat:**
1. Update chat UI in `/frontend/src/App.js` and `App.css`
2. Add new co-pilot endpoint in `/backend/server.py` under `/api/copilot/`
3. Integrate with existing Groq LLM module
4. Test markdown rendering and error states
Important Notes
**Never commit `.env` files** - they contain secrets (MongoDB URI, API keys)**AI responses require error handling** - always implement fallback when parsing fails**BMR calculations must follow Mifflin-St Jeor** - do not use alternative formulas without documentation**Co-pilot chat is branded "Nutrichef AI"** - maintain consistent naming in UI**All API routes use `/api` prefix** - do not create routes without this prefix**Recipe conversion is AI-powered** - traditional → quick version is core feature, test thoroughlyTesting Strategy
1. **Unit tests:** Run `yarn test` in frontend, verify Pydantic models in backend
2. **Integration tests:** Execute `backend_test.py` for full API coverage
3. **Manual testing:** Test co-pilot chat with real cooking questions
4. **AI validation:** Verify structured responses from Groq API with edge cases
Deployment Considerations
Frontend builds to static files via `yarn build`Backend runs on Uvicorn ASGI serverEnsure MongoDB connection string is production-readyConfigure CORS settings for production domainSet appropriate rate limits for AI API calls