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.
- π― 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.
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β 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 β
βββββββββββββββββββββββββββββββ βββββββββββββββββββββββββββββββ
| 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 |
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)
You can run HackMatch either using Docker Compose (recommended for zero-config setup) or manually via Node.js.
Make sure you have Docker Desktop installed and running.
-
Clone the repository:
git clone https://github.com/your-username/hackMatch.git cd hackMatch -
Start all services:
docker compose up --build
-
Access the application:
- Frontend App: http://localhost:3000
- Backend API: http://localhost:5000
- Interactive Swagger Docs: http://localhost:5000/api-docs
- Node.js: v18.x or later (v20+ recommended)
- PostgreSQL: Running locally on port
5432 - Redis: Running locally on port
6379
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/.envEnsure 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"From the repository root, install dependencies for the root, backend, and client:
npm run install-allRun 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:seedRun both the backend API and Vite client concurrently:
npm run dev- Frontend Client: http://localhost:5173 (or
http://localhost:3000) - Backend API & Swagger: http://localhost:5000/api-docs
When the database is seeded (npm run db:seed), the following accounts are ready to test:
| Role | 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 |
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-docswhen the server is running.
The matching engine scores compatibility between a user
-
Tech Stack & Skill Overlap (
$40%$ ): Jaccard similarity coefficient applied across desired technical competencies and candidate skills. -
Experience Level Synergy (
$25%$ ): Balances seniority tiers (Beginner, Intermediate, Advanced) to promote productive team dynamics. -
Hackathon Mutual Interest (
$25%$ ): Bonus weighting awarded if both parties are registered for the same upcoming competition. -
Community Badges & Verification (
$10%$ ): Verified badges boost candidate profile visibility in match queries.
This project is licensed under the MIT License β see the LICENSE file for details.