Skip to content

README.md

Latest commit

 

History

History
72 lines (51 loc) · 3.66 KB

README.md

File metadata and controls

72 lines (51 loc) · 3.66 KB
Raw

Charon

Overview

Charon is a ticket distribution, encryption, and validation microservice developed for Excel, the annual techno-managerial fest of Govt. Model Engineering College, Kochi.

Designed to seamlessly manage onboarding for over 2,000 attendees, this service ensures that entry validation across various events during the three-day fest remains secure, scalable, and highly responsive, even during peak hours.

Tech Stack

  • FastAPI: High-performance asynchronous web framework for the API.
  • PostgreSQL: Relational database for robust data integrity and transactional locking.
  • Redis & Celery: Message broker and background task queue for reliable, non-blocking email delivery.
  • Docker: Containerization for a reproducible and isolated deployment environment.

Features

  • Single-Use Encrypted Tickets: Utilizes AES-GCM encryption to generate secure, tamper-proof QR codes.
  • Concurrency Control: Implements database-level pessimistic locking (SELECT FOR UPDATE) to eliminate duplicate scans, ensuring only the first successful transaction is processed.
  • Asynchronous Email Distribution: Leverages Celery for background email generation and delivery, ensuring the main API remains fast and responsive.
  • Rate Limit Compliance: Automatically throttles outgoing SMTP traffic to comply with AWS SES and other provider rate limits.
  • SES Webhook Integration: Processes AWS SNS notifications to seamlessly capture bounced emails and flag them in the database for administrative review.

Setup Guide

Prerequisites

Please ensure the following are installed:

  • Docker and Docker Compose
  • PostgreSQL (database instance)

Installation & Launch

  1. Clone the Repository

    git clone https://github.com/ABHAY-100/Charon.git

  2. Navigate to the Project Directory

    cd Charon

  3. Configure Environment Variables Create a copy of the example environment file and provide your database connection, JWT, encryption, and SMTP credentials:

    cp .env.example .env

  4. Initialize the Database Apply the SQL schema, tables, and necessary triggers to your PostgreSQL database:

    psql -U postgres -d charon -f tickets_schema.sql

  5. Start the Services Launch the API, Redis queue, and Celery worker environments using Docker Compose:

    docker-compose up --build -d

  6. Open your browser and navigate to http://localhost:8000/docs to access the interactive API documentation.

How It Works

  1. Registration: Administrators can register events and upload user lists via bulk CSV endpoints (/proshows and /attendees). PostgreSQL triggers then automatically generate ticket records for every user-event combination.
  2. Distribution: Initiating the /distribute endpoint securely encrypts ticket keys and queues them for delivery. The Celery workers process this queue to dispatch HTML emails containing the inline QR codes.
  3. Check-In: At the venue, volunteers scan the QR codes, which interact with the /validate endpoint. The server decrypts the token, applies a database lock on the ticket, verifies the scanning time window, and successfully checks the attendee in.

About Excel

Excel, the premier techno-managerial fest of India, is proudly hosted by the students of Govt. Model Engineering College, Kochi. Since its inception in 2001, Excel has been shaped by moments of bold thinking, relentless curiosity and the drive of young minds determined to leave their mark. What began as an idea has, over time, evolved into a powerful platform where creativity is refined, innovation is celebrated and excellence is forged.