Hackathon QR Check-in System

This project is a web application designed for managing event check-ins and other interactions (like meals or swag distribution) using QR codes.

Technical Overview

The application is built using Next.js (a React framework) and TypeScript. It provides a user interface for scanning QR codes, manually entering IDs, and interacting with a backend API to process these actions.

Core Functionalities

1. Scan Type Selection:

   • Users can select the purpose of the scan from a predefined list: "Check-in", "Breakfast", "Lunch", "Dinner", or "Swag".
   • This selection determines how the backend processes the scanned ID.

2. QR Code Scanning:

   • The application utilizes the html5-qrcode library to access the device's camera through the browser's WebRTC (getUserMedia) API.
   • When a QR code is successfully scanned, the decoded text (expected to be a userId) is captured.
   • Input: A QR code image captured by the device camera. The system expects this QR code to contain a unique userId string.
   • Process: The html5-qrcode library handles camera access, QR code detection, and decoding.
   • Output: The decoded userId string.

3. Manual ID Entry:

   • As an alternative to QR scanning, users can manually type in a userId.
   • This is useful if a QR code is unreadable or unavailable.
   • Input: A userId string entered into a text field by the user.
   • Output: The entered userId string.

4. API Interaction (/api/scan):

   • Both QR scanning and manual entry ultimately send a request to the /api/scan backend endpoint.
   • Input to API: A JSON payload containing:

     {
       "userId": "string", // The scanned or manually entered User ID
       "scanType": "string" // e.g., "check-in", "lunch"
     }

   • Output from API: A JSON response (ScanResult) indicating the outcome:

     interface ScanResult {
       success: boolean; // True if the operation was successful, false otherwise
       message: string;  // A human-readable message about the outcome
       application?: {   // Optional: Details of the user/application associated with the userId
         userId?: string;
         fullName?: string;
         cwid?: string;
         status?: string;
       };
       checkIn?: {       // Optional: Details of the check-in record created/updated
         checkInType?: string;
         checkInTime?: string; // ISO date-time string
       };
     }

     For example, a successful check-in might return:

     {
       "success": true,
       "message": "Checked in successfully.",
       "application": {
         "userId": "user123",
         "fullName": "John Doe",
         "cwid": "C00123456",
         "status": "accepted"
       },
       "checkIn": {
         "checkInType": "check-in",
         "checkInTime": "2023-10-27T10:30:00.000Z"
       }
     }

     An unsuccessful attempt (e.g., user not found, already checked in for a meal) would return success: false with an appropriate message.

5. Result Display:

   • The UI updates to show whether the scan/manual entry was successful or failed, based on the API response.
   • On success, it may display user details (like full name) and the type/time of the interaction.

6. Debug Tools:

   • The application includes a debug section with tools to:
     • Test API connectivity (/api/test).
     • Create test application data (/api/debug/create-test-app).
     • List all applications in the database (/api/debug/list-apps).

Camera Usage and React Native Adaptation

The current web application uses the html5-qrcode library, which relies on browser standards (WebRTC's getUserMedia API) to access the camera. This is a common approach for web-based QR scanning.

To build a similar application in React Native, you would leverage native camera capabilities. Here's how the concept translates:

• Camera Access: Instead of html5-qrcode, you would use a React Native library that provides access to the device's native camera and QR scanning functionalities. Popular choices include:
  • react-native-camera (though it might be less actively maintained for newer React Native versions).
  • react-native-vision-camera: A more modern and powerful library that supports frame processors, allowing for efficient on-device QR code detection (often by integrating with MLKit Vision on Android or Vision framework on iOS).
• Scanning Logic:
  • The React Native component would initialize the camera view.
  • The chosen library would provide callbacks or events that trigger when a QR code is detected and decoded within the camera's viewfinder.
• Data Handling:
  • Once a QR code is decoded in the React Native app (yielding the userId), the subsequent logic would be very similar to the web app:
    1. Take the userId and the selected scanType.
    2. Make an HTTP POST request to the same /api/scan backend endpoint with the userId and scanType.
    3. Receive and process the ScanResult JSON response from the backend.
    4. Update the React Native UI to display the success/failure message and any relevant data.

The backend API (/api/scan) remains the same, meaning a React Native app can consume it directly without changes to the backend, provided the API is publicly accessible or the app has network access to it. The primary difference lies in how the camera is accessed and how the QR code is captured and decoded (native OS libraries via React Native bridge vs. browser APIs).

Project Structure (Key Directories)

• app/: Contains the Next.js pages and API routes.
  • app/page.tsx: The main page component for the QR scanner UI.
  • app/api/: Backend API route handlers.
    • app/api/scan/route.ts: Handles the QR scan and manual entry logic.
    • app/api/debug/: Contains API routes for debugging purposes.
• lib/: Utility functions, potentially database interactions (e.g., Prisma client).
• prisma/: Prisma schema and migration files for database management.
• components/: Reusable React components.
• public/: Static assets.

Setup and Running

(Assuming this section will be filled in with actual setup instructions like pnpm install, pnpm dev, etc.)

1. Install dependencies:

   pnpm install

2. Set up environment variables: Create a .env.local file based on .env.example (if one exists) and fill in necessary values (e.g., database URL).
3. Run database migrations (if using Prisma or similar):

   pnpm prisma migrate dev

4. Start the development server:

   pnpm dev

   The application should be accessible at http://localhost:3000.

This technical overview should help anyone understand the project's architecture and how it functions, making it easier to contribute or adapt its concepts, for instance, into a React Native application.