hxqlabs/helixque

1. Overall shape

Helixque is a two-part application: a Next.js frontend for the user experience and a Node.js + TypeScript backend that acts as the real-time signaling and matchmaking service. The actual video/audio media is peer-to-peer via WebRTC; the backend does not carry media streams.

2. Frontend boundary

The frontend lives under frontend/ and uses the Next.js App Router. Its job is to manage pages, user interaction, device permissions, local UI state, and the browser-side RTCPeerConnection lifecycle. It is the only part that touches camera/microphone APIs directly.

3. Frontend page structure

The main routes are app/page.tsx (entry/landing), create-room, match, room/[roomId], and a test-toasts utility page. The room/[roomId] route is the core call experience, while match and create-room are entry points into the session flow.

4. Frontend RTC subsystem

Most call logic is concentrated in frontend/components/RTC/. Room.tsx appears to be the top-level coordinator for an active session, with supporting pieces for the video grid, control bar, device checks, timeout alerts, and chat UI. hooks.tsx and webrtc-utils.tsx likely encapsulate WebRTC state management and signaling helpers so the UI stays separate from connection mechanics.

5. Frontend UI composition

The frontend also includes a small reusable UI layer under components/ui/ for toasts, tooltips, shimmer buttons, cards, and similar presentation concerns. This is a supporting layer rather than a core architectural boundary, but it matters because the room experience is built from these reusable pieces.

6. Backend responsibility

The backend under backend/src/ is the real-time coordination service. It handles Socket.IO signaling, user presence, queueing/matching, room lifecycle, and likely chat/event relaying. This service is stateful enough to track who is waiting, who is matched, and which room a user belongs to.

7. Backend internal subsystems

The main backend modules are:

- managers/UserManger.ts for user/session state and queue behavior

- managers/RoomManager.ts for room creation, membership, and cleanup

- match/Matchmaker.ts for preference-based pairing logic

- chat/chat.ts for messaging

- cache/presence.ts and cache/redis.ts for shared presence/cache support

- index.ts as the server entry point wiring everything together

8. Matching and session flow

A typical flow is: a user opens the frontend, connects to the backend over Socket.IO, enters the matchmaking queue, and the backend pairs them using preference data. Once matched, the backend creates or assigns a room and instructs one side to initiate WebRTC offer/answer exchange. This is where the app transitions from “matching” to “active room.”

9. Signaling data path

After pairing, the frontend and backend exchange offers, answers, and ICE candidates through Socket.IO events. The backend relays these messages between peers and tracks room membership so each candidate or SDP message reaches the correct counterpart. This signaling layer is the critical bridge between the browser UI and the peer-to-peer media connection.

10. Presence, skips, and disconnect handling

The backend also manages user presence and room cleanup so the app can handle leaving, skipping, and partner disconnects cleanly. The README’s event list indicates the system supports queue:next, queue:leave, and partner:left, which suggests the backend is responsible for recovering the session state when one side exits.

11. Redis and scale-out boundary

cache/redis.ts and the README’s Redis notes indicate optional Redis-backed coordination for presence or multi-instance deployment. That means the architecture can run in a single-process mode for development, but can also be extended to multiple backend instances where shared state is needed.

12. External infrastructure

The app expects a NEXT_PUBLIC_BACKEND_URL in the frontend and PORT, CORS_ORIGINS, and optional REDIS_URL in the backend. The README also notes TURN servers for production WebRTC reliability, which is important because peer-to-peer media may fail without relay in restrictive networks.

13. Diagramming guidance

If you’re drawing the architecture, the main boxes are:

- Browser client / Next.js frontend

- Socket.IO signaling backend

- Optional Redis shared cache

- External TURN/STUN infrastructure

- Direct WebRTC peer-to-peer media path between two browsers

The key distinction is that signaling and matchmaking go through the backend, while audio/video flows directly between peers once the connection is established.