# Loyalty Module Phase 2: Admin & Store Interfaces ## Executive Summary This document outlines the plan for building admin and store interfaces for the Loyalty Module, along with detailed user journeys for stamp-based and points-based loyalty programs. The design follows market best practices from leading loyalty platforms (Square Loyalty, Toast, Fivestars, Belly, Punchh). --- ## Part 1: Interface Design ### 1.1 Store Dashboard (Retail Store) #### Main Loyalty Dashboard (`/store/loyalty`) ``` ┌─────────────────────────────────────────────────────────────────┐ │ 🎯 Loyalty Program [Setup] │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────┐│ │ │ 1,247 │ │ 892 │ │ 156 │ │ €2.3k ││ │ │ Members │ │ Active │ │ Redeemed │ │ Saved ││ │ │ Total │ │ 30 days │ │ This Month │ │ Value ││ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────┘│ │ │ │ ┌─────────────────────────────────────────────────────────────┐│ │ │ 📊 Activity Chart (Last 30 Days) ││ │ │ [Stamps Issued] [Rewards Redeemed] [New Members] ││ │ │ ═══════════════════════════════════════════════ ││ │ └─────────────────────────────────────────────────────────────┘│ │ │ │ ┌─────────────────────────┐ ┌─────────────────────────────┐ │ │ │ 🔥 Quick Actions │ │ 📋 Recent Activity │ │ │ │ │ │ │ │ │ │ [➕ Add Stamp] │ │ • John D. earned stamp #8 │ │ │ │ [🎁 Redeem Reward] │ │ • Marie L. redeemed reward │ │ │ │ [👤 Enroll Customer] │ │ • Alex K. joined program │ │ │ │ [🔍 Look Up Card] │ │ • Sarah M. earned 50 pts │ │ │ │ │ │ │ │ │ └─────────────────────────┘ └─────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` #### Stamp/Points Terminal (`/store/loyalty/terminal`) **Primary interface for daily operations - optimized for tablet/touchscreen:** ``` ┌─────────────────────────────────────────────────────────────────┐ │ 🎯 Loyalty Terminal │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌───────────────────────────────────────────────────┐ │ │ │ │ │ │ │ 📷 SCAN QR CODE │ │ │ │ │ │ │ │ [Camera Viewfinder Area] │ │ │ │ │ │ │ │ or enter card number │ │ │ │ ┌─────────────────────────┐ │ │ │ │ │ Card Number... │ │ │ │ │ └─────────────────────────┘ │ │ │ └───────────────────────────────────────────────────┘ │ │ │ │ [Use Camera] [Enter Manually] [Recent Cards ▼] │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` **After scanning - Customer Card View:** ``` ┌─────────────────────────────────────────────────────────────────┐ │ ← Back Customer Card │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ 👤 Marie Laurent │ │ │ │ marie.laurent@email.com │ │ │ │ Member since: Jan 2024 │ │ │ └─────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ │ │ │ │ ☕ ☕ ☕ ☕ ☕ ☕ ☕ ☕ ○ ○ │ │ │ │ │ │ │ │ 8 / 10 stamps │ │ │ │ 2 more until FREE COFFEE │ │ │ │ │ │ │ └─────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ │ │ │ │ [ ➕ ADD STAMP ] [ 🎁 REDEEM ] │ │ │ │ │ │ │ └─────────────────────────────────────────────────┘ │ │ │ │ ⚠️ Next stamp available in 12 minutes │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` **PIN Entry Modal (appears when adding stamp):** ``` ┌─────────────────────────────────────────────────────────────────┐ │ Enter Staff PIN │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────┐ │ │ │ ● ● ● ● │ │ │ └─────────────────┘ │ │ │ │ ┌─────┐ ┌─────┐ ┌─────┐ │ │ │ 1 │ │ 2 │ │ 3 │ │ │ └─────┘ └─────┘ └─────┘ │ │ ┌─────┐ ┌─────┐ ┌─────┐ │ │ │ 4 │ │ 5 │ │ 6 │ │ │ └─────┘ └─────┘ └─────┘ │ │ ┌─────┐ ┌─────┐ ┌─────┐ │ │ │ 7 │ │ 8 │ │ 9 │ │ │ └─────┘ └─────┘ └─────┘ │ │ ┌─────┐ ┌─────┐ ┌─────┐ │ │ │ ⌫ │ │ 0 │ │ ✓ │ │ │ └─────┘ └─────┘ └─────┘ │ │ │ │ [Cancel] │ └─────────────────────────────────────────────────────────────────┘ ``` #### Program Setup (`/store/loyalty/settings`) ``` ┌─────────────────────────────────────────────────────────────────┐ │ ⚙️ Loyalty Program Settings │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Program Type │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ ☑️ Stamps │ │ ☐ Points │ │ ☐ Hybrid │ │ │ │ Buy 10 Get 1 │ │ Earn per € │ │ Both systems │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ │ ───────────────────────────────────────────────────────────── │ │ │ │ Stamp Configuration │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ Stamps needed for reward: [ 10 ▼ ] │ │ │ │ Reward description: [ Free coffee of choice ] │ │ │ │ Reward value (optional): [ €4.50 ] │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ ───────────────────────────────────────────────────────────── │ │ │ │ 🛡️ Fraud Prevention │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ ☑️ Require staff PIN for operations │ │ │ │ Cooldown between stamps: [ 15 ] minutes │ │ │ │ Max stamps per day: [ 5 ] │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ ───────────────────────────────────────────────────────────── │ │ │ │ 🎨 Card Branding │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ Card name: [ Café Loyalty Card ] │ │ │ │ Primary color: [████] #4F46E5 │ │ │ │ Logo: [Upload] cafe-logo.png ✓ │ │ │ │ │ │ │ │ Preview: ┌────────────────────┐ │ │ │ │ │ ☕ Café Loyalty │ │ │ │ │ │ ████████░░ │ │ │ │ │ │ 8/10 stamps │ │ │ │ │ └────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ [Cancel] [Save Changes] │ └─────────────────────────────────────────────────────────────────┘ ``` #### Staff PIN Management (`/store/loyalty/pins`) ``` ┌─────────────────────────────────────────────────────────────────┐ │ 🔐 Staff PINs [+ Add PIN] │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ 👤 Marie (Manager) [Edit] [🗑️] │ │ │ │ Last used: Today, 14:32 │ │ │ │ Status: ✅ Active │ │ │ ├─────────────────────────────────────────────────────────┤ │ │ │ 👤 Thomas (Staff) [Edit] [🗑️] │ │ │ │ Last used: Today, 11:15 │ │ │ │ Status: ✅ Active │ │ │ ├─────────────────────────────────────────────────────────┤ │ │ │ 👤 Julie (Staff) [Edit] [🗑️] │ │ │ │ Last used: Yesterday │ │ │ │ Status: 🔒 Locked (3 failed attempts) [Unlock] │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ ℹ️ Staff PINs prevent unauthorized stamp/point operations. │ │ PINs are locked after 5 failed attempts for 30 minutes. │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` #### Customer Cards List (`/store/loyalty/cards`) ``` ┌─────────────────────────────────────────────────────────────────┐ │ 👥 Loyalty Members 🔍 [Search...] [Export]│ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Filter: [All ▼] [Active ▼] [Has Reward Ready ▼] │ │ │ │ ┌─────────────────────────────────────────────────────────────┐│ │ │ Customer │ Card # │ Stamps │ Last Visit │ ⋮ ││ │ ├───────────────────┼──────────────┼────────┼────────────┼────┤│ │ │ Marie Laurent │ 4821-7493 │ 8/10 ⭐│ Today │ ⋮ ││ │ │ Jean Dupont │ 4821-2847 │ 10/10 🎁│ Yesterday │ ⋮ ││ │ │ Sophie Martin │ 4821-9382 │ 3/10 │ 3 days ago │ ⋮ ││ │ │ Pierre Bernard │ 4821-1029 │ 6/10 │ 1 week ago │ ⋮ ││ │ │ ... │ ... │ ... │ ... │ ⋮ ││ │ └─────────────────────────────────────────────────────────────┘│ │ │ │ Showing 1-20 of 1,247 members [← Prev] [1] [2] [Next →]│ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 1.2 Admin Dashboard (Platform) #### Platform Loyalty Overview (`/admin/loyalty`) ``` ┌─────────────────────────────────────────────────────────────────┐ │ 🎯 Loyalty Programs Platform │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────┐│ │ │ 47 │ │ 38 │ │ 12,847 │ │ €47k ││ │ │ Programs │ │ Active │ │ Members │ │ Saved ││ │ │ Total │ │ Programs │ │ Total │ │ Value ││ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────┘│ │ │ │ Programs by Type: │ │ ═══════════════════════════════════════ │ │ Stamps: ████████████████████ 32 (68%) │ │ Points: ███████ 11 (23%) │ │ Hybrid: ████ 4 (9%) │ │ │ │ ┌─────────────────────────────────────────────────────────────┐│ │ │ Store │ Type │ Members │ Activity │ Status ││ │ ├───────────────────┼─────────┼─────────┼──────────┼──────────┤│ │ │ Café du Coin │ Stamps │ 1,247 │ High │ ✅ Active││ │ │ Boulangerie Paul │ Points │ 892 │ Medium │ ✅ Active││ │ │ Pizza Roma │ Stamps │ 456 │ Low │ ⚠️ Setup ││ │ │ ... │ ... │ ... │ ... │ ... ││ │ └─────────────────────────────────────────────────────────────┘│ │ │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## Part 2: User Journeys ### 2.1 Stamp-Based Loyalty Journey #### Customer Journey: Enrollment ``` ┌─────────────────────────────────────────────────────────────────┐ │ STAMP LOYALTY - ENROLLMENT │ └─────────────────────────────────────────────────────────────────┘ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ DISCOVER│────▶│ JOIN │────▶│ SAVE │────▶│ USE │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ │ ▼ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────┐ │ 1. Customer sees │ 2. Scans QR at │ 3. Card added │ 4. Ready to │ │ sign at counter│ register or │ to Google/ │ collect │ │ "Join our │ gives email │ Apple Wallet│ stamps! │ │ loyalty!" │ to cashier │ │ │ └─────────────────────────────────────────────────────────┘ ``` **Detailed Steps:** 1. **Discovery** (In-Store) - Customer sees loyalty program signage/tent card - QR code displayed at counter - Staff mentions program during checkout 2. **Sign Up** (30 seconds) - Customer scans QR code with phone - Lands on mobile enrollment page - Enters: Email (required), Name (optional) - Accepts terms with checkbox - Submits 3. **Card Creation** (Instant) - System creates loyalty card - Generates unique card number & QR code - Shows "Add to Wallet" buttons - Sends welcome email with card link 4. **Wallet Save** (Optional but encouraged) - Customer taps "Add to Google Wallet" or "Add to Apple Wallet" - Pass appears in their wallet app - Always accessible, works offline #### Customer Journey: Earning Stamps ``` ┌─────────────────────────────────────────────────────────────────┐ │ STAMP LOYALTY - EARNING │ └─────────────────────────────────────────────────────────────────┘ Customer Staff System Wallet │ │ │ │ │ 1. Makes │ │ │ │ purchase │ │ │ │───────────────▶│ │ │ │ │ │ │ │ 2. Shows │ │ │ │ loyalty card │ │ │ │───────────────▶│ │ │ │ │ 3. Scans QR │ │ │ │─────────────────▶│ │ │ │ │ │ │ │ 4. Enters PIN │ │ │ │─────────────────▶│ │ │ │ │ │ │ │ 5. Confirms │ │ │ │◀─────────────────│ │ │ │ "Stamp added!" │ │ │ │ │ │ │ 6. Verbal │ │ 7. Push │ │ confirmation │ │ notification │ │◀───────────────│ │────────────────▶│ │ │ │ │ │ │ 8. Pass updates│ │◀───────────────────────────────────│────────────────▶│ │ "8/10 stamps" │ │ ``` **Anti-Fraud Checks (Automatic):** 1. ✅ Card is active 2. ✅ Program is active 3. ✅ Staff PIN is valid 4. ✅ Cooldown period elapsed (15 min since last stamp) 5. ✅ Daily limit not reached (max 5/day) **Success Response:** ```json { "success": true, "stamp_count": 8, "stamps_target": 10, "stamps_until_reward": 2, "message": "2 more stamps until your free coffee!", "next_stamp_available": "2024-01-28T15:30:00Z" } ``` #### Customer Journey: Redeeming Reward ``` ┌─────────────────────────────────────────────────────────────────┐ │ STAMP LOYALTY - REDEMPTION │ └─────────────────────────────────────────────────────────────────┘ Customer Staff System │ │ │ │ 1. "I'd like │ │ │ to redeem my │ │ │ free coffee" │ │ │───────────────▶│ │ │ │ │ │ 2. Shows card │ │ │ (10/10 stamps)│ │ │───────────────▶│ │ │ │ 3. Scans + sees │ │ │ "REWARD READY" │ │ │─────────────────▶│ │ │ │ │ │ 4. Clicks │ │ │ [REDEEM REWARD] │ │ │─────────────────▶│ │ │ │ │ │ 5. Enters PIN │ │ │─────────────────▶│ │ │ │ │ │ 6. Confirms │ │ │◀─────────────────│ │ │ "Reward redeemed"│ │ │ Stamps reset: 0 │ │ │ │ │ 7. Gives free │ │ │ coffee │ │ │◀───────────────│ │ │ │ │ │ 🎉 HAPPY │ │ │ CUSTOMER! │ │ ``` ### 2.2 Points-Based Loyalty Journey #### Customer Journey: Earning Points ``` ┌─────────────────────────────────────────────────────────────────┐ │ POINTS LOYALTY - EARNING │ └─────────────────────────────────────────────────────────────────┘ Customer Staff System │ │ │ │ 1. Purchases │ │ │ €25.00 order │ │ │───────────────▶│ │ │ │ │ │ 2. Shows │ │ │ loyalty card │ │ │───────────────▶│ │ │ │ 3. Scans card │ │ │─────────────────▶│ │ │ │ │ │ 4. Enters amount │ │ │ €25.00 │ │ │─────────────────▶│ │ │ │ │ │ 5. Enters PIN │ │ │─────────────────▶│ │ │ │ ┌──────────┐ │ │ │ │Calculate:│ │ │ │ │€25 × 10 │ │ │ │ │= 250 pts │ │ │ │ └──────────┘ │ │ 6. Confirms │ │ │◀─────────────────│ │ │ "+250 points!" │ │ │ │ │ 7. Receipt │ │ │ shows points │ │ │◀───────────────│ │ ``` **Points Calculation:** ``` Purchase: €25.00 Rate: 10 points per euro Points Earned: 250 points New Balance: 750 points ``` #### Customer Journey: Redeeming Points ``` ┌─────────────────────────────────────────────────────────────────┐ │ POINTS LOYALTY - REDEMPTION │ └─────────────────────────────────────────────────────────────────┘ Customer Staff System │ │ │ │ 1. Views │ │ │ rewards in │ │ │ wallet app │ │ │ │ │ │ │ ▼ │ │ │ ┌──────────┐ │ │ │ │ REWARDS │ │ │ │ │──────────│ │ │ │ │ 500 pts │ │ │ │ │ Free │ │ │ │ │ Drink │ │ │ │ │──────────│ │ │ │ │ 1000 pts │ │ │ │ │ Free │ │ │ │ │ Meal │ │ │ │ └──────────┘ │ │ │ │ │ │ 2. "I want to │ │ │ redeem for │ │ │ free drink" │ │ │───────────────▶│ │ │ │ 3. Scans card │ │ │ Selects reward │ │ │─────────────────▶│ │ │ │ │ │ 4. Enters PIN │ │ │─────────────────▶│ │ │ │ │ │ 5. Confirms │ │ │◀─────────────────│ │ │ "-500 points" │ │ │ Balance: 250 pts │ │ │ │ │ 6. Gets free │ │ │ drink │ │ │◀───────────────│ │ ``` --- ## Part 3: Market Best Practices ### 3.1 Competitive Analysis | Feature | Square Loyalty | Toast | Fivestars | **Orion** | |---------|---------------|-------|-----------|--------------| | Stamp cards | ✅ | ✅ | ✅ | ✅ | | Points system | ✅ | ✅ | ✅ | ✅ | | Google Wallet | ✅ | ❌ | ✅ | ✅ | | Apple Wallet | ✅ | ✅ | ✅ | ✅ | | Staff PIN | ❌ | ✅ | ✅ | ✅ | | Cooldown fraud protection | ❌ | ❌ | ✅ | ✅ | | Daily limits | ❌ | ❌ | ✅ | ✅ | | Tablet terminal | ✅ | ✅ | ✅ | ✅ (planned) | | Customer app | ✅ | ✅ | ✅ | Via Wallet | | Analytics dashboard | ✅ | ✅ | ✅ | ✅ | ### 3.2 Best Practices to Implement #### UX Best Practices 1. **Instant gratification** - Show stamp/points immediately after transaction 2. **Progress visualization** - Clear progress bars/stamp grids 3. **Reward proximity** - "Only 2 more until your free coffee!" 4. **Wallet-first** - Push customers to save to wallet 5. **Offline support** - Card works even without internet (via wallet) #### Fraud Prevention Best Practices 1. **Multi-layer security** - PIN + cooldown + daily limits 2. **Staff accountability** - Every transaction tied to a staff PIN 3. **Audit trail** - Complete history with IP/device info 4. **Lockout protection** - Automatic PIN lockout after failures 5. **Admin oversight** - Unlock and PIN management in dashboard #### Engagement Best Practices 1. **Welcome bonus** - Give 1 stamp on enrollment (configurable) 2. **Birthday rewards** - Extra stamps/points on customer birthday 3. **Milestone notifications** - "Congrats! 50 stamps earned lifetime!" 4. **Re-engagement** - Remind inactive customers via email 5. **Double points days** - Promotional multipliers (future) --- ## Part 4: Implementation Roadmap ### Phase 2A: Store Interface (Priority) | Task | Effort | Priority | |------|--------|----------| | Loyalty terminal (scan/stamp/redeem) | 3 days | P0 | | Program setup wizard | 2 days | P0 | | Staff PIN management | 1 day | P0 | | Customer cards list | 1 day | P1 | | Dashboard with stats | 2 days | P1 | | Export functionality | 1 day | P2 | ### Phase 2B: Admin Interface | Task | Effort | Priority | |------|--------|----------| | Programs list view | 1 day | P1 | | Platform-wide stats | 1 day | P1 | | Program detail view | 0.5 day | P2 | ### Phase 2C: Customer Experience | Task | Effort | Priority | |------|--------|----------| | Enrollment page (mobile) | 1 day | P0 | | Card detail page | 0.5 day | P1 | | Wallet pass polish | 1 day | P1 | | Email templates | 1 day | P2 | ### Phase 2D: Polish & Advanced | Task | Effort | Priority | |------|--------|----------| | QR code scanner (JS) | 2 days | P0 | | Real-time updates (WebSocket) | 1 day | P2 | | Receipt printing | 1 day | P3 | | POS integration hooks | 2 days | P3 | --- ## Part 5: Technical Specifications ### Store Terminal Requirements - **Responsive**: Works on tablet (primary), desktop, mobile - **Touch-friendly**: Large buttons, numpad for PIN - **Camera access**: For QR code scanning (WebRTC) - **Offline-capable**: Queue operations if network down (future) - **Real-time**: WebSocket for instant updates ### Frontend Stack - **Framework**: React/Vue components (match existing stack) - **QR Scanner**: `html5-qrcode` or `@aspect-sdk/barcode-reader` - **Charts**: Existing charting library (Chart.js or similar) - **Animations**: CSS transitions for stamp animations ### API Considerations - All store endpoints require `store_id` from auth token - Staff PIN passed in request body, not headers - Rate limiting on lookup/scan endpoints - Pagination on card list (default 50) --- ## Appendix: Mockup Reference Images ### Stamp Card Visual (Wallet Pass) ``` ┌────────────────────────────────────┐ │ ☕ Café du Coin │ │ │ │ ████ ████ ████ ████ ████ │ │ ████ ████ ████ ░░░░ ░░░░ │ │ │ │ 8/10 STAMPS │ │ 2 more until FREE COFFEE │ │ │ │ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ │ │ ▓▓▓▓▓▓▓▓ QR CODE ▓▓▓▓▓▓▓▓ │ │ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ │ │ │ │ Card #4821-7493-2841 │ └────────────────────────────────────┘ ``` ### Points Card Visual (Wallet Pass) ``` ┌────────────────────────────────────┐ │ 🍕 Pizza Roma Rewards │ │ │ │ ★ 750 ★ │ │ POINTS │ │ │ │ ────────────────────── │ │ Next reward: 500 pts │ │ Free drink │ │ ────────────────────── │ │ │ │ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ │ │ ▓▓▓▓▓▓▓▓ QR CODE ▓▓▓▓▓▓▓▓ │ │ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ │ │ │ │ Card #4821-2847-9283 │ └────────────────────────────────────┘ ``` --- *Document Version: 1.0* *Created: 2025-01-28* *Author: Orion Engineering*