# JAM Members Club — Loyalty Program
## Project Plan v1.0 | May 2026

---

## 1. Business Overview

**Client:** JAM by Chef Sunil
**Location:** 1 Palmer St, South Townsville QLD 4810, Australia
**ABN:** 55404568757
**Contact:** manager@jamcorner.com.au | (07) 4721 4900
**Website:** jamcorner.com.au

### Business Goal
Build a digital loyalty program platform that:
- Rewards repeat diners and encourages higher spend frequency
- Segments members into three tiers (Invited, Indulged, Limitless) based on real visit and spend data
- Gives the JAM admin team full control to manage members, record points, and oversee tier progressions
- Provides members with a clear, self-service portal to track their points, tier status, and benefits
- Drives long-term customer retention through personalised, tiered rewards

---

## 2. Tech Stack

| Layer | Technology |
|---|---|
| Backend | PHP 8.2 + Laravel 11 |
| Frontend | Blade templates + Tailwind CSS + Alpine.js |
| Database | MySQL 8.0 |
| Auth | Laravel Breeze / Fortify (role-based) |
| Email | Laravel Mail (SMTP — configurable) |
| Hosting | Shared hosting (cPanel compatible) |
| Queue | Laravel Queue (database driver for shared hosting) |
| Storage | Local disk (shared hosting) |

---

## 3. User Roles

| Role | Description |
|---|---|
| **Super Admin** | Full access — manages admins, members, points, tiers, system settings |
| **Admin** | Manages members, points entry/deduction, tier actions |
| **Member** | Self-service portal — view tier, points, history, profile |

---

## 4. Membership Tiers (as per T&C)

| | Invited | Indulged | Limitless |
|---|---|---|---|
| Min spend/visit | $100 | $150 | $200 |
| Visit frequency | 1 per 3 months | 1 per month | 2 per month (or 15/year) |
| Points to maintain tier | 250+ in 3 months | 500+ in 3 months | 1000+ in 3 months |
| Points accrual | $1 = 1 point | $1 = 1 point | $1 = 1 point |
| Points expiry | Annual (enrolment anniversary) | Annual | Annual |
| Tier assessment | Quarterly | Quarterly | Quarterly |

**Note:** Points are used solely for tier assessment — they hold no cash/redemption value per the T&C.

---

## 5. Feature Modules

---

### 5.1 Member Portal (Public-facing)

#### Authentication
- Self-registration form (name, DOB, email, phone, password)
- Email verification on signup
- Login / logout
- Password reset via email
- Age validation (18+ only, based on DOB)

#### Member Dashboard
- Current tier badge (Invited / Indulged / Limitless)
- Total points balance
- Points progress bar toward next tier threshold
- Visit count summary (current period)
- Next tier assessment date
- Quick view of active benefits at current tier
- Points expiry date (next anniversary)

#### Points History
- Chronological log: date, description (e.g. "Visit recorded — $150 spend"), points added/deducted, running balance
- Admin note visible to member (optional, admin-controlled)

#### Benefits Page
- Full breakdown of benefits for current tier
- Greyed-out view of higher tier benefits (to encourage upgrade)

#### Profile Management
- Update name, phone, email (email change triggers re-verification)
- View membership number
- View enrolment date
- Cannot self-delete account (must contact JAM)

---

### 5.2 Admin Panel

#### Admin Dashboard (Overview)
- Total active members (by tier)
- Points issued today / this week / this month
- Members due for tier review (flagged)
- Recently inactive members
- New registrations (last 7 days)
- Quick-action buttons: Add Points, View Member, Create Member

#### Member Management
- List all members with search, filter (by tier, status, name, email)
- **Create new member** (admin-initiated registration)
- **View member profile** — full details, tier history, points log, visit history
- **Edit member details**
- **Deactivate member** (soft disable — member cannot log in, data retained)
- **Suspend member** (temporary — with reason and optional end date)
- **Reactivate member**
- **Export member list** (CSV)

#### Points Management
- **Add points** to a member — enter amount, visit date, spend amount, optional note
- **Deduct points** from a member — enter amount, reason/note
- All point transactions logged with admin who performed the action + timestamp
- Cannot add points to deactivated/suspended members

#### Tier Management
- View all members with current tier and tier assessment status
- **Auto-suggest toggle** (system-wide on/off) — when ON, system automatically flags members eligible for tier upgrade based on spend/visit data
- **Manual tier upgrade/downgrade button** per member (with required reason note)
- Quarterly assessment view — lists all members due for review with recommended action
- **Tier change log** — full history of tier movements per member

#### Visit Log
- Each time admin adds points, a visit record is created
- View visit history per member (date, spend, points awarded, admin who entered)

#### Admin User Management (Super Admin only)
- Create new admin accounts (name, email, role: Admin or Super Admin)
- Deactivate/reactivate admin accounts
- View admin activity log (who did what, when)

#### Notifications & Email
- Triggered emails to members:
  - Welcome email on registration
  - Points added (with new balance)
  - Points deducted (with new balance and reason)
  - Tier upgraded (congratulations + new benefits)
  - Tier downgraded (notification + what's needed to re-qualify)
  - Points expiry reminder (30 days before anniversary)
  - Membership inactive warning
- Admin can toggle email notifications on/off per event type in settings

#### System Settings (Super Admin only)
- Restaurant name, contact details
- SMTP email configuration
- Tier thresholds (editable in case T&C changes)
- Points accrual rate
- Quarterly assessment schedule

---

## 6. Database Schema (Overview)

### `users` — member accounts
- id, name, dob, email, phone, password
- membership_number (auto-generated)
- status (active / inactive / suspended / lapsed)
- enrolled_at, points_expiry_at
- email_verified_at, created_at, updated_at

### `tiers` — tier definitions (configurable)
- id, name (invited/indulged/limitless), min_spend_per_visit, visit_frequency_months, points_threshold_3months, display_order

### `member_tiers` — tier history per member
- id, user_id, tier_id, assigned_at, assigned_by (admin_id), reason, is_current

### `points_transactions` — every point movement
- id, user_id, type (credit/debit), amount, balance_after
- description, visit_date, spend_amount, admin_id, created_at

### `visits` — visit records (linked to points transactions)
- id, user_id, visit_date, spend_amount, points_awarded, recorded_by (admin_id), created_at

### `admins` — admin accounts
- id, name, email, password, role (admin/super_admin)
- status (active/inactive), created_at, last_login_at

### `admin_activity_log` — audit trail
- id, admin_id, action, target_type, target_id, meta (JSON), created_at

### `tier_assessments` — quarterly review records
- id, user_id, assessed_at, assessed_by (admin_id / system), previous_tier_id, new_tier_id, reason, auto_suggested

### `notifications` — email notification log
- id, user_id, type, subject, sent_at, status

---

## 7. Development Phases

---

### Phase 1 — Foundation (Week 1–2)
- Laravel project setup (routing, auth scaffolding, role middleware)
- Database migrations and seeders (tiers, super admin account)
- Membership registration flow (public form + email verification)
- Member login and basic dashboard skeleton
- Admin login and basic panel skeleton

### Phase 2 — Core Admin Functions (Week 3–4)
- Member management (list, create, edit, deactivate, suspend, reactivate)
- Points add/deduct with full transaction log
- Visit recording linked to points entry
- Points history view (admin + member)
- Admin user management (Super Admin)

### Phase 3 — Tier Engine (Week 5)
- Tier assessment logic (auto-evaluate based on visits + spend + points)
- Auto-suggest system with admin toggle
- Manual tier override with reason log
- Quarterly assessment dashboard view
- Tier history per member

### Phase 4 — Member Portal (Week 6)
- Member dashboard (tier, points, progress bar, benefits)
- Benefits display per tier
- Points history page (member view)
- Profile management

### Phase 5 — Notifications & Email (Week 7)
- Email templates (welcome, points added/deducted, tier change, expiry reminder)
- Queue setup for email dispatch
- Admin notification settings panel
- Points expiry scheduler (annual, runs via cron)

### Phase 6 — Polish & Deploy (Week 8)
- Responsive design (mobile-friendly)
- Branding applied (logo, colors — pending client assets)
- Input validation and error handling throughout
- Security hardening (CSRF, rate limiting on login, XSS protection)
- Shared hosting deployment (cPanel, `.env` config)
- UAT (User Acceptance Testing) with client

---

## 8. Security Considerations
- All passwords hashed (bcrypt via Laravel)
- Role-based middleware on all admin routes
- CSRF protection on all forms
- Rate limiting on login (prevent brute force)
- Admin activity log for full auditability
- Email verification on member registration
- Soft deletes only — no hard data deletion

---

## 8.5 Design Direction (Reference Screenshots Provided)

### Visual Style
- **Theme:** Dark luxury — near-black background (`#0d0d0d` / `#111`) with gold/amber accent (`#D4B84A`)
- **Typography:** Serif display font (e.g. Playfair Display) for headings; condensed uppercase sans-serif for labels/nav
- **Feel:** Fine-dining, heritage, premium — consistent with JAM Corner brand

### Member Portal Design
- **Login page:** Split-screen — left half: full restaurant photo + brand tagline + feature bullet points; right half: auth form (Login/Signup toggle, email, password, CTA button)
- **Dashboard:** Welcome greeting, prominent points card (tier badge, points total, progress to next tier, expiry date), recent ledger entries sidebar, benefits/content section below
- **Points Ledger:** Full-width transaction table (date, description, tier badge, +/- amount), filter tabs (All / Credit / Debit), tier progress widget on right rail
- **Benefits page:** Card grid per tier showing available benefits

### Admin Panel Design
- **Separate login page** (distinct URL from member login, e.g. `/admin/login`)
- **Sidebar navigation:** Logo top-left, nav items with icons (Dashboard, Members, Points, Tiers, Admins, Settings)
- **Directory/Member list:** Stats summary cards at top (total points issued, total members, active members), searchable member table with tier badge, points total, action icons (edit, view, suspend)
- **Dark card components** with subtle gold borders/highlights

### Separate Systems
- Member portal: `/` or `/member`
- Admin panel: `/admin` — completely separate layout, auth guard, and session

### Note on Points Redemption
The reference design (Image 4) shows a "Redeem" section — **this is excluded** from the build. Per the T&C, points have no monetary value and cannot be redeemed. The Points Ledger is view-only history for members.

---

## 9. Pending / To Be Confirmed
- [ ] Branding assets (logo, colors, fonts) — client to provide reference screenshots
- [ ] Domain / subdomain for the portal (e.g. members.jamcorner.com.au)
- [ ] Shared hosting provider details (for deployment config)
- [ ] SMTP credentials for email (or use a service like Mailgun/SMTP2GO)
- [ ] Whether members can log in via phone number or email only

---

## 10. Out of Scope (v1.0)
- Online booking integration
- POS system integration
- Mobile app
- QR code check-in at restaurant
- Points redemption for monetary value (excluded per T&C)
- Member-to-member referral system