Helixque

<br /> <p align="center"> <a href="https://github.com/HXQLabs/Helixque"> <img src="assets/header.png" alt="Helixque Header" width="100%"> </a> </p> <p align="center"><b>Professional real-time video chat with preference-based matching</b></p> <p align="center"> <a href="https://github.com/HXQLabs/Helixque/blob/main/CONTRIBUTING.md"><b>Contributing Guidelines</b></a> ✦ <a href="https://github.com/HXQLabs/Helixque/releases"><b>Releases</b></a> ✦ <a href="https://github.com/HXQLabs/Helixque/blob/main/CODE_OF_CONDUCT.md"><b>Code Of Conduct</b></a> </p> <div align="center">

<br/>    

</div> <p align="center"> <b>This project is backed by</b> <br/> <br/> <a href="https://vercel.com/oss"> <img alt="Vercel OSS Program" src="https://vercel.com/oss/program-badge.svg" /> </a> <br/> <br/> </p>

Meet Helixque, a professional real-time video chat application that pairs people based on their preferences. Built with WebRTC for secure, low-latency peer-to-peer media and Socket.IO for reliable signaling delivering a modern experience for networking, and collaboration. 🎥

[!IMPORTANT]

Helixque is continuously evolving. Your suggestions, ideas, and reported bugs help us immensely. Do not hesitate to join the conversation on Discord or raise a GitHub issue. We read everything and respond to most.

Note

You can now preview the latest updates and improvements every 2–3 days at the following link: 👉 Helixque-Changes

🚀 Quick Start

Getting started with Helixque is simple:

1. Clone the repository

git clone https://github.com/HXQLabs/Helixque.git
cd Helixque

2. Install dependencies

# Backend
cd backend && npm install

# Frontend
cd ../frontend && npm install

3. Configure environment variables

# Backend: Copy and edit .env.example
cp backend/.env.example backend/.env

# Frontend: Create .env.local
echo "NEXT_PUBLIC_BACKEND_URL=http://localhost:5001" > frontend/.env.local

4. Start development servers

# Terminal 1 - Backend
cd backend && npm run dev

# Terminal 2 - Frontend
cd frontend && npm run dev

Open your browser at http://localhost:3000 and allow camera/microphone access. 🎉

🌟 Features

• Enhanced UI & Layout Enjoy a cleaner, smoother interface with improved stability when switching between users. Seamless navigation and responsive design ensure a premium user experience.

• Seamless Media Switching Toggle between video and audio effortlessly with smooth transitions for uninterrupted conversations. Real-time device management keeps your calls crystal clear.

• Instant Messaging Send and receive messages in real time for seamless communication alongside video calls. Perfect for sharing links, notes, or quick thoughts during conversations.

• One-on-One Video Calling Connect directly with other users for private, high-quality video conversations. WebRTC ensures low-latency, peer-to-peer connections for the best quality.

• Random Connect with Professionals Meet and network with professionals from various fields instantly. Expand your connections effortlessly with intelligent preference-based matching.

• Unlimited Skips No limits on finding the right match. Skip as many times as you need until you find the perfect conversation partner.

🛠️ Local Development

Frontend

The frontend is a Next.js application (App Router) that manages device selection, user preferences, UI state, and the RTCPeerConnection lifecycle.

Development commands:

cd frontend
npm install          # Install dependencies
npm run dev          # Start development server
npm run build        # Build for production
npm start            # Start production server

Environment variables:

Create frontend/.env.local:

NEXT_PUBLIC_BACKEND_URL=http://localhost:5001

Note: Frontend requires HTTPS in production for getUserMedia to function correctly. Device permissions must be granted by the user.

Backend

The backend is a Node.js + TypeScript server providing Socket.IO signaling, user presence, and preference-based matchmaking.

Development commands:

cd backend
npm install          # Install dependencies
npm run dev          # Start development server
npm run build        # Build for production
npm start            # Start production server

Environment variables:

Copy backend/.env.example to backend/.env:

PORT=5001
NODE_ENV=production
CORS_ORIGINS=http://localhost:3000
# Optional: REDIS_URL=redis://localhost:6379
# Optional: STUN/TURN server configuration

Note: Use a TURN server in production to ensure media relay when direct P2P is not possible. For multiple backend instances, configure Socket.IO Redis adapter.

⚙️ Built With

🏗️ Project Structure

Helixque/
├─ backend/              # Signaling server (Node.js + TypeScript)
│  ├─ src/
│  │  ├─ managers/       # UserManager, RoomManager
│  │  └─ index.ts        # Entry point
│  ├─ .env.example
│  └─ package.json
├─ frontend/             # Next.js app (TypeScript)
│  ├─ app/               # App Router pages
│  ├─ components/        # UI + RTC components
│  ├─ .env.local
│  └─ package.json
├─ assets/               # Images and static files
└─ README.md

Core Components

• UserManager (backend) — Queue management, matching logic, presence tracking, and session state
• RoomManager (backend) — Room lifecycle, signaling orchestration, and cleanup operations
• Room (frontend) — RTCPeerConnection lifecycle, media controls, and UI state management

📡 Socket.IO Events

Client → Server

| Event | Description | Payload | |-------|-------------|---------| | offer | Send WebRTC offer | { sdp: string, roomId: string } | | answer | Send WebRTC answer | { sdp: string, roomId: string } | | add-ice-candidate | Send ICE candidate | { candidate: RTCIceCandidate, roomId: string, type: 'sender' \| 'receiver' } | | queue:next | Request next match | — | | queue:leave | Leave queue / room | — |

Server → Client

| Event | Description | Payload | |-------|-------------|---------| | lobby | User joined lobby | — | | queue:waiting | Waiting for a match | — | | send-offer | Instruct client to create/send offer | { roomId: string } | | offer | Deliver remote offer | { sdp: string, roomId: string } | | answer | Deliver remote answer | { sdp: string, roomId: string } | | add-ice-candidate | Deliver remote ICE candidate | { candidate: RTCIceCandidate, type: 'sender' \| 'receiver' } | | partner:left | Remote peer disconnected | { reason?: string } |

🚢 Deployment

Backend (Render / Railway / Heroku)

| Platform | Guide | |----------|-------| | Render | Deploy Node.js app with environment variables | | Railway | Auto-deploy from GitHub with build commands | | Heroku | Use Procfile with npm start |

Deployment steps:

1. Set environment variables (PORT, NODE_ENV, CORS_ORIGINS, optional REDIS_URL and TURN_*)
2. Build and run:

cd backend
npm run build
npm start

Frontend (Vercel / Netlify)

| Platform | Guide | |----------|-------| | Vercel | Automatic Next.js deployment from GitHub | | Netlify | Configure build command: npm run build |

Deployment steps:

1. Set NEXT_PUBLIC_BACKEND_URL to your backend's HTTPS endpoint
2. Deploy using your platform's Next.js build pipeline

Docker: Container examples are included in the project for advanced deployments.

❤️ Community

Join the Helixque community on Discord and GitHub Discussions.

Feel free to ask questions, report bugs, participate in discussions, share ideas, request features, or showcase your projects. We'd love to hear from you!

🛡️ Security

If you discover a security vulnerability in Helixque, please report it responsibly instead of opening a public issue. We take all legitimate reports seriously and will investigate them promptly.

To disclose any security issues, please contact the maintainers through Discord or open a private security advisory on GitHub.

🤝 Contributing

There are many ways