🛒 ValueStop (CheapStop) - Smart City Hackathon Project

Find the cheapest groceries near you in seconds!

CheapStop uses AI (Gemini API) to find nearby stores and live web scraping to compare prices across Walmart, Target, Kroger, CVS, Walgreens, and more. One click to get Google Maps directions to the cheapest store!

🚀 Features

• ✅ Auto Location Detection - Browser geolocation finds stores near you
• ✅ AI-Powered Store Finding - Gemini API locates nearby stores intelligently
• ✅ Live Price Scraping - Real-time price comparison from multiple stores
• ✅ Smart Sorting - Automatically shows cheapest total first
• ✅ Google Maps Integration - One-click directions to your chosen store
• ✅ Cartoon UI - Fun, engaging, hackathon-ready design
• ✅ No Database Required - All live data, perfect for demos

🛠️ Tech Stack

Backend

• Node.js + Express - API server
• Cheerio - Fast HTML parsing for web scraping
• Gemini API - AI-powered store location finding
• Axios - HTTP requests

Frontend

• React + Vite - Fast, modern UI
• TailwindCSS - Cartoon-style design system
• Geolocation API - Browser location access

📋 Prerequisites

• Node.js 18+ installed
• Gemini API key (get from Google AI Studio)
• Google Maps API key (for directions)

⚡ Quick Start

1. Clone & Install

```bash cd cheapstop npm run install:all ```

2. Setup Environment Variables

Create `server/.env` file:

```env GEMINI_API_KEY=your_gemini_api_key_here GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here PORT=3001 NODE_ENV=development ```

Get your API keys:

• Gemini API: https://makersuite.google.com/app/apikey
• Google Maps API: https://console.cloud.google.com/apis/credentials

3. Run the App

```bash npm run dev ```

This starts:

• Backend: http://localhost:3001
• Frontend: http://localhost:5173

4. Use the App

1. Open http://localhost:5173
2. Allow location access when prompted
3. Enter items (e.g., "eggs, milk, bread")
4. Hit Search!
5. Click "Go" on any store to get directions

📁 Project Structure

``` cheapstop/ ├── server/ │ ├── index.js # Express server │ ├── routes/ │ │ └── search.js # Search endpoint │ ├── services/ │ │ ├── gemini.js # Gemini AI integration │ │ └── scraper.js # Web scraping logic │ └── .env.example # Environment template ├── client/ │ ├── src/ │ │ ├── App.jsx # Main app component │ │ ├── components/ │ │ │ ├── SearchBar.jsx │ │ │ ├── StoreCard.jsx │ │ │ └── LocationPrompt.jsx │ │ └── index.css # Tailwind + custom styles │ └── tailwind.config.js # Cartoon theme config └── package.json # Root workspace config ```

🎨 UI Features

• Cartoon Design System - Bold borders, playful shadows, bright colors
• Responsive Layout - Works on mobile and desktop
• Animations - Bounce-in effects, wiggle buttons
• Loading States - Clear feedback during search
• Error Handling - User-friendly error messages

🔧 API Endpoints

POST /api/search

Search for items across stores.

Request: ```json { "latitude": 33.7490, "longitude": -84.3880, "items": ["eggs", "milk", "bread"] } ```

Response: ```json { "query": "eggs, milk, bread", "userLocation": { "latitude": 33.7490, "longitude": -84.3880 }, "totalStores": 6, "stores": [ { "storeId": "walmart-atl-midtown", "storeName": "Walmart Supercenter", "address": "1105 Howell Mill Rd NW, Atlanta, GA 30318", "distanceMiles": 2.1, "latitude": 33.7890, "longitude": -84.3946, "items": [ { "name": "Eggs", "price": 2.98, "inStock": true }, { "name": "Milk", "price": 3.47, "inStock": true }, { "name": "Bread", "price": 1.98, "inStock": true } ], "totalPrice": 8.43, "itemsFound": 3 } ], "bestDeal": { /* cheapest store */ }, "timestamp": "2025-11-15T10:30:00.000Z" } ```

🎯 How It Works

1. User enters location → Browser geolocation API
2. User searches items → Frontend sends to backend
3. Backend calls Gemini → AI finds nearby stores with coords
4. Backend scrapes stores → Cheerio extracts prices (or uses mock data)
5. Backend returns sorted results → Cheapest first
6. User clicks "Go" → Google Maps opens with directions

🏆 Hackathon Demo Script

1. Intro: "I'm at [location], need eggs and milk"
2. Search: Type items, hit search
3. Show Results: "Found 6 stores, Walmart is cheapest at $8.43"
4. Navigate: Click "Go" → Google Maps opens with route
5. Wow Factor: "Live prices, AI location finding, one-click navigation!"

🔐 Security Notes

• Never commit .env files
• API keys are server-side only
• CORS is enabled for local development
• For production, add proper CORS restrictions

🐛 Troubleshooting

Location not working?

• Check browser permissions
• Try HTTPS (required for geolocation in production)

Scraping fails?

• Uses fallback mock data automatically
• Some stores block scraping (expected)

Gemini API errors?

• Check API key in .env
• Falls back to hardcoded Atlanta stores

📝 License

Built for Smart City Track EMORY HACKS Hackathon 2025 FALL

🤝 Contributing

This is a hackathon project! Feel free to fork and improve.

🎉 Let's Win This!

Made with ❤️ and ☕ by your team!