# Flyer Crawler - Grocery AI Analyzer

Flyer Crawler is a web application that uses Google Gemini AI to extract, analyze, and manage data from grocery store flyers. Users can upload flyer images or PDFs, and the application automatically identifies items, prices, and sale dates, storing structured data in a PostgreSQL database for historical analysis, price tracking, and personalized deal alerts.

**Our mission**: Help people save money by finding good deals that are only advertised in store flyers. The app makes uploading flyers as easy and accurate as possible, and matches sales to users' needs.

---

## Features

- **AI-Powered Data Extraction**: Upload PNG, JPG, or PDF flyers to automatically extract store names, sale dates, and detailed item lists with prices and quantities
- **Bulk Import**: Process multiple flyers at once with summary reports of successes, skips (duplicates), and errors
- **Personalized Watchlist**: Create a watchlist of specific grocery items you want to track
- **Active Deal Alerts**: See current sales on your watched items from all valid flyers
- **Price History Charts**: Visualize price trends of watched items over time
- **Shopping List Management**: Create multiple shopping lists, add items from flyers or your watchlist, and track purchased items
- **User Authentication**: Secure sign-up, login, profile management, and account deletion
- **Dynamic UI**: Responsive interface with dark mode and metric/imperial unit systems

---

## Tech Stack

| Layer          | Technology                          |
| -------------- | ----------------------------------- |
| Frontend       | React, TypeScript, Tailwind CSS     |
| AI             | Google Gemini API (`@google/genai`) |
| Backend        | Node.js, Express                    |
| Database       | PostgreSQL with PostGIS             |
| Authentication | Passport.js (Google, GitHub OAuth)  |
| Charts         | Recharts                            |

---

## Quick Start

```bash
# Install dependencies
npm install

# Run in development mode
npm run dev
```

See [INSTALL.md](INSTALL.md) for detailed setup instructions.

---

## Documentation

| Document                               | Description                              |
| -------------------------------------- | ---------------------------------------- |
| [INSTALL.md](INSTALL.md)               | Local development setup with Podman      |
| [DATABASE.md](DATABASE.md)             | PostgreSQL setup, schema, and extensions |
| [AUTHENTICATION.md](AUTHENTICATION.md) | OAuth configuration (Google, GitHub)     |
| [DEPLOYMENT.md](DEPLOYMENT.md)         | Production server setup, NGINX, PM2      |

---

## Environment Variables

This project uses environment variables for configuration (no `.env` files). Key variables:

| Variable                                     | Description                      |
| -------------------------------------------- | -------------------------------- |
| `DB_HOST`                                    | PostgreSQL host                  |
| `DB_USER_PROD`, `DB_PASSWORD_PROD`           | Production database credentials  |
| `DB_USER_TEST`, `DB_PASSWORD_TEST`           | Test database credentials        |
| `DB_DATABASE_PROD`, `DB_DATABASE_TEST`       | Database names                   |
| `JWT_SECRET`                                 | Authentication token signing key |
| `VITE_GOOGLE_GENAI_API_KEY`                  | Google Gemini API key            |
| `GOOGLE_MAPS_API_KEY`                        | Google Maps Geocoding API key    |
| `REDIS_PASSWORD_PROD`, `REDIS_PASSWORD_TEST` | Redis passwords                  |

See [INSTALL.md](INSTALL.md) for the complete list.

---

## Scripts

| Command              | Description                      |
| -------------------- | -------------------------------- |
| `npm run dev`        | Start development server         |
| `npm run build`      | Build for production             |
| `npm run start:prod` | Start production server with PM2 |
| `npm run test`       | Run test suite                   |
| `npm run seed`       | Seed development user accounts   |

---

## License

[Add license information here]
