Skip to content
TheCodeHeist-CoderPublic

About

Rexial - An open-source real-time quiz platform — host a live quiz, share a code, watch the leaderboard move as people answer. Hosts can also upload a PDF and let the AI service write the questions for them.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

23 stars

Watchers

0 watching

Forks

Latest commit

 

History

396 Commits

Folders and files

Repository files navigation

Rexial

An open-source real-time quiz platform — host a live quiz, share a code, watch the leaderboard move as people answer.

CI License: MIT PRs Welcome Good First Issues

Demo · Architecture · Setup · Contributing · Good first issues


A host builds a quiz, Rexial generates a join code, and participants join from any device without signing up. Questions advance in real time over WebSockets, scores update after every question, and a final leaderboard closes the session.

Hosts can also upload a PDF and let the AI service write the questions for them.

A look at it

The host opens a lobby and shares the code

Rexial host lobby: a quiz access code above a grid of joined players, with a live count of 751

Participants answer on their own device, and the room watches the answers land

Rexial on a phone: the question, four answer options, a countdown, and a progress bar showing 61 of 751 answered

Scores settle into a leaderboard at the end

Rexial final leaderboard: a podium of the top three, then the ranked list below

The screenshots are from a load test, which is why the players are named Bot1, Bot2 and so on — 751 of them in one session.

Why it might interest you

Rexial is a genuinely distributed real-time system, not a CRUD app with a quiz theme. If you want to work on any of the following, there is real code here to work on:

  • WebSockets at scale — a dedicated ws-server handles live quiz sessions. Recent work took p99 latency from 466ms to ~9ms for thousands of concurrent users.
  • Retrieval-augmented generation — a Python/FastAPI service chunks and embeds PDFs, then generates validated multiple-choice questions.
  • WebRTC at the edge — a self-hosted LiveKit SFU carries live video for up to 300 players, with a small Express service issuing tokens and handling moderation.
  • Monorepo architecture — Turborepo + pnpm workspaces across five services and a shared Prisma package.
  • Deployment — Docker Compose for dev and prod, GitHub Actions CI, Jenkins, nginx.

Features

Live quizzes (v1, shipped)

  • Create and host quizzes, with co-host support via email invite
  • Participants join with a code — no account required
  • Real-time question flow over WebSockets
  • Live dashboard after each question, final leaderboard at the end
  • Random avatar per participant

AI quiz generation (v2, shipped)

  • Upload a PDF and describe what you want ("5 medium questions about chapter 2")
  • Questions land in a review step — edit, fix, or drop them before anything is saved
  • Model output is validated: anything without exactly 4 options and 1 correct answer is discarded rather than shown

Live video quizzes (v3, in progress)

  • The host and co-hosts run the quiz on camera; players watch and listen
  • Players appear only as their avatar, raise a hand, and speak once a host lets them in
  • Up to 300 players per live video session
  • Optional: self-hosted LiveKit over WebRTC, off unless you configure it — see apps/streaming

Architecture

flowchart TB
    SPA["React frontend"]

    HTTP["<b>http-server</b><br/>Express :4000<br/>auth · quiz CRUD"]
    WS["<b>ws-server</b><br/>ws :8080<br/>live gameplay · scoring"]
    AI["<b>genAI</b><br/>FastAPI :8000<br/>PDF → questions"]
    ST["<b>streaming</b><br/>Express :7000<br/>room tokens"]
    LK["<b>LiveKit</b> SFU<br/>WebRTC video"]

    PG[("PostgreSQL<br/>Prisma")]
    RD[("Redis<br/>cache · pub/sub")]

    SPA -->|REST| HTTP
    SPA -->|WebSocket| WS
    SPA -->|PDF upload| AI
    SPA -.->|REST| ST
    SPA ==>|camera + mic| LK

    HTTP --> PG
    WS --> PG
    WS --> RD
    HTTP --> RD
    ST -.-> LK

    classDef optional stroke-dasharray: 6 4
    class ST,LK optional
Loading

Live video (streaming + LiveKit) is optional and off unless configured.

Service Stack Port
apps/frontend React 5173
apps/http-server Node + Express 4000
apps/ws-server WebSockets 8080
apps/genAI Python + FastAPI 8000
apps/streaming Node + Express, LiveKit (optional) 7000
packages/db Prisma + PostgreSQL 5432
apps/admin React (super-admin panel) 5174
apps/admin-server Node + Express (admin API) 5000

The super-admin panel is optional and deployed separately, not through Docker or CI/CD — see apps/admin-server/README.md.

Read the full architecture guide → — service boundaries, data model, request flows, caching, and the reasoning behind each decision.

Quick start

Prerequisites: Node.js ≥ 22, pnpm ≥ 9, Docker, Docker Compose (Python ≥ 3.11 only if you are working on the AI service).

git clone https://github.com/TheCodeHeist-Coder/Rexial.git
cd Rexial
pnpm install

Create the environment files — the exact values are in setup.md:

cp apps/genAI/.env.example apps/genAI/.env   # AI keys are optional

Then start everything:

docker compose up --build

The frontend comes up at http://localhost:5173.

The AI features need free API keys from Groq, Google AI Studio and Tavily. Without them the rest of the app still runs — only the AI endpoints return an error naming the missing key.

Full walkthrough, including running without Docker: setup.md

Contributing

Contributions are welcome, and the issue tracker is organised so you can find something that matches how much time you have.

  • New to the project? → good first issues are scoped to a few files and say exactly which ones.
  • Want something meatier? → help wanted covers race conditions, RAG caching, and WebSocket scaling.

CONTRIBUTING.md is a step-by-step guide written for a first-ever pull request — fork, branch, env setup, commit conventions, and opening the PR.

Please also read our Code of Conduct. To report a security issue, see SECURITY.md — do not open a public issue.

Roadmap

See ROADMAP.md for what is shipped, in progress, and open for contribution.

License

MIT — free to use, modify and distribute.

About

Rexial - An open-source real-time quiz platform — host a live quiz, share a code, watch the leaderboard move as people answer. Hosts can also upload a PDF and let the AI service write the questions for them.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

23 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Contributors

Languages