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

Development with Podman Containers

# 1. Start PostgreSQL and Redis containers
podman start flyer-crawler-postgres flyer-crawler-redis

# 2. Install dependencies (first time only)
npm install

# 3. Run in development mode
npm run dev

The application will be available at:

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

See docs/getting-started/INSTALL.md for detailed setup instructions including:

• Podman Desktop installation
• Container configuration
• Database initialization
• Environment variables

Testing

IMPORTANT: All tests must run inside the dev container for reliable results.

# Run all tests in container
podman exec -it flyer-crawler-dev npm test

# Run only unit tests
podman exec -it flyer-crawler-dev npm run test:unit

# Run only integration tests
podman exec -it flyer-crawler-dev npm run test:integration

See docs/development/TESTING.md for testing guidelines.

---

Documentation

Core Documentation

Document	Description
📚 Documentation Index	Navigate all documentation
⚙️ Installation Guide	Local development setup with Podman
🏗️ Architecture Overview	System design, database, authentication
💻 Development Guide	Testing, debugging, code patterns
🚀 Deployment Guide	Production setup, NGINX, PM2
🤖 AI Agent Guides	Working with Claude Code subagents

Quick References

Document	Description
CLAUDE.md	AI agent project instructions
CONTRIBUTING.md	Development workflow, PR process
Architecture Decision Records	Design decisions and rationale

---

Environment Variables

Production/Test: Uses Gitea CI/CD secrets injected during deployment (no local .env files)

Dev Container: Uses .env.local file which overrides the default DSNs in compose.dev.yml

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 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]