🎫 ProperCoupons

Enterprise Batch Loyalty Token & Coupon Generation Suite

Cryptographic Code Engine • Visual Layout Studio • 300 DPI Duplex Print PDFs • Supabase Cloud Sync • Mobile Customer Portal

---

  ██████╗ ██████╗  ██████╗ ██████╗ ███████╗██████╗  ██████╗ ██████╗ ██╗   ██╗██████╗  ██████╗ ███╗   ██╗███████╗
  ██╔══██╗██╔══██╗██╔═══██╗██╔══██╗██╔════╝██╔══██╗██╔════╝██╔═══██╗██║   ██║██╔══██╗██╔═══██╗████╗  ██║██╔════╝
  ██████╔╝██████╔╝██║   ██║██████╔╝█████╗  ██████╔╝██║     ██║   ██║██║   ██║██████╔╝██║   ██║██╔██╗ ██║███████╗
  ██╔═══╝ ██╔══██╗██║   ██║██╔═══╝ ██╔══╝  ██╔══██╗██║     ██║   ██║██║   ██║██╔═══╝ ██║   ██║██║╚██╗██║╚════██║
  ██║     ██║  ██║╚██████╔╝██║     ███████╗██║  ██║╚██████╗╚██████╔╝╚██████╔╝██║     ╚██████╔╝██║ ╚████║███████║
  ╚═╝     ╚═╝  ╚═╝ ╚═════╝ ╚═╝     ╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚═════╝  ╚═════╝ ╚═╝      ╚═════╝ ╚═╝  ╚═══╝╚══════╝

ProperCoupons is a full-stack, production-ready loyalty card and promotional coupon generation ecosystem.
It automates everything from cryptographic coupon generation and visual template composition to commercial duplex PDF printing, Supabase cloud synchronization, and instant mobile customer redemptions.

---

📑 Table of Contents

• 🌟 System Architecture
• ✨ Key Highlights & Features
  • 1. 🎨 Visual Template Studio
  • 2. 🔐 Cryptographic Code Engine
  • 3. 🖨️ Commercial Print-Ready PDF Engine
  • 4. ☁️ Dual-Sync Cloud & Local Database
  • 5. 📱 Standalone Customer Redemption Portal
  • 6. 📊 Token Ledger & Audit Studio
• 📁 Project Tree
• 🚀 Quick Start Guide
  • Prerequisites
  • Installation
  • Running the Interactive Web Studio
  • Running the Terminal CLI
• ☁️ Supabase Cloud Setup (2 Minutes)
• 🌐 Deploying the Customer Portal
• 🧪 Automated Test Suite
• 📜 License

---

🌟 System Architecture

flowchart TD
    subgraph Admin & Studio Suite [ProperCoupons Studio Suite]
        STUDIO[🎨 Visual Template Designer] -->|Live Position & Color Sliders| CFG[(config/templates.yaml)]
        GEN[🚀 Batch Generation Engine] -->|1. Generate Codes| CRYPTO[🔐 Crypto CSPRNG Engine]
        CRYPTO -->|2. Record Batch| DUAL_SYNC{🔄 Dual Sync Engine}
        DUAL_SYNC -->|Local Storage| SQLITE[(Local SQLite DB)]
        DUAL_SYNC -->|REST / RPC API| SUPABASE[(☁️ Supabase PostgreSQL)]
        GEN -->|3. Render Layout| COMPOSITOR[🖼️ PIL 8K High-Res Compositor]
        COMPOSITOR -->|4. Compile Matrix| PDF_ENG[🖨️ ReportLab Duplex PDF Engine]
        PDF_ENG -->|Print Output| PDF_FILE[📄 300 DPI A4/A3 Sheets + Crop Marks]
    end

    subgraph Customer Mobile Journey [Customer Self-Service Experience]
        CUSTOMER[📱 Customer / Contractor] -->|Scans QR Code on Pack| PORTAL[🌐 Customer Redemption Portal]
        PORTAL -->|Auto-fill ?code=ABC123| RPC_CALL[⚡ Supabase Atomic Stored Procedure]
        RPC_CALL -->|Row-Locking Anti-Fraud Check| SUPABASE
        SUPABASE -->|🎉 Success + Reward Confirmation| PORTAL
    end

    subgraph Real-Time Ledger [Audit & Administration]
        LEDGER[📊 Token Ledger & Audit Tab] -->|Query Real-Time Stats| DUAL_SYNC
    end

Loading

---

✨ Key Highlights & Features

1. 🎨 Visual Template Studio

• Intuitive Single-Axis Sliders: Move text and QR codes across the card freely with ↔️ Horizontal Position (Left ⟵ Center ⟶ Right) and ↕️ Vertical Position (Top ⟵ Center ⟶ Bottom) sliders.
• Minimal Fit Typography: Automatic bounding box fitting eliminates clipping and text overflow.
• Full Color Customization: Live color pickers for coupon text, QR foreground, and QR background.
• Real-Time Live Rendering: Preview changes on high-resolution 8K assets instantly.
• Per-Template Persistence: Click "💾 Save Settings for this Template" to save coordinates and colors directly to config/templates.yaml.

2. 🔐 Cryptographic Code Engine

• Cryptographically Secure RNG: Powered by Python's secrets module (CSPRNG).
• Ambiguity-Free Charsets: Automatically removes confusing characters (0 vs O, 1 vs I, L) to eliminate user typing mistakes.
• 100% Collision-Free Guarantee: Checks against database and lifetime batch sets to prevent duplicates.
• Luhn Mod-36 Checksums: Optional client-side mathematical checksum validation.

3. 🖨️ Commercial Print-Ready PDF Engine

• 300 DPI High-Resolution Output: Crisp vector-quality cards ready for offset and digital print shops.
• Precision Crop Marks: Subtle corner cut lines for automated guillotine and die-cutting trimmers.
• Synchronized Duplex Alignment: Front artwork and Back coupon cards are automatically mirrored in multi-up grid sheets (A4, A3, Letter) for double-sided printing.

4. ☁️ Dual-Sync Cloud & Local Database

• Offline-First Resilience: Works offline with zero dependencies using an embedded SQLite ledger (coupons.db).
• Supabase Cloud Push: Automatically dual-writes new batches to Supabase PostgreSQL in high-speed chunks.
• Atomic Fraud Protection: PostgreSQL stored procedure redeem_token uses row-level locking (FOR UPDATE) to mathematically prevent double-redemption race conditions.

5. 📱 Standalone Customer Redemption Portal

• Mobile-First Responsive Web App: Located in customer_portal/, ready for 1-click free hosting on Vercel, Cloudflare Pages, or Netlify.
• Auto-Fill from QR Scan: Scanning a token's printed QR code opens https://yourdomain.com/?code=H0DOA7 and populates the code automatically.
• In-Browser Camera Scanner: Built-in HTML5 QR/Barcode scanner allows customers to scan directly without installing an app.
• Confetti Celebration & Receipt: Celebratory animations, credited points badge, and digital timestamped receipts.

6. 📊 Token Ledger & Audit Studio

• Collapsible Batch Cards (st.expander): View batch metrics at a glance (Total, Redeemed, Active, Value, Date).
• Comprehensive Token Inspector: Examine individual coupon codes, timestamps, and customer references.
• Multi-Field Search Bar: Instantly filter across Token Codes, Campaign Names, Customer Phone Numbers, and Invoice References.
• One-Click Exports: Download batch .csv files and formatted .xlsx Excel spreadsheets directly.

---

📁 Project Tree

ProperCoupons/
├── config/
│   ├── templates.yaml             # Template profiles, coordinates, QR positions & colors
│   └── settings.yaml              # Global settings, paper sizes, DPI & Supabase keys
├── customer_portal/               # Standalone Customer Web App (Deployable to Vercel/Cloudflare)
│   ├── index.html                 # Mobile-first customer redemption portal
│   ├── style.css                  # Responsive design with reward cards & animations
│   ├── app.js                     # Supabase RPC redemption logic & QR camera scanner
│   ├── config.js                  # Frontend Supabase project configuration
│   ├── vercel.json                # Vercel deployment routing configuration
│   └── README.md                  # 1-click web portal hosting guide
├── src/
│   ├── core/
│   │   ├── code_generator.py      # Cryptographic PRNG, patterns & checksums
│   │   ├── renderer.py            # High-performance PIL compositor & auto-font engine
│   │   ├── sheet_layout.py        # Print PDF generator, duplex alignment & crop marks
│   │   ├── database.py            # SQLite lifecycle ledger & Excel/CSV export engine
│   │   └── supabase_client.py     # Supabase cloud sync & remote RPC caller
│   ├── utils/
│   │   ├── helpers.py             # Cross-platform path, font loader & color parser
│   │   └── config_loader.py       # YAML configuration parser & persistence engine
│   └── ui/
│       ├── web_app.py             # Streamlit visual studio & token ledger
│       └── cli.py                 # Rich interactive terminal interface
├── supabase/
│   └── schema.sql                 # PostgreSQL tables, indices, RLS & atomic RPC function
├── tests/                         # Full automated test suite (15 unit tests)
│   ├── test_generator.py
│   ├── test_renderer.py
│   ├── test_database.py
│   └── test_supabase.py
├── run.py                         # Unified CLI & Web application runner
├── requirements.txt               # Python package dependencies
├── .gitignore                     # Git ignore rules for builds & databases
├── LICENSE                        # MIT open source license
└── README.md                      # Project documentation

---

🚀 Quick Start Guide

Prerequisites

• Python 3.10 or higher
• pip package manager

Installation

# 1. Clone the repository
git clone https://github.com/yourusername/ProperCoupons.git
cd ProperCoupons

# 2. Install dependencies
pip install -r requirements.txt

Running the Interactive Web Studio

python run.py --web

Opens the interactive Visual Designer, Batch Generator, and Token Ledger in your default web browser.

Running the Terminal CLI

# Interactive Menu
python run.py

# Headless Batch Generation (e.g. for automation / CI)
python run.py --generate -t acrylic_enhancer_5kg -c 100 -n "Fall Promo 2026" -d "100"

# Verify / Redeem a Code from Terminal
python run.py --verify H0DOA7

---

☁️ Supabase Cloud Setup (2 Minutes)

1. Create a free project at supabase.com.
2. Go to SQL Editor, paste the contents of supabase/schema.sql, and click Run.
3. Copy your Project URL and API Keys from Settings ➔ API.
4. In config/settings.yaml, add your credentials:

   supabase:
     enabled: true
     url: "https://your-project.supabase.co"
     key: "your-service-role-or-anon-key"

5. In customer_portal/config.js, add your public anon key:

   const SUPABASE_CONFIG = {
     url: "https://your-project.supabase.co",
     anonKey: "your-public-anon-key"
   };

---

🌐 Deploying the Customer Portal

Deploy the customer web app for free in under 1 minute:

Deploy with Vercel

1. Go to vercel.com ➔ New Project.
2. Select your repository.
3. Set Root Directory to customer_portal.
4. Click Deploy. Your customer portal is immediately live at https://your-app.vercel.app!

Once deployed, update url_template in config/templates.yaml to point to your live URL:

qr_element:
  url_template: "https://your-app.vercel.app/?code={code}"

---

🧪 Automated Test Suite

ProperCoupons includes a test suite covering cryptographic uniqueness, mathematical checksums, dynamic image composition, duplex PDF layout, SQLite queries, and Supabase client fallbacks.

Run all unit tests:

python -m unittest discover tests

...............
----------------------------------------------------------------------
Ran 15 tests in 4.908s

OK

---

📜 License

Distributed under the MIT License. See LICENSE for more information.

---

_{Built with ❤️ for High-Volume Loyalty & Promotional Production.}