Skip to content
devnaldoPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

2 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

πŸš€ HackMatch β€” Smart Hackathon Team Builder & Collaboration Platform

TypeScript React Node.js Express.js PostgreSQL Prisma ORM Redis Socket.IO Tailwind CSS Docker License: MIT

HackMatch is a full-stack, real-time web platform engineered to solve one of the biggest challenges in collegiate and professional hackathons: forming balanced, high-performing teams quickly and efficiently.

The platform combines an algorithmic compatibility engine, instant WebSocket messaging, project idea brainstorm boards, and hackathon tracking into a responsive interface designed for both organizers and hackers.


🌟 Key Highlights & Features

  • 🎯 Algorithmic Compatibility Engine: Quantifies user-to-user and team-to-user synergy scores based on required skills, tech stack complementarity, experience level, and hackathon interest.
  • ⚑ Real-Time Collaboration (WebSockets): Low-latency team chat powered by Socket.IO featuring live typing indicators, room broadcasting, and instant activity alerts.
  • πŸ”” Instant Notification Hub: Real-time push notifications for team invitations, join requests, approval status updates, and deadline reminders.
  • πŸ’‘ Project Ideation Marketplace: Brainstorm, submit, and upvote project concepts categorized by domain (AI, Web3, FinTech, HealthTech, etc.) with direct linking to active teams.
  • πŸ›‘οΈ Robust Security Architecture: Stateless JWT authentication with salted BCrypt password hashing, request rate-limiting, and role-based access control (RBAC).
  • πŸ“Š Admin Moderation & Insights: Dedicated admin panel providing platform telemetry, active user filtering, and user moderation controls.
  • πŸ§ͺ One-Command Mock Seeder: Pre-populates realistic hackers, hackathons, skills, and active teams for instant demonstration out of the box.

πŸ—οΈ System Architecture

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                 Client Layer (React 19 + Vite)              β”‚
β”‚      Tailwind CSS  β”‚  Zustand Stores  β”‚  Socket.io Client   β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                               β”‚ HTTP / REST & WebSockets
                               β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚               Backend Layer (Node.js + Express)             β”‚
β”‚   Rate Limiter  β”‚  JWT Auth Guard  β”‚  Zod Schema Validation β”‚
β”‚   Controllers   β”‚  Matching Logic  β”‚  Socket.io Event Bus   β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
               β”‚                              β”‚
               β–Ό                              β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚      Prisma ORM (Data)      β”‚ β”‚     Redis 7 (Pub/Sub)       β”‚
β”‚  PostgreSQL 16 Multi-Model  β”‚ β”‚   Session & Event Caching   β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

πŸ› οΈ Technology Stack

Domain Technologies & Libraries
Frontend React 19, TypeScript, Vite, Tailwind CSS, Lucide Icons, Axios
State Management Zustand (Stateless client-side stores)
Backend Node.js (v20+), Express.js, TypeScript
Database & ORM PostgreSQL 16, Prisma ORM 6
Real-Time & Caching Socket.IO, Redis 7 (ioredis)
Security & Utilities JSON Web Tokens (jsonwebtoken), BCrypt.js, express-rate-limit, Zod
API Documentation Swagger / OpenAPI 3.0 (swagger-ui-express, swagger-jsdoc)
DevOps & Containers Docker, Docker Compose, Multi-stage builds

πŸ“ Repository Structure

hackMatch/
β”œβ”€β”€ backend/                  # Express + TypeScript REST & WebSocket Server
β”‚   β”œβ”€β”€ prisma/               # Prisma Database Schema & Migrations
β”‚   β”‚   └── schema.prisma     # Relational models (Users, Teams, Hackathons, Messages)
β”‚   β”œβ”€β”€ src/
β”‚   β”‚   β”œβ”€β”€ config/           # DB, Redis, and Swagger configurations
β”‚   β”‚   β”œβ”€β”€ controllers/      # Request handlers (Auth, Teams, Matches, Ideas)
β”‚   β”‚   β”œβ”€β”€ middleware/       # JWT Authentication & Rate limiting
β”‚   β”‚   β”œβ”€β”€ routes/           # API router declarations
β”‚   β”‚   β”œβ”€β”€ services/         # Algorithmic matching & Socket.io service
β”‚   β”‚   β”œβ”€β”€ utils/            # Data formatting and helper utilities
β”‚   β”‚   β”œβ”€β”€ seed.ts           # Automatic database seeder
β”‚   β”‚   └── server.ts         # Server entrypoint and WebSocket initialization
β”‚   β”œβ”€β”€ .env.example          # Backend environment variable template
β”‚   β”œβ”€β”€ Dockerfile            # Multi-stage production container
β”‚   β”œβ”€β”€ package.json          # Backend dependencies and scripts
β”‚   └── tsconfig.json         # TypeScript configuration
β”œβ”€β”€ client/                   # React 19 + TypeScript + Vite Single Page Application
β”‚   β”œβ”€β”€ src/
β”‚   β”‚   β”œβ”€β”€ api/              # Axios instance and interceptors
β”‚   β”‚   β”œβ”€β”€ components/       # Reusable UI components (Cards, Badges, ChatWindow)
β”‚   β”‚   β”œβ”€β”€ pages/            # Page views (Dashboard, Hackathons, Teams, Profile)
β”‚   β”‚   β”œβ”€β”€ store/            # Zustand global state (Auth, Notifications)
β”‚   β”‚   β”œβ”€β”€ types/            # TypeScript interfaces and shared types
β”‚   β”‚   └── utils/            # Matching logic, avatar generator, and socket client
β”‚   β”œβ”€β”€ .env.example          # Frontend environment variable template
β”‚   β”œβ”€β”€ Dockerfile            # Nginx production container
β”‚   β”œβ”€β”€ package.json          # Frontend dependencies and scripts
β”‚   └── vite.config.ts        # Vite build tool configuration
β”œβ”€β”€ docker-compose.yml        # Orchestration for PostgreSQL, Redis, Backend & Client
β”œβ”€β”€ package.json              # Root monorepo manager with concurrent execution
β”œβ”€β”€ .gitignore                # Comprehensive Git ignore rules
β”œβ”€β”€ LICENSE                   # MIT Open-Source License
└── README.md                 # Project documentation (This file)

⚑ Quick Start Guide

You can run HackMatch either using Docker Compose (recommended for zero-config setup) or manually via Node.js.

Option A: Running with Docker Compose (Recommended)

Make sure you have Docker Desktop installed and running.

  1. Clone the repository:

    git clone https://github.com/your-username/hackMatch.git
    cd hackMatch
  2. Start all services:

    docker compose up --build
  3. Access the application:


Option B: Local Manual Setup

Prerequisites

  • Node.js: v18.x or later (v20+ recommended)
  • PostgreSQL: Running locally on port 5432
  • Redis: Running locally on port 6379

1. Setup Environment Variables

Copy the sample environment files in both folders:

# In the backend directory
cp backend/.env.example backend/.env

# (Optional) In the client directory
cp client/.env.example client/.env

Ensure the DATABASE_URL in backend/.env points to your PostgreSQL instance:

DATABASE_URL="postgresql://postgres:yourpassword@localhost:5432/hackmatch?schema=public"
REDIS_URL="redis://localhost:6379"
JWT_SECRET="your_custom_jwt_secret_key_make_it_long_and_secure"

2. Install Dependencies

From the repository root, install dependencies for the root, backend, and client:

npm run install-all

3. Initialize & Seed the Database

Run Prisma migrations and populate mock data:

# Push schema to PostgreSQL
npm run db:push

# Generate Prisma client
npm run db:generate

# Populate initial hackathons, mock hackers, and teams
npm run db:seed

4. Launch Development Servers

Run both the backend API and Vite client concurrently:

npm run dev

πŸ”‘ Default Test Accounts (From Seeder)

When the database is seeded (npm run db:seed), the following accounts are ready to test:

Role Email Password Details
Admin admin@hackmatch.com admin123 Full access to moderation & admin panel
Full Stack Hacker alex@mit.edu password123 React, Node.js, TypeScript specialist
AI / ML Hacker sarah@stanford.edu password123 Python, PyTorch, LangChain specialist
UI/UX Hacker david@berkeley.edu password123 Figma, Tailwind, Next.js specialist

πŸ“‘ REST API Reference

HackMatch provides a documented RESTful API. Below is a summary of primary endpoints:

Method Endpoint Description Auth Required
POST /api/auth/register Register a new hacker profile No
POST /api/auth/login Authenticate user and receive JWT No
GET /api/auth/me Fetch authenticated user details Yes
GET /api/hackathons List all hackathons (supports filtering) No
GET /api/hackathons/:id Retrieve hackathon details & teams No
POST /api/hackathons/:id/interested Toggle interest/registration Yes
GET /api/teams List open teams and requirements No
POST /api/teams Create a new hackathon team Yes
GET /api/match/teammates Get smart teammate recommendations Yes
POST /api/requests/join Send request to join an active team Yes
POST /api/requests/invite Invite a user to your team Yes
GET /api/ideas Browse community project ideas No
POST /api/ideas/:id/upvote Upvote a project idea Yes
GET /api/messages/:teamId Retrieve team chat message history Yes
GET /api/notifications Fetch user notification stream Yes
GET /api/admin/stats Access platform metrics Admin

Explore the full interactive request/response schemas at /api-docs when the server is running.


🧠 Smart Matching Algorithm Breakdown

The matching engine scores compatibility between a user $U$ and a candidate/team $C$ using a weighted multi-factor heuristic:

  1. Tech Stack & Skill Overlap ($40%$): Jaccard similarity coefficient applied across desired technical competencies and candidate skills.
  2. Experience Level Synergy ($25%$): Balances seniority tiers (Beginner, Intermediate, Advanced) to promote productive team dynamics.
  3. Hackathon Mutual Interest ($25%$): Bonus weighting awarded if both parties are registered for the same upcoming competition.
  4. Community Badges & Verification ($10%$): Verified badges boost candidate profile visibility in match queries.

πŸ“„ License

This project is licensed under the MIT License β€” see the LICENSE file for details.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages