tomsjavajive/README.md

# Tom's Java Jive - E-commerce Coffee Shop

A complete e-commerce platform built with **PHP 8.4** and **MySQL 8.0** for cPanel hosting.

## Quick Download

**ZIP File:** [tomsjavajive-php.zip](https://tomsjavajive.com/tomsjavajive-php.zip)

## Features

### Storefront
- 🛒 Shopping cart with session management
- 📦 Product catalog with categories, search, and filtering
- 💳 Checkout with multiple payment options
- 📱 PWA support (installable, offline capable)
- 👤 Customer accounts with order history

### Admin Panel
- 📊 Dashboard with sales overview
- 📈 Advanced analytics with charts
- 🛍️ Product management (CRUD)
- 📋 Order management
- 💰 POS (Point of Sale) system
- 👥 Customer management with wallet
- ⭐ Review moderation
- 🎁 Gift cards & coupons
- ✉️ Email campaigns
- 📦 Inventory tracking
- 🚚 Shipping configuration
- 💳 Payment settings
- 👤 Admin user management

### Integrations (Placeholder Keys - Configure in Admin)
- 📧 **SendGrid** - Transactional emails
- 📱 **Twilio** - SMS notifications
- 🔔 **Push Notifications** - Web push
- 🏆 **Loyalty Program** - 4-tier rewards system
- 💳 **Stripe Payments** - cURL-based (no Composer needed)

## Installation

### Requirements
- PHP 8.0+ (tested on 8.4.19)
- MySQL 8.0+
- Apache with mod_rewrite

### Steps

1. **Upload Files**
   - Extract the ZIP to your `public_html` folder
   - Or upload via FTP

2. **Create Database**
   ```
   Log into phpMyAdmin
   Create a new database (e.g., `tomsjavajive`)
   ```

3. **Import Schema**
   - Go to phpMyAdmin > Import
   - Select `install/schema.sql`
   - Click "Go"

4. **Run Migrations** (for full features)
   - Import `install/migration_v2.sql`
   - Import `install/migration_v3.sql`

5. **Configure Database**
   - Edit `config/database.php`:
   ```php
   define('DB_HOST', 'localhost');
   define('DB_NAME', 'your_database_name');
   define('DB_USER', 'your_username');
   define('DB_PASS', 'your_password');
   ```

6. **Create Admin User**
   - `create-admin.php` and the seeded default admin account have been removed —
     insert your own row into `admin_users` directly (via phpMyAdmin/CLI) with a
     bcrypt hash from `password_hash($password, PASSWORD_BCRYPT, ['cost' => 12])`.
     Never leave a well-known default password (e.g. `admin123!`) in place.

7. **Configure Site URL**
   - Edit `config/config.php`:
   ```php
   define('SITE_URL', 'https://yoursite.com');
   define('SITE_NAME', "Tom's Java Jive");
   ```

8. **Delete Installation Files** (Security)
   ```
   Delete: create-admin.php
   Delete: install/ folder (optional, keep for reference)
   ```

## Directory Structure

```
/
├── admin/              # Admin panel pages
│   ├── assets/         # Admin CSS/JS
│   ├── includes/       # Admin header/footer
│   └── *.php          # Admin pages
├── account/           # Customer portal
│   └── includes/      # Account layout
├── api/               # AJAX endpoints
├── assets/            # Frontend assets
│   ├── css/
│   ├── js/
│   ├── images/
│   └── icons/
├── config/            # Configuration files
├── includes/          # Core PHP files
│   ├── auth.php       # Authentication
│   ├── db.php         # Database connection
│   ├── email.php      # SendGrid integration
│   ├── sms.php        # Twilio integration
│   ├── push.php       # Push notifications
│   ├── loyalty.php    # Loyalty program
│   └── functions.php  # Helper functions
├── install/           # Installation files
│   ├── schema.sql     # Main database schema
│   ├── migration_v2.sql
│   └── migration_v3.sql
├── manifest.json      # PWA manifest
├── sw.js             # Service worker
└── *.php             # Storefront pages
```

## Configuring Integrations

### SendGrid (Email)
1. Get API key from https://app.sendgrid.com/settings/api_keys
2. Admin > Settings > Integrations
3. Enter API key, from email, and from name

### Twilio (SMS)
1. Get credentials from https://console.twilio.com/
2. Admin > Settings > Integrations
3. Enter Account SID, Auth Token, and Phone Number

### Push Notifications
1. Generate VAPID keys at https://web-push-codelab.glitch.me/
2. Admin > Settings > Integrations
3. Enter Public and Private keys

## Loyalty Program Tiers

| Tier | Points Required | Multiplier | Key Benefits |
|------|----------------|------------|--------------|
| Bronze Bean | 0 | 1x | Birthday reward |
| Silver Roast | 500 | 1.25x | Free shipping $25+ |
| Gold Blend | 1,500 | 1.5x | Free all shipping |
| Platinum Reserve | 5,000 | 2x | VIP benefits |

**Redemption:** 100 points = $1 wallet credit

## Security Notes

- All passwords are hashed with `password_hash()`
- PDO prepared statements prevent SQL injection
- CSRF protection on forms
- XSS prevention via `htmlspecialchars()`
- Session-based authentication

## Stripe Payment Integration

The app includes a **cURL-based Stripe integration** that works without Composer:

### Features
- **PaymentIntent API** - Inline card element payments
- **Checkout Sessions** - Hosted Stripe payment page (redirect)
- **Webhooks** - Payment confirmation handlers
- **Demo Mode** - Works without API keys for testing

### Setup
1. Get your API keys from https://dashboard.stripe.com/apikeys
2. Edit `config/config.php`:
   ```php
   define('STRIPE_SECRET_KEY', 'sk_live_your_key');
   define('STRIPE_PUBLISHABLE_KEY', 'pk_live_your_key');
   define('STRIPE_WEBHOOK_SECRET', 'whsec_your_secret');
   ```

### Webhook Setup
1. Stripe Dashboard > Developers > Webhooks
2. Add endpoint: `https://yoursite.com/api/webhook.php`
3. Select events: `payment_intent.succeeded`, `checkout.session.completed`

### Files
- `includes/stripe.php` - Core Stripe API class (cURL-based)
- `api/create-payment-intent.php` - Create PaymentIntent
- `api/create-checkout-session.php` - Create Checkout Session
- `api/payment-status.php` - Poll payment status
- `api/webhook.php` - Handle Stripe webhooks

## Support

For issues or feature requests, contact your developer.

## License

Proprietary - All rights reserved.

---

**Version:** 2.0  
**Last Updated:** December 2025