Project: HealthifyCart Demo

# Project: HealthifyCart Demo

## Tech Stack

- **Language:** JavaScript (ES modules)
- **Framework:** React 19 + Vite 8
- **Styling:** Tailwind CSS dependency with custom CSS in src/index.css
- **Animation:** motion/react (Motion v12)
- **Icons:** Lucide React
- **Testing:** No automated test suite configured yet
- **Linter/Formatter:** ESLint 9 (prettier)
- **Database:** None (frontend-only demo)
- **Package Manager:** pnpm (pnpm-lock.yaml present)

## Project Conventions

- **File naming:** PascalCase for UI components/screens, camelCase for data/api/utils modules
- **Test location:** No test directories currently; add tests near feature code if introduced
- **Import style:** Relative imports inside src
- **Error handling:** Fallback-first behavior for AI calls, shape validation via src/utils/mealValidation.js, user feedback via toast messages
- **State management:** App-level useState/useMemo/useEffect with prop-driven screen components (no Redux/Zustand)
- **Data flow:** UI text/prices/messages should come from mealData payload and constants, not hardcoded component literals

## Commands Reference

- **Install dependencies:** pnpm install
- **Run tests:** Not configured
- **Run single test file:** Not configured
- **Lint:** pnpm lint
- **Format:** pnpm format
- **Build:** pnpm build
- **Dev server:** pnpm dev
- **Preview build:** pnpm preview

## Architecture Notes

- src/App.jsx — Root orchestrator for screen routing, generated meal state, pantry state, compare/swap state, and placeholder confirm handoff
- src/screens/MealPlanScreen.jsx — Screen 1 (meal plan)
- src/screens/PantryCheckScreen.jsx — Screen 2 (pantry toggles + estimate)
- src/screens/PriceCompareScreen.jsx — Screen 3 (platform comparison + swap + budget projection)
- src/api/config.js — OpenRouter env/config
- src/api/generateMeal.js — AI meal generation request + parsing + validation
- src/data/fallbackMeal.js — Offline-safe fallback payload
- src/data/constants.js — Budget and platform constants
- src/components/ — Reusable UI blocks (BudgetBar, RiaBubble, PlatformPrice, SwapCard, etc.)
- src/styles/theme.js — Theme tokens and UI constants
- src/utils/mealValidation.js — AI response shape validation
- plans/ — Plan, phase completion, and closeout artifacts

## Plan Directory

Plans are stored in: plans/

## Project-Specific Agent Instructions

### For the implementer:

- Keep demo flow resilient without network: never break fallback-only mode when VITE_OPENROUTER_KEY is absent.
- Keep state in App unless a strong reason exists; avoid adding external state libraries.
- Use existing platform constants and helper patterns for price math and selection validity.
- Preserve mobile-frame-first UX and existing motion patterns.
- Do not add real commerce, payment, or delivery integrations in this repo scope.

### For the reviewer:

- Verify fallback mode still works when API key is missing.
- Verify no meal-specific literals are hardcoded where mealData should be used.
- Verify cart total, savings, and budget projection calculations remain mathematically correct.
- Verify screen navigation and state persistence across back/forward transitions.
- Require pnpm lint (and pnpm build for larger UI/state changes) before approval.

## Known Gotchas

- README.md still describes an earlier phase; rely on code and plans/ for current implementation scope.
- .env exists locally; VITE_OPENROUTER_KEY is optional for demo continuity and triggers fallback mode when missing.
- OpenRouter model/settings are defined in src/api/config.js; keep env-driven configuration there.
- Screen keys and ordering are centralized in src/App.jsx; update SCREEN_ORDER when adding routes.
- Platform selection and swap acceptance state use ingredient-id string keys; preserve this mapping pattern.
- There is no automated test harness yet, so lint/build and targeted manual flow checks are currently required for confidence.