QR Meal System - Hackathon Management

A robust Next.js application for managing hackathon participants using QR codes for meal tracking. This system combines the best features from both the unified scan flow and hackvision projects.

Features

• QR Code Scanning: Real-time QR code scanning using device camera
• Participant Registration: Register participants by binding their info to QR codes
• Meal Allocation: Track and serve meals (breakfast, lunch, snacks, dinner) to participants
• Admin Dashboard: Comprehensive dashboard with statistics, logs, and participant management
• QR Code Generation: Generate bulk QR codes for participants
• Robust Security: Prevents duplicate meal serving using database constraints
• Real-time Updates: Auto-refreshing dashboard with live statistics

Tech Stack

• Framework: Next.js 16 (App Router)
• Language: TypeScript
• Database: MongoDB with Mongoose
• Styling: Tailwind CSS
• UI Components: Custom components with shadcn/ui patterns
• QR Code: html5-qrcode for scanning, qrcode for generation
• Notifications: Sonner for toast notifications

Prerequisites

• Node.js 18+
• MongoDB (local or cloud instance)
• npm or yarn

Installation

1. Clone the repository and navigate to the project:

cd qr-meal-system

2. Install dependencies:

npm install

3. Create a .env.local file in the root directory:

MONGODB_URI=mongodb://localhost:27017/qr-meal-system

For MongoDB Atlas (cloud), use:

MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/qr-meal-system

4. Start the development server:

npm run dev

5. Open http://localhost:3000 in your browser.

Usage

1. Generate QR Codes

Navigate to /generate-qr to generate QR codes for participants:

• Enter the number of QR codes to generate
• Set the starting index
• Click "Generate QR Codes"
• QR code images will be saved in /public/qr_codes/

2. Register Participants

1. Go to the home page (/)
2. Scan a QR code using the camera
3. If the QR code is valid but not registered, you'll see the registration form
4. Fill in participant details (name, team, college, phone)
5. Submit to activate the QR code

3. Serve Meals

1. Scan a registered participant's QR code
2. Select the meal type (breakfast, lunch, snacks, dinner)
3. Confirm allocation
4. The system prevents duplicate meal serving automatically

4. View Dashboard

Navigate to /dashboard to see:

• Total QR codes and registered participants
• Meal distribution statistics
• Live scan logs
• Registered participants list

API Endpoints

• POST /api/validate-qr - Validate a QR code before registration
• POST /api/register - Register a participant
• POST /api/check-participant - Check if participant is registered
• POST /api/scan-meal - Record a meal scan
• GET /api/stats - Get dashboard statistics
• GET /api/logs - Get recent meal scan logs
• GET /api/registered - Get list of registered participants
• GET /api/participant-meals/[participantId] - Get meals served to a participant
• POST /api/generate-qr - Generate QR codes

Database Schema

Participant

• participantId: String (unique, indexed)
• name: String
• teamName: String
• college: String
• phone: String
• qrActive: Boolean (indexed)
• createdAt: Date
• updatedAt: Date

MealRecord

• participantId: String (indexed)
• mealType: Enum ['breakfast', 'lunch', 'snacks', 'dinner']
• scannedBy: String
• scanTime: Date
• Unique constraint on (participantId, mealType) to prevent duplicates

Security Features

1. Duplicate Prevention: Database unique constraint prevents serving the same meal twice to a participant
2. QR Activation: QR codes must be activated during registration before they can be used
3. Server-side Validation: All validations happen on the server, not client-side
4. Race Condition Handling: Database constraints handle concurrent requests

Project Structure

qr-meal-system/
├── app/
│   ├── api/              # API routes
│   ├── dashboard/        # Admin dashboard page
│   ├── generate-qr/     # QR generation page
│   ├── layout.tsx        # Root layout
│   ├── page.tsx          # Main scanner page
│   └── globals.css       # Global styles
├── components/
│   ├── ui/               # Reusable UI components
│   ├── QRScanner.tsx     # QR scanner component
│   ├── RegistrationForm.tsx
│   └── MealAllocation.tsx
├── lib/
│   ├── db.ts            # MongoDB connection
│   ├── qr-generator.ts  # QR code generation utility
│   └── utils.ts         # Utility functions
├── models/
│   ├── Participant.ts   # Participant model
│   └── MealRecord.ts    # Meal record model
└── public/
    └── qr_codes/        # Generated QR code images

Development

# Run development server
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Lint code
npm run lint

Environment Variables

• MONGODB_URI: MongoDB connection string (required)

Notes

• QR codes are generated with format: EVENT2026_P_XXXXXX (6-digit zero-padded number)
• QR code images are saved as PNG files in /public/qr_codes/
• The dashboard auto-refreshes every 5 seconds
• Camera permissions are required for QR scanning

License

MIT