🚀 AeroHacks - AI-Powered Hackathon Management System

A comprehensive, AI-powered hackathon management platform with QR-based authentication, real-time team management, AI resume analysis, and automated evaluation systems.

📋 Table of Contents

Features
Tech Stack
Architecture
Getting Started
Project Structure
Authentication System
AI Features
API Documentation
Environment Variables
Deployment
Contributing
License

✨ Features

🎯 Core Features

Dual Authentication System
- Manual code-based login (Admin/Judge/Participant)
- QR code-based instant authentication
- JWT token-based session management
- 7-day QR token expiry with reusable codes
Role-Based Access Control
- Admin: Full hackathon management, QR generation, team oversight
- Judge: Team evaluation, scoring, shortlisting
- Participant: Team registration, submission, profile management
AI-Powered Features
- Resume parsing and analysis
- Automated skill extraction
- Team compatibility scoring
- GitHub repository analysis
- Presentation deck evaluation
QR Code Management
- Bulk QR code generation
- ZIP download for all roles
- Instant QR verification
- Token hash validation
Team Management
- Team registration and formation
- Member management
- Submission tracking
- Real-time leaderboard
Hackathon Phases
- Registration
- Team Formation
- Development
- Submission
- Evaluation
- Results

🎨 UI/UX Features

Modern, responsive design with Tailwind CSS
Dark mode support
Real-time toast notifications
Smooth animations with Framer Motion
Mobile-friendly interface
Intuitive navigation

🛠️ Tech Stack

Frontend

Framework: React 19.2
Build Tool: Vite 7.3
Routing: React Router DOM 7.13
Styling: Tailwind CSS 4.2 + DaisyUI 5.5
Animations: Framer Motion 12.34
QR Handling: html5-qrcode 2.3
Icons: Lucide React 0.574
Notifications: React Hot Toast 2.6

Backend

Runtime: Node.js 20+
Framework: Express 5.2
Database: MongoDB (Mongoose 9.2)
Authentication: JWT (jsonwebtoken 9.0)
File Upload: Multer 2.0
QR Generation: qrcode 1.5
File Parsing: pdf-parse, officeparser
Archive: archiver 7.0

AI/ML Integration

Hugging Face Inference API
Custom resume parsing algorithms
GitHub API integration
Automated scoring systems

🏗️ Architecture

aerohacks/
├── frontend/                 # React frontend application
│   ├── src/
│   │   ├── components/      # Reusable UI components
│   │   │   ├── features/    # Feature-specific components
│   │   │   ├── layout/      # Layout components
│   │   │   ├── participant/ # Participant dashboard components
│   │   │   └── ui/          # Base UI components
│   │   ├── context/         # React Context providers
│   │   │   ├── AuthContext.jsx
│   │   │   ├── HackathonContext.jsx
│   │   │   ├── TeamContext.jsx
│   │   │   └── ThemeContext.jsx
│   │   ├── pages/           # Page components
│   │   │   ├── Landing.jsx
│   │   │   ├── RoleAuth.jsx
│   │   │   ├── AdminDashboard.jsx
│   │   │   ├── JudgeDashboard.jsx
│   │   │   ├── ParticipantDashboard.jsx
│   │   │   └── ...
│   │   ├── utils/           # Utility functions
│   │   └── App.jsx          # Main app component
│   └── package.json
│
├── backend/                  # Express backend API
│   ├── config/              # Configuration files
│   │   └── db.js            # MongoDB connection
│   ├── models/              # Mongoose models
│   │   ├── User.js
│   │   ├── Hackathon.js
│   │   ├── Team.js
│   │   └── Analysis.js
│   ├── src/
│   │   ├── controllers/     # Route controllers
│   │   │   ├── qrController.js
│   │   │   ├── ai.controller.js
│   │   │   ├── participant.controller.js
│   │   │   └── team.controller.js
│   │   ├── routes/          # API routes
│   │   │   ├── qr.routes.js
│   │   │   ├── ai.routes.js
│   │   │   ├── participant.routes.js
│   │   │   └── team.routes.js
│   │   ├── services/        # Business logic
│   │   │   └── qrService.js
│   │   └── utils/           # Utility functions
│   │       └── tokenUtils.js
│   ├── scripts/             # Setup and utility scripts
│   │   ├── generateTestQRs.js
│   │   └── setupTestDatabase.js
│   ├── server.js            # Express server entry point
│   └── package.json
│
└── docs/                     # Documentation
    ├── QR_AUTH_IMPLEMENTATION.md
    ├── DATABASE_SETUP_GUIDE.md
    └── improvements.md

🚀 Getting Started

Prerequisites

Node.js 20+ and npm
MongoDB Atlas account (or local MongoDB)
Git

Installation

Clone the repository

git clone https://github.com/Pratham21223/Decryters.git
cd aerohacks

Setup Backend
```
cd backend
npm install
```

Configure Backend Environment

Create backend/.env:

MONGO_URI=mongodb+srv://username:password@cluster.mongodb.net/aerohacks
JWT_SECRET=your-super-secret-jwt-key-min-64-characters-long
QR_TOKEN_EXPIRY=7d
PORT=5000
FRONTEND_URL=http://localhost:5173

Setup Frontend
```
cd ../frontend
npm install
```
Configure Frontend Environment

Create frontend/.env:
```
VITE_BACKEND_URL=http://localhost:5000
```

Setup Test Database

cd ../backend
node scripts/setupTestDatabase.js

Start Development Servers

Terminal 1 (Backend):
```
cd backend
npm run dev
```
Terminal 2 (Frontend):
```
cd frontend
npm run dev
```
Access the Application
- Frontend: http://localhost:5173
- Backend API: http://localhost:5000

📁 Project Structure

Frontend Components

Features

CodeGenerator: Generate and display hackathon codes
QRLogin: QR code upload and scanning
QRManagement: Admin QR code generation and management
TeamRegistrationForm: Team creation and member management
EntryLogTable: Track participant entries
HackathonSetupForm: Create new hackathons

Layout

Layout: Main application layout wrapper
Navbar: Top navigation bar
Sidebar: Side navigation menu
ProtectedRoute: Route authentication wrapper

UI Components

Button: Reusable button component
CodeInput: Code entry input field
QRDisplay: Display QR codes
StatsCard: Dashboard statistics cards
StatusBadge: Status indicators
PhaseIndicator: Hackathon phase display

Backend Structure

Models

User: User accounts with roles and QR tokens
Hackathon: Hackathon events and configurations
Team: Team information and members
Analysis: AI analysis results

Controllers

qrController: QR code generation, verification, download
ai.controller: AI-powered resume and GitHub analysis
participant.controller: Participant operations
team.controller: Team management

Services

qrService: QR code generation and image creation
ai.service: AI analysis integration

🔐 Authentication System

Manual Code Authentication

User enters hackathon code (e.g., AERO-2026-HC1234)
Selects role (Admin/Judge/Participant)
Enters role-specific code
System validates and creates session

QR Code Authentication

Generation:
- Admin generates QR codes for all roles
- JWT token embedded in QR code
- Token hash stored in database
- QR codes downloadable as ZIP
Verification:
- User uploads QR code image
- Frontend scans and extracts JWT token
- Backend verifies JWT signature and token hash
- Session created on successful verification
Security:
- SHA-256 token hashing
- 7-day token expiry
- Reusable QR codes (not one-time)
- Token invalidation support

Flow Diagram

User → Upload QR → Scan Token → Verify JWT → Check Hash → Create Session → Dashboard

🤖 AI Features

Resume Analysis

Parsing: Extract text from PDF/DOCX resumes
Skill Extraction: Identify technical and soft skills
Experience Analysis: Parse work experience and education
Scoring: Overall resume quality score (0-100)
Recommendations: Improvement suggestions

GitHub Analysis

Repository Metrics: Stars, forks, commits, contributors
Code Quality: Language distribution, file structure
Activity Analysis: Commit frequency, recent activity
Collaboration: Team contribution patterns

Team Compatibility

Skill Matching: Complementary skill sets
Experience Balance: Mix of junior/senior developers
Domain Expertise: Relevant project experience
Diversity Score: Varied backgrounds and skills

📡 API Documentation

Base URL

http://localhost:5000/api/v1

Authentication Endpoints

Verify QR Token

POST /qr/verify
Content-Type: application/json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response:
{
  "success": true,
  "user": {
    "userId": "...",
    "name": "John Doe",
    "email": "john@example.com",
    "role": "participant",
    "roleCode": "P-A3F9K2H8"
  },
  "hackathon": {
    "hackathonCode": "AERO-2026-HC1234",
    "name": "AeroHacks 2026"
  },
  "sessionToken": "..."
}

Generate QR Codes

POST /qr/generate
Content-Type: application/json

{
  "hackathonId": "AERO-2026-HC1234",
  "role": "participant",
  "userId": "user_id_here"
}

Response:
{
  "success": true,
  "qrCode": "data:image/png;base64,..."
}

Download QR Codes (ZIP)

GET /qr/download/:hackathonId?role=participant

Response: ZIP file download

AI Endpoints

Analyze Resume

POST /ai/analyze-resume
Content-Type: multipart/form-data

file: resume.pdf

Response:
{
  "success": true,
  "analysis": {
    "parsedInfo": {
      "name": "John Doe",
      "email": "john@example.com",
      "skills": ["JavaScript", "React", "Node.js"],
      "experience": [...]
    },
    "scores": {
      "overall": 85,
      "technical": 90,
      "experience": 80
    },
    "recommendations": [...]
  }
}

Analyze GitHub

POST /ai/analyze-github
Content-Type: application/json

{
  "githubUrl": "https://github.com/username/repo"
}

Response:
{
  "success": true,
  "analysis": {
    "repository": {
      "name": "repo-name",
      "stars": 100,
      "forks": 20,
      "commits": 500
    },
    "metrics": {
      "codeQuality": 85,
      "activity": 90,
      "collaboration": 75
    }
  }
}

Team Endpoints

Register Team

POST /teams/register
Content-Type: application/json

{
  "teamName": "Team Awesome",
  "hackathonCode": "AERO-2026-HC1234",
  "members": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "role": "Team Lead"
    }
  ]
}

Get Team Details

GET /teams/:teamId

Response:
{
  "success": true,
  "team": {
    "teamName": "Team Awesome",
    "members": [...],
    "submissions": [...],
    "score": 85
  }
}

🔧 Environment Variables

Backend (.env)

Variable	Description	Example
`MONGO_URI`	MongoDB connection string	`mongodb+srv://...`
`JWT_SECRET`	Secret key for JWT signing (min 64 chars)	`your-secret-key...`
`QR_TOKEN_EXPIRY`	QR token expiration time	`7d`
`PORT`	Backend server port	`5000`
`FRONTEND_URL`	Frontend URL for CORS	`http://localhost:5173`
`NODE_ENV`	Environment mode	`development`

Frontend (.env)

Variable	Description	Example
`VITE_BACKEND_URL`	Backend API base URL	`http://localhost:5000`

🧪 Testing

Test Data

After running setupTestDatabase.js, you'll have:

Hackathon Code: AERO-2026-HC1234

Role Codes:

Admin: A-12345678
Judge: J-87654321
Participant: P-A3F9K2H8

QR Codes: Located in backend/test-qr-codes/

Manual Testing

Manual Login:
- Go to http://localhost:5173
- Enter hackathon code
- Select role
- Enter role code
- Verify dashboard access
QR Login:
- Click "Upload QR" tab
- Upload QR from test-qr-codes/
- Verify instant login
Admin Features:
- Generate new QR codes
- Download QR ZIP
- Manage hackathon phases
- View all teams
Participant Features:
- Register team
- Upload resume
- Submit GitHub repo
- View AI feedback

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Coding Standards

Follow ESLint configuration
Use meaningful variable names
Add comments for complex logic
Write clean, maintainable code
Test before committing

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Team

Decrypters

Pratham Kataria - @Pratham21223

🙏 Acknowledgments

React and Vite teams for amazing tools
MongoDB for robust database solution
Tailwind CSS for beautiful styling
Hugging Face for AI capabilities
All open-source contributors

📞 Support

For support, email prathamkataria@example.com or open an issue on GitHub.

🗺️ Roadmap

Real-time notifications with WebSockets
Email integration for QR code distribution
Advanced analytics dashboard
Mobile app (React Native)
Multi-hackathon support
Sponsor management
Prize distribution system
Live streaming integration

Name		Name	Last commit message	Last commit date
backend		backend
docs		docs
frontend		frontend
scripts		scripts
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation