Savor

Savor is a real-time food waste intelligence platform for dining operations. It combines camera-based waste detection, inventory/menu sync, historical analytics, student credits tracking, and an ordering assistant into one full-stack application.

What It Does

• Detects food waste from live camera frames using OpenAI vision analysis.
• Prevents duplicate detections using SSIM + cooldown checks.
• Stores events in SQLite and generates aggregate stats.
• Streams live camera and scanner overlays (MJPEG endpoints).
• Tracks student credit scans with barcode/OCR and leaderboard ranking.
• Syncs Stanford dining hall menus (all halls, all meals, 3-day window with fallback) into JSON.
• Produces historical waste inventory datasets for dashboard charts.
• Generates smart-shopping recommendations using linear regression predictions.
• Includes an ordering chat assistant endpoint.
• Supports Whisper transcription and Google TTS for voice experiences.

Tech Stack

• Backend: FastAPI, Uvicorn, SQLite, OpenCV, OpenAI SDK, httpx, BeautifulSoup.
• Frontend: React 19 + Vite, Recharts, Three.js/react-three-fiber.
• Data: JSON inventory files + SQLite event/credits tables.

Repository Layout

savor/
  backend/
    main.py                    # FastAPI app and background loops
    analyzer.py                # GPT-based plate and card analysis
    stanford_inventory.py      # Stanford menu sync + caching
    database.py                # SQLite queries + historical inventory builder
    config.py                  # Central environment config
    requirements.txt           # Python dependencies
  frontend/
    src/App.jsx                # Main UI routes/pages
    src/api.js                 # Backend API wrappers
    package.json               # Frontend scripts/deps
  README.md                    # Single project documentation source

Frontend Pages

• / Live Tracking
• /dashboard Dashboard
• /reports Reports
• /credits Credits
• /smart-shopping Smart Commerce
• /menu Menu Operations
• /inventory Inventory

Backend API

Camera and system

• GET /api/video_feed
• POST /api/camera/start
• POST /api/camera/stop
• POST /api/system/reactivate
• GET /api/status

Waste and inventory analytics

• GET /api/events
• GET /api/stats
• GET /api/inventory-history
• GET /api/inventory
• POST /api/inventory/refresh
• GET /api/smart-shopping

Credits scanner

• GET /api/credits/status
• POST /api/credits/scanner/start
• POST /api/credits/scanner/stop
• GET /api/credits/video_feed
• GET /api/credits/leaderboard

Ordering and voice

• POST /api/order-chat
• POST /api/order-chat/greeting
• POST /api/transcribe
• POST /api/tts

Environment Variables

Create a root .env file (same level as this README).

Required

• OPENAI_API_KEY - required for vision analysis and transcription endpoint.

Optional (backend behavior)

• CAMERA_INDEX (default 0)
• CAMERA_BACKEND (default dshow on Windows, default otherwise; use dshow to avoid MSMF grab warnings)
• CAPTURE_INTERVAL (default 3.0)
• ANALYSIS_FORCE_INTERVAL_SECONDS (default 8.0; forces periodic analysis even without large scene change)
• ANALYSIS_REQUEST_TIMEOUT_SECONDS (default 22.0; max wait per OpenAI vision call)
• SSIM_THRESHOLD (default 0.85)
• COOLDOWN_SECONDS (default 10)
• GOOGLE_TTS_API_KEY (required only if using /api/tts)

Optional (Stanford menu sync)

• STANFORD_DINING_MENU_URL (default https://rdeapps.stanford.edu/dininghallmenu/)
• STANFORD_DINING_HALL (default Wilbur)
• STANFORD_DINING_MEAL (default Lunch)
• STANFORD_DINING_DAY_OFFSET (default 0)

Legacy (currently unused by menu sync)

• BRIGHTDATA_API_KEY
• BRIGHTDATA_BROWSER_WSS

Local Development

1) Backend

cd backend
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
uvicorn main:app --reload --host 0.0.0.0 --port 8000

2) Frontend

cd frontend
npm install
npm run dev

Vite runs on http://localhost:5173 and calls backend http://localhost:8000 through /api/*.

Data and Outputs

• backend/vision_bin.db - waste events + student credits.
• backend/food_inventory.json - aggregate inventory summary.
• backend/food_inventory_historical.json - chart-friendly historical dataset.
• backend/stanford_inventory.json - latest Stanford menu sync payload.

Notes

• Inventory sync now uses direct HTTP form postbacks (no browser automation required).
• /api/inventory/refresh forces a live menu sync and bypasses cache.
• If Stanford does not expose full past dates, sync includes fallback window metadata in JSON.
• Backend startup auto-seeds demo rows if backend/vision_bin.db has zero waste_events, so analytics pages never start from a fully empty DB.