ScanQRTo.WIN

A comprehensive QR code contest platform built with Go, React, Vite, and Tailwind CSS. This professional-grade platform enables you to host sophisticated QR code-based contests, giveaways, and promotional campaigns with advanced features like delayed mode, prize management, lead capture, and real-time analytics.

🚀 About The Project

ScanQRTo.WIN is a production-ready contest platform designed for businesses, events, and marketers who need full control over their promotional campaigns. Running as a single binary with an embedded frontend, it provides enterprise-level features with simple deployment.

✨ Key Features

🎯 Contest Management

• Instant Mode: Traditional immediate win/lose determination with customizable probabilities
• Delayed Mode: Manual prize distribution perfect for live events and controlled giveaways
• Win Controls: Force wins, halt winning, set daily/total limits, and manage win percentages
• Session Archiving: Preserve historical data between campaigns with complete state restoration

🎨 Advanced Customization

• Professional QR Codes: Custom shapes, colors, logo embedding, and advanced styling options
• Branded Experiences: Fully customizable winner/loser/waiting screens with themes and animations
• Media Management: Upload and organize images, videos, and assets with automatic optimization
• Template System: Save and share complete contest configurations with team members

🏆 Prize & Giveaway System

• Multiple Distribution Modes: Sequential, probability-based, or hybrid prize distribution
• Stock Management: Real-time inventory tracking with automatic availability control
• Prize Categories: Organize prizes into logical groups for better management
• Winner Tracking: Complete fulfillment workflow with status updates and notes

📊 Lead Capture & Analytics

• Dynamic Forms: Build custom lead capture forms with 13+ field types and validation
• Webhook Integration: Real-time data delivery to CRMs and marketing platforms
• Export & Reporting: Comprehensive data export in CSV/JSON with advanced filtering
• Real-time Monitoring: Live participant feed with device detection and duplicate prevention

⚡ Performance & Reliability

• Real-time Updates: WebSocket-powered live updates with automatic polling fallback
• Device Fingerprinting: Advanced duplicate detection preventing multi-entry cheating
• Mobile Optimized: Responsive design ensuring perfect experience across all devices
• Single Binary Deployment: Zero-dependency deployment with embedded frontend and database

Built With

• Go (Backend)
• Gin (Web Framework)
• SQLite (Database)
• React (Frontend)
• Vite (Build Tool)
• Tailwind CSS (CSS Framework)

🏁 Getting Started

To get a local copy up and running, follow these simple steps.

Prerequisites

You will need the following software installed on your machine:

• Go (version 1.19 or higher)
• Node.js (version 16 or higher) & npm

Installation & Setup

1. Clone the repository:

   git clone https://github.com/your_username/scanqrto-unified.git
   cd scanqrto-unified
   

2. Configure Environment: Create a .env file in the root directory and add the following variables.

   SERVER_PORT=8090
   ADMIN_USERNAME=admin
   

3. Build Frontend Assets:

   cd frontend
   npm install
   npm run build
   cd ..
   

4. Build and Run the Backend: This command builds the Go server and starts it. The frontend is served from the frontend/dist directory.

   go build -o scanqrto-server .
   ./scanqrto-server
   

   Your server is now running at http://localhost:8090.

📖 Usage Guide

Access Points

• Admin Panel: http://localhost:8090/admin - Complete contest management interface
• Public QR Display: http://localhost:8090/ - Main QR code display for participants
• Scan Landing Page: http://localhost:8090/play - Player experience and results

Quick Start Workflow

1. Initial Setup

   • Access admin panel and change default password in System tab
   • Configure basic contest settings in Controls tab
   • Customize QR code appearance in Advanced QR tab

2. Design Your Experience

   • Customize winner/loser screens in Play Design tab
   • Upload brand assets through Media tab
   • Configure duplicate player messaging in Duplicate Design tab

3. Choose Your Contest Mode

   • Instant Mode: Set win percentage and let players scan for immediate results
   • Delayed Mode: Enable from Delayed Mode tab, then use Start/Stop Contest controls

4. Optional Enhancements

   • Set up prize system in Prizes tab with distribution modes
   • Configure lead capture funnel for data collection
   • Create templates to save configurations for future use

Delayed Mode Operations

See DELAYED-MODE.md for consolidated technical details.

For Live Events:

1. Enable Delayed Mode and configure timer/display options
2. Start Contest from Logs tab when ready to accept entries
3. Monitor waiting entrants in real-time
4. Use Disperse Prize button to manually award prizes
5. Stop Contest when event concludes

Admin Features:

• Real-time entrant monitoring with similarity detection
• Manual prize override with thumbnail previews
• Auto-distribute remaining prizes option
• Archive and resume functionality for multi-day events

Admin Panel Overview

The admin interface is organized into intuitive sections:

Design Tabs

• Splash: Main QR display page customization
• Advanced QR: Professional QR code styling with shapes and logos
• Play: Winner/loser result screen design
• Duplicate: Repeat visitor screen customization

Management Tabs

• Controls: Win percentages, contest rules, and limits
• Prizes: Prize system with categories and distribution modes
• Delayed Mode: Manual contest management and screen design
• Templates: Save/load complete configurations

Data & Analytics

• Media: Upload and manage images, videos, and assets
• Logs: Real-time participant monitoring and management
• Archive: Historical campaign data and session management

Lead Generation

• Funnel: Lead capture form builder and triggers
• Leads: View captured data and webhook integration

System

• System: Security settings and admin password management
• Help: Comprehensive tutorials and feature documentation

🤝 Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📜 License

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