# hxqlabs/helixque architecture

> Architecture diagram of the GitHub repository hxqlabs/helixque, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hxqlabs/helixque
- Repository: https://github.com/hxqlabs/helixque

## Overview

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.

Main entry points: [`backend/src/index.ts`](https://github.com/hxqlabs/helixque/blob/main/backend/src/index.ts) (Server), [`frontend/components/RTC/Room.tsx`](https://github.com/hxqlabs/helixque/blob/main/frontend/components/RTC/Room.tsx) (RTC Room), [`frontend/app`](https://github.com/hxqlabs/helixque/tree/main/frontend/app) (App Router), [`frontend/app/room/[roomId]/page.tsx`](https://github.com/hxqlabs/helixque/blob/main/frontend/app/room/[roomId]/page.tsx) (Room Call)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App Router<br/>Next.js app"]
  node_home_page["Landing<br/>route<br/>[page.tsx]"]
  node_match_page["Match<br/>route<br/>[page.tsx]"]
  node_create_room_page["Create Room<br/>route<br/>[page.tsx]"]
  node_room_page["Room Call<br/>route<br/>[page.tsx]"]
  node_rtc_room["RTC Room<br/>call coordinator<br/>[Room.tsx]"]
  node_rtc_hooks["RTC Hooks<br/>state/hooks<br/>[hooks.tsx]"]
  node_rtc_utils["WebRTC Utils<br/>signaling helpers<br/>[webrtc-utils.tsx]"]
  node_video_grid["Video Grid<br/>media UI<br/>[VideoGrid.tsx]"]
  node_controls["Control Bar<br/>media controls<br/>[ControlBar.tsx]"]
  node_device_check["Device Check<br/>permissions UI<br/>[DeviceCheck.tsx]"]
  node_chat_ui["Chat UI<br/>messaging UI<br/>[chat.tsx]"]
  node_toasts["UI Kit<br/>shared UI"]
end

subgraph group_backend["Backend"]
  node_backend_entry["Server<br/>[index.ts]"]
  node_matchmaker["Matchmaker<br/>pairing logic<br/>[Matchmaker.ts]"]
  node_user_manager["Users<br/>session/queue state<br/>[UserManger.ts]"]
  node_room_manager["Rooms<br/>room lifecycle<br/>[RoomManager.ts]"]
  node_chat_backend["Chat Relay<br/>message relay<br/>[chat.ts]"]
  node_presence_cache["Presence Cache<br/>shared cache<br/>[presence.ts]"]
end

subgraph group_external["External"]
  node_browser(("Browser<br/>client runtime"))
  node_redis[("Redis<br/>external store")]
  node_socketio(("Socket.IO<br/>signaling transport"))
  node_webrtc(("P2P Media<br/>peer media path"))
  node_turnstun(("TURN/STUN<br/>nat traversal"))
end

node_browser -->|"loads"| node_frontend_app
node_frontend_app -->|"routes"| node_home_page
node_frontend_app -->|"routes"| node_match_page
node_frontend_app -->|"routes"| node_create_room_page
node_frontend_app -->|"routes"| node_room_page
node_room_page -->|"composes"| node_rtc_room
node_rtc_room -->|"uses"| node_rtc_hooks
node_rtc_room -->|"uses"| node_rtc_utils
node_rtc_room -->|"renders"| node_video_grid
node_rtc_room -->|"renders"| node_controls
node_rtc_room -->|"gates"| node_device_check
node_rtc_room -->|"includes"| node_chat_ui
node_rtc_room -->|"uses"| node_toasts
node_browser -->|"signals"| node_socketio
node_socketio -->|"connects to"| node_backend_entry
node_backend_entry -->|"delegates"| node_matchmaker
node_backend_entry -->|"tracks"| node_user_manager
node_backend_entry -->|"manages"| node_room_manager
node_backend_entry -->|"relays"| node_chat_backend
node_backend_entry -->|"shares state"| node_presence_cache
node_presence_cache -->|"backed by"| node_redis
node_matchmaker -->|"pairs from"| node_user_manager
node_room_manager -->|"assigns"| node_user_manager
node_backend_entry -->|"emits"| node_socketio
node_backend_entry -.->|"coordinates"| node_webrtc
node_browser -->|"streams"| node_webrtc
node_webrtc -.->|"falls back to"| node_turnstun
node_match_page -->|"queues"| node_backend_entry
node_create_room_page -->|"creates"| node_backend_entry
node_room_page -->|"joins"| node_backend_entry

click node_frontend_app "https://github.com/hxqlabs/helixque/tree/main/frontend/app"
click node_home_page "https://github.com/hxqlabs/helixque/blob/main/frontend/app/page.tsx"
click node_match_page "https://github.com/hxqlabs/helixque/blob/main/frontend/app/match/page.tsx"
click node_create_room_page "https://github.com/hxqlabs/helixque/blob/main/frontend/app/create-room/page.tsx"
click node_room_page "https://github.com/hxqlabs/helixque/blob/main/frontend/app/room/[roomId]/page.tsx"
click node_rtc_room "https://github.com/hxqlabs/helixque/blob/main/frontend/components/RTC/Room.tsx"
click node_rtc_hooks "https://github.com/hxqlabs/helixque/blob/main/frontend/components/RTC/hooks.tsx"
click node_rtc_utils "https://github.com/hxqlabs/helixque/blob/main/frontend/components/RTC/webrtc-utils.tsx"
click node_video_grid "https://github.com/hxqlabs/helixque/blob/main/frontend/components/RTC/VideoGrid.tsx"
click node_controls "https://github.com/hxqlabs/helixque/blob/main/frontend/components/RTC/ControlBar.tsx"
click node_device_check "https://github.com/hxqlabs/helixque/blob/main/frontend/components/RTC/DeviceCheck.tsx"
click node_chat_ui "https://github.com/hxqlabs/helixque/blob/main/frontend/components/RTC/Chat/chat.tsx"
click node_toasts "https://github.com/hxqlabs/helixque/tree/main/frontend/components/ui"
click node_backend_entry "https://github.com/hxqlabs/helixque/blob/main/backend/src/index.ts"
click node_matchmaker "https://github.com/hxqlabs/helixque/blob/main/backend/src/match/Matchmaker.ts"
click node_user_manager "https://github.com/hxqlabs/helixque/blob/main/backend/src/managers/UserManger.ts"
click node_room_manager "https://github.com/hxqlabs/helixque/blob/main/backend/src/managers/RoomManager.ts"
click node_chat_backend "https://github.com/hxqlabs/helixque/blob/main/backend/src/chat/chat.ts"
click node_presence_cache "https://github.com/hxqlabs/helixque/blob/main/backend/src/cache/presence.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_app,node_home_page,node_match_page,node_create_room_page,node_room_page,node_rtc_room,node_rtc_hooks,node_rtc_utils,node_video_grid,node_controls,node_device_check,node_chat_ui,node_toasts toneBlue
class node_backend_entry,node_matchmaker,node_user_manager,node_room_manager,node_chat_backend,node_presence_cache toneAmber
class node_browser,node_redis,node_socketio,node_webrtc,node_turnstun toneMint
```

## Components

### Frontend

Next.js browser application and call UI

- [App Router](https://github.com/hxqlabs/helixque/tree/main/frontend/app): Next.js app · Top-level routes and shell for the frontend · `frontend/app`
- [Landing](https://github.com/hxqlabs/helixque/blob/main/frontend/app/page.tsx): route · Entry page and general navigation · `frontend/app/page.tsx`
- [Match](https://github.com/hxqlabs/helixque/blob/main/frontend/app/match/page.tsx): route · Matchmaking entry point · `frontend/app/match/page.tsx`
- [Create Room](https://github.com/hxqlabs/helixque/blob/main/frontend/app/create-room/page.tsx): route · Room creation entry point · `frontend/app/create-room/page.tsx`
- [Room Call](https://github.com/hxqlabs/helixque/blob/main/frontend/app/room/[roomId]/page.tsx): route · Active call experience for a room · `frontend/app/room/[roomId]/page.tsx`
- [RTC Room](https://github.com/hxqlabs/helixque/blob/main/frontend/components/RTC/Room.tsx): call coordinator · Coordinates session state, signaling, and room UI · `frontend/components/RTC/Room.tsx`
- [RTC Hooks](https://github.com/hxqlabs/helixque/blob/main/frontend/components/RTC/hooks.tsx): state/hooks · WebRTC and session state helpers · `frontend/components/RTC/hooks.tsx`
- [WebRTC Utils](https://github.com/hxqlabs/helixque/blob/main/frontend/components/RTC/webrtc-utils.tsx): signaling helpers · Connection and signaling utility functions · `frontend/components/RTC/webrtc-utils.tsx`
- [Video Grid](https://github.com/hxqlabs/helixque/blob/main/frontend/components/RTC/VideoGrid.tsx): media UI · Renders local and remote video tiles · `frontend/components/RTC/VideoGrid.tsx`
- [Control Bar](https://github.com/hxqlabs/helixque/blob/main/frontend/components/RTC/ControlBar.tsx): media controls · Call controls such as mute, skip, and leave · `frontend/components/RTC/ControlBar.tsx`
- [Device Check](https://github.com/hxqlabs/helixque/blob/main/frontend/components/RTC/DeviceCheck.tsx): permissions UI · Camera and microphone permission and device validation · `frontend/components/RTC/DeviceCheck.tsx`
- [Chat UI](https://github.com/hxqlabs/helixque/blob/main/frontend/components/RTC/Chat/chat.tsx): messaging UI · In-room chat interface · `frontend/components/RTC/Chat/chat.tsx`
- [UI Kit](https://github.com/hxqlabs/helixque/tree/main/frontend/components/ui): shared UI · Reusable presentation components such as toasts, tooltips, and cards · `frontend/components/ui`

### Backend

Socket.IO signaling and matchmaking service

- [Server](https://github.com/hxqlabs/helixque/blob/main/backend/src/index.ts): Node socket server · Backend entry point wiring Socket.IO, managers, and caches · `backend/src/index.ts`
- [Matchmaker](https://github.com/hxqlabs/helixque/blob/main/backend/src/match/Matchmaker.ts): pairing logic · Preference-based user pairing · `backend/src/match/Matchmaker.ts`
- [Users](https://github.com/hxqlabs/helixque/blob/main/backend/src/managers/UserManger.ts): session/queue state · User presence, queueing, and session state · `backend/src/managers/UserManger.ts`
- [Rooms](https://github.com/hxqlabs/helixque/blob/main/backend/src/managers/RoomManager.ts): room lifecycle · Room creation, membership, and cleanup · `backend/src/managers/RoomManager.ts`
- [Chat Relay](https://github.com/hxqlabs/helixque/blob/main/backend/src/chat/chat.ts): message relay · Backend chat and event relay · `backend/src/chat/chat.ts`
- [Presence Cache](https://github.com/hxqlabs/helixque/blob/main/backend/src/cache/presence.ts): shared cache · Presence and optional shared coordination layer · `backend/src/cache/presence.ts`

### External

Browser APIs and infrastructure outside the repo

- **Browser**: client runtime · End-user browser running the app and local WebRTC stack
- **Redis**: external store · Optional shared state backend for multi-instance deployment
- **Socket.IO**: signaling transport · Event transport between browser clients and backend
- **P2P Media**: peer media path · Direct audio/video transport between browsers
- **TURN/STUN**: nat traversal · External relay and traversal infrastructure for WebRTC

## Connections

- Browser → App Router: loads · Browser opens the Next.js application
- App Router → Landing: routes · App Router serves the landing page
- App Router → Match: routes · App Router serves matchmaking entry
- App Router → Create Room: routes · App Router serves room creation entry
- App Router → Room Call: routes · App Router serves the active room page
- Room Call → RTC Room: composes · Room route mounts the RTC session coordinator
- RTC Room → RTC Hooks: uses · Coordinator relies on WebRTC/session hooks
- RTC Room → WebRTC Utils: uses · Coordinator uses signaling and connection helpers
- RTC Room → Video Grid: renders · Coordinator renders the media grid
- RTC Room → Control Bar: renders · Coordinator renders the call controls
- RTC Room → Device Check: gates · Coordinator checks device permissions before call setup
- RTC Room → Chat UI: includes · Coordinator includes in-room chat
- RTC Room → UI Kit: uses · Coordinator relies on shared presentation components
- Browser → Socket.IO: signals · Browser exchanges match and WebRTC events with backend
- Socket.IO → Server: connects to · Socket transport terminates in the backend server
- Server → Matchmaker: delegates · Server delegates pairing decisions
- Server → Users: tracks · Server tracks users and queue state
- Server → Rooms: manages · Server manages room lifecycle
- Server → Chat Relay: relays · Server relays chat and session events
- Server → Presence Cache: shares state · Server uses shared presence/cache support
- Presence Cache → Redis: backed by · Optional Redis-backed coordination
- Matchmaker → Users: pairs from · Matchmaker consumes queue and preference state
- Rooms → Users: assigns · Room manager assigns matched users to rooms
- Server → Socket.IO: emits · Backend emits signaling events over Socket.IO
- Server → P2P Media: coordinates · Backend coordinates peer connection setup but not media
- Browser → P2P Media: streams · Browsers exchange audio/video directly
- P2P Media → TURN/STUN: falls back to · TURN/STUN assists traversal when direct path is blocked
- Match → Server: queues · Match route initiates matchmaking through the backend
- Create Room → Server: creates · Create-room flow registers a new session with the backend
- Room Call → Server: joins · Room route joins the signaling/session backend