Conc QR System

A comprehensive QR-based event access and management system designed for tracking participant attendance, food distribution, and activity access across multiple days and roles.

🚀 Overview

This repository contains a unified application consisting of:

• Backend: Express.js with Sequelize ORM and PostgreSQL.
• Frontend: Next.js with a modern scanning interface and an Admin Dashboard.
• Database: PostgreSQL for persistent storage of users, participants, and scan history.

The system is designed to be deployed as a single unit or run separately for development.

---

🛠 Tech Stack

• Frontend: Next.js 15, Tailwind CSS, Lucide React, Framer Motion.
• Backend: Node.js, Express, Sequelize (PostgreSQL), JWT Authentication.
• Infrastructure: Docker & Docker Compose.

---

🏃 Quick Start (Docker)

The easiest way to get the entire system running is using Docker.

1. Clone the repository:

   git clone <repo-url>
   cd conc-qr

2. Start the services:

   docker-compose up --build

   This will start:

   • PostgreSQL database on port 5432.
   • Unified Web + API application on port 3000.

3. Seed the data (See Seeding Data below).

---

🔧 Local Development

1. Backend Setup

cd server
npm install
cp .env.example .env # Configure your DATABASE_URL
npm run dev

2. Frontend Setup

cd web
npm install
npm run dev # Runs on http://localhost:3001

Note: In development, the frontend is configured to proxy API requests to http://localhost:5000 (default backend port).

---

🌱 Seeding Data

Seeding is crucial for initializing the system with authorized users (scanners) and participants.

1. Seeding Users (Scanners)

Users are the staff members who will perform the scans.

• CSV Path: Root directory user.csv or server/user.csv.
• CSV Format:

  name, email, password, role
  John Doe, admin@example.com, password123, ADMIN
  Jane Smith, hospi@example.com, password123, HOSPI

• Roles: ADMIN, HOSPI, RND, MGMT, SECURITY.
• Command:

  # From /server directory
  npm run seed-users:dev ../user.csv

2. Seeding Participants

Participants are the event attendees who have QR codes.

• CSV Path: Root directory participants.csv.
• CSV Format:

  id, name, email, phone, teamType
  XX-01, Kartik Jain, test@example.com, 919999999999, solo
  XX-02, Team Alpha, team@example.com, 918888888888, team

• ID Format: Typically XX-00 (used for QR code generation/scanning).
• Command:

  # From /server directory
  npm run seed:dev ../participants.csv

🐳 Seeding inside Docker

If you are running the system via Docker Compose, you can execute the seed scripts directly inside the running container. Note that since the backend is in the /server directory, you need to run the commands from there:

# Seed Users
docker-compose exec app npm run seed-users --prefix server

# Seed Participants
docker-compose exec app npm run seed-participants --prefix server

Note: The Docker container already has user.csv and participants.csv mounted via volumes, and the scripts are designed to find them automatically regardless of the execution path.

---

🛡 Access Matrix System

The system uses a dynamic Access Matrix to control which roles can scan for which event/day.

• Days: day1, day2, day3, etc.
• Access Types: REGISTRATION, FOOD, LUNCH, HIGH_TEA, ATTENDANCE, COMEDY_NIGHT, etc.
• Configuration: Admins can update this matrix via the Admin UI. It defines, for example, that only HOSPI and ADMIN roles can scan for FOOD on day1.

---

📁 Project Structure

.
├── server/             # Express.js Backend
│   ├── src/
│   │   ├── db/         # Models & Connection
│   │   ├── routes/     # API Endpoints
│   │   ├── scripts/    # Seeding scripts
│   │   └── index.ts    # Main Entry
├── web/                # Next.js Frontend
│   ├── src/
│   │   ├── app/        # Next.js App Router
│   │   ├── components/ # Shared UI components
│   │   └── lib/        # API client & Utilities
├── Dockerfile          # Unified build file
├── docker-compose.yml  # Local infrastructure
├── participants.csv    # Default participant seed data
└── user.csv            # Default user seed data

---

📜 API Documentation

Detailed API documentation is available in server/API_DOCUMENTATION.md.

---

📝 Important Notes

• Password Hashing: The seed-users script automatically hashes the plain-text passwords provided in the CSV using bcrypt.
• Database Sync: The backend uses sequelize.sync({ alter: true }), which automatically updates the schema to match the models on startup.
• Proxies: In production (Docker), the frontend proxies all /api/* requests to the internal backend service.