# PriceCompare Botswana

**Grocery Price Comparison Platform**

A product-level price search engine where shoppers search one grocery item and instantly see its price across every participating store and branch in Botswana.

---

## 📁 Project Structure

```
pricecompare/
├── database/
│   └── schema.sql              # Full MySQL schema
├── api/                        # REST API (PHP)
│   ├── config.php              # Environment & CORS config
│   ├── db.php                  # Database singleton
│   ├── auth.php                # JWT auth & helpers
│   ├── auth-endpoint.php       # Login/register endpoints
│   ├── search.php              # Product search with location
│   ├── products.php            # Product detail + history
│   ├── prices.php              # Manual price entry (admin)
│   ├── watchlist.php           # User watchlists
│   ├── shopping-lists.php      # Basket comparison
│   ├── alerts.php              # Price drop alerts
│   ├── receipts.php            # Receipt upload (consumer)
│   ├── promotions.php          # Promotions CRUD
│   ├── stats.php               # Admin dashboard stats
│   ├── product-aliases.php     # Matching queue management
│   ├── scraper-runs.php        # Scraper history
│   ├── chains.php              # Chain config
│   ├── branches.php            # Branch listings
│   ├── users-admin.php         # User management
│   ├── receipts-admin.php      # Receipt moderation
│   ├── store-stats.php         # Store dashboard stats
│   └── store-products.php      # Store product listings
├── admin/                      # Admin/Ops Console
│   ├── index.html
│   ├── styles.css
│   └── app.js
├── store-dashboard/            # Store Partner Portal
│   ├── index.html
│   ├── styles.css
│   └── app.js
├── scrapers/                   # Data ingestion
│   ├── base_scraper.php        # Abstract scraper class
│   ├── runner.php              # Daily cron runner
│   └── adapters/               # Per-chain scrapers
│       └── example_adapter.php
└── mobile/                     # Ionic/Capacitor app (TODO)
```

---

## 🚀 Setup Instructions

### 1. Database
```bash
mysql -u root -p < database/schema.sql
```

### 2. Environment Variables
Create `.env` or set these in your host:
```
DB_HOST=localhost
DB_NAME=pricecompare
DB_USER=pricecompare_user
DB_PASS=your_secure_password
JWT_SECRET=256-bit-random-string
FCM_SERVER_KEY=your_firebase_key
OCR_PROVIDER=tesseract
```

### 3. Web Server
- Point document root to `pricecompare/`
- Ensure `uploads/` directory is writable (775)
- Configure SSL certificate

### 4. Cron (Scraper)
Add to crontab for daily 2 AM runs:
```
0 2 * * * /usr/bin/php /path/to/pricecompare/scrapers/runner.php >> /var/log/pricecompare-scraper.log 2>&1
```

### 5. Admin Access
Default credentials (change immediately):
- Email: `admin@pricecompare.co.bw`
- Password: `admin123`

---

## 🔌 API Endpoints

| Endpoint | Method | Auth | Description |
|----------|--------|------|-------------|
| `/api/auth-endpoint.php?action=register` | POST | No | User registration |
| `/api/auth-endpoint.php?action=login` | POST | No | User login |
| `/api/auth-endpoint.php?action=admin-login` | POST | No | Admin login |
| `/api/search.php?q=cerevita` | GET | No | Search products |
| `/api/products.php/{id}` | GET | No | Product detail + history |
| `/api/prices.php` | POST | Admin | Manual price entry |
| `/api/watchlist.php` | GET/POST/DELETE | User | Watchlist management |
| `/api/shopping-lists.php` | GET/POST/DELETE | User | Basket comparison |
| `/api/alerts.php` | GET/PUT | User | Price alerts |
| `/api/receipts.php` | POST | User | Upload receipt |
| `/api/promotions.php` | GET/POST | Store/Admin | Promotions |

---

## 🏗️ Build Sequence Status

- [x] Foundation — DB schema, chain config, scraper framework, manual entry, core search API, matching pipeline
- [x] Admin Console — Full ops dashboard
- [x] Store Partner Dashboard — Promotions, analytics, price discrepancy alerts
- [ ] Consumer App — Ionic/Capacitor build (next session)
- [ ] Engagement Layer — Push notifications, receipt OCR pipeline
- [ ] Scraper Adapters — Per-chain implementations

---

## 🔐 Security Checklist

- [x] JWT-based auth with expiration
- [x] Object-level authorization (users can only access own data)
- [x] Input sanitization on all endpoints
- [x] XSS prevention via htmlspecialchars
- [x] CORS configured for known origins
- [x] Rate limiting ready (implement per-IP in production)
- [ ] SQL injection prevention via prepared statements ✅
- [ ] File upload validation ✅

---

## 📱 Mobile App

The consumer mobile app will be built with **Ionic + Capacitor** (recommended over React Native for PHP/web teams). Features:
- Barcode scanning (ZXing)
- Push notifications (FCM)
- Receipt camera upload
- Offline search cache

---

## 💰 Monetization

1. **Promotions/Ads** — Store partners pay for featured placement (self-serve dashboard ready)
2. **Future:** Store subscription tiers with analytics
3. **Future:** Affiliate commissions on click-throughs

---

## 📝 Open Items

- [ ] Final chain list (scrape vs. manual)
- [ ] Hosting decision — VPS-for-scraper vs. cPanel cron support
- [ ] Hybrid framework sign-off — Ionic/Capacitor vs. React Native
- [ ] OCR provider — Google Vision vs. Tesseract
- [ ] Working product name
- [ ] Store partner login system (currently placeholder)

---

**Built for Botswana. Currency: BWP. Market: Gaborone-first, national rollout.**