From f1c6ca7efd28593bbab4b353c03e87eb7ead6443 Mon Sep 17 00:00:00 2001 From: Rajkumar Date: Mon, 21 Sep 2026 14:18:07 +0530 Subject: [PATCH] docs: make the project ready for outside contributors Rexial was public but not actually contributable: there was no license, and the setup instructions pointed at a repository name that no longer exists, so a new contributor failed at the clone step. Licensing - Add MIT LICENSE. Without it the repository was implicitly all-rights-reserved, so nobody could legally fork or contribute. Fix the stale Qtrive naming - setup.md cloned TheCodeHeist-Coder/Qtrive, which does not resolve - Navbar linked to the same dead repository - Rename the package and dev container names to Rexial Deliberately left as Qtrive: POSTGRES_DB, DATABASE_URL and the docker volume names (renaming orphans existing local dev databases), and the 'Qtrive-auth' localStorage key (renaming logs out every current user). These are runtime state, not branding. Documentation - Rewrite README: the previous one ended mid-code-block with an unclosed fence and had no license or contributing section - Point the demo link at demo.mp4 rather than the space-containing filename - Rename contribution.md to CONTRIBUTING.md so GitHub links it automatically on every new issue and pull request - Fix the placeholder clone URLs inside it - Add ROADMAP.md, CODE_OF_CONDUCT.md and SECURITY.md Issue and PR templates - Add bug report and feature request forms with required fields, so reports arrive with reproduction steps instead of one-line summaries - config.yml links to good first issues, setup and architecture docs - Add a pull request template Verified: pnpm lint (19 pre-existing frontend errors, unchanged), check-types and build all pass; frontend tsc --noEmit is clean. Co-Authored-By: Claude Opus 5 (1M context) --- .github/ISSUE_TEMPLATE/bug_report.yml | 90 +++++++++ .github/ISSUE_TEMPLATE/config.yml | 14 ++ .github/ISSUE_TEMPLATE/feature_request.yml | 76 ++++++++ .github/pull_request_template.md | 53 ++++++ .gitignore | 3 + CODE_OF_CONDUCT.md | 123 +++++++++++++ contribution.md => CONTRIBUTING.md | 6 +- LICENSE | 21 +++ README.md | 201 +++++++++++---------- ROADMAP.md | 61 +++++++ SECURITY.md | 77 ++++++++ apps/frontend/src/components/Navbar.tsx | 2 +- apps/frontend/src/screens/Signup.tsx | 2 +- docker-compose.yml | 12 +- package.json | 2 +- planning.md | 2 +- setup.md | 4 +- 17 files changed, 642 insertions(+), 107 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/pull_request_template.md create mode 100644 CODE_OF_CONDUCT.md rename contribution.md => CONTRIBUTING.md (96%) create mode 100644 LICENSE create mode 100644 ROADMAP.md create mode 100644 SECURITY.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..35aba3f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,90 @@ +name: Bug report +description: Something in Rexial is not working the way it should +title: "[Bug]: " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to report this. The more precisely you can + describe what happened, the faster it can be fixed. + + - type: textarea + id: what-happened + attributes: + label: What happened? + description: Describe the bug, and what you expected instead. + placeholder: | + When a participant joins with a code that has expired, the screen stays + blank instead of showing an error. + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Steps to reproduce + description: Numbered steps someone else can follow to see the same thing. + placeholder: | + 1. Host creates a quiz and generates a join code + 2. Wait for the code to expire + 3. Open the join page and enter that code + 4. Screen goes blank, nothing in the UI explains why + validations: + required: true + + - type: dropdown + id: service + attributes: + label: Which part of Rexial? + description: Select all that seem involved. Unsure is a fine answer. + multiple: true + options: + - frontend (React) + - http-server (Express REST API) + - ws-server (WebSockets) + - genAI (Python / FastAPI) + - database (Prisma / PostgreSQL) + - Docker / deployment + - CI / GitHub Actions + - Not sure + validations: + required: true + + - type: dropdown + id: how-running + attributes: + label: How are you running Rexial? + options: + - Docker Compose (docker-compose up) + - Locally with pnpm dev + - Deployed instance + - Other + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Logs or error output + description: > + Browser console, terminal output, or container logs. This is + automatically formatted as code, so no backticks needed. + render: shell + + - type: input + id: environment + attributes: + label: Environment + description: OS, Node version, browser — whatever is relevant. + placeholder: "Ubuntu 24.04, Node 20.11, Chrome 130" + + - type: checkboxes + id: checks + attributes: + label: Before submitting + options: + - label: I searched existing issues and this has not been reported + required: true + - label: I am not including any secrets, API keys or passwords in this report + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..9dab042 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,14 @@ +blank_issues_enabled: true +contact_links: + - name: Looking for something to work on? + url: https://github.com/TheCodeHeist-Coder/Rexial/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22 + about: Browse good first issues — each one names the files it touches. + - name: Setup not working? + url: https://github.com/TheCodeHeist-Coder/Rexial/blob/main/setup.md + about: The setup guide covers Docker and non-Docker installs, including the Python AI service. + - name: How does Rexial work internally? + url: https://github.com/TheCodeHeist-Coder/Rexial/blob/main/ARCHITECTURE.md + about: Service boundaries, data model, request flows and design decisions. + - name: Reporting a security vulnerability + url: https://github.com/TheCodeHeist-Coder/Rexial/security/advisories/new + about: Please report security issues privately, not as a public issue. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..7e412c0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,76 @@ +name: Feature request +description: Suggest something Rexial should be able to do +title: "[Feature]: " +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Before opening this, it is worth checking [ROADMAP.md](https://github.com/TheCodeHeist-Coder/Rexial/blob/main/ROADMAP.md) + in case the idea is already planned. + + - type: textarea + id: problem + attributes: + label: What problem would this solve? + description: > + Describe the situation where today's Rexial falls short. Start from the + problem rather than the solution — it often leads somewhere better. + placeholder: | + A host running a long quiz cannot pause it. If something goes wrong in + the room, the timer keeps running and participants lose points. + validations: + required: true + + - type: textarea + id: solution + attributes: + label: What would you like to see? + description: Your proposed solution, as concretely as you can describe it. + validations: + required: true + + - type: dropdown + id: area + attributes: + label: Which part of Rexial would this touch? + multiple: true + options: + - frontend (React) + - http-server (Express REST API) + - ws-server (WebSockets) + - genAI (Python / FastAPI) + - database (Prisma / PostgreSQL) + - Docker / deployment + - Documentation + - Not sure + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives you considered + description: Other approaches, or how you work around this today. + + - type: dropdown + id: contributing + attributes: + label: Would you like to build this? + description: > + Entirely optional — a good idea is valuable whether or not you + implement it. Saying yes just means we will scope it with you first. + options: + - "Yes, I would like to work on it" + - "Yes, but I would need guidance" + - "No, just suggesting the idea" + validations: + required: true + + - type: checkboxes + id: checks + attributes: + label: Before submitting + options: + - label: I searched existing issues and the roadmap for this idea + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..16d9fe1 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,53 @@ +## What does this PR do? + + + +## Related issue + + + +Closes # + +## Type of change + +- [ ] Bug fix +- [ ] New feature +- [ ] Documentation +- [ ] Refactoring +- [ ] Performance +- [ ] Tests +- [ ] Build / CI / deployment + +## Which services does this touch? + +- [ ] `apps/frontend` +- [ ] `apps/http-server` +- [ ] `apps/ws-server` +- [ ] `apps/genAI` +- [ ] `packages/db` (schema or Prisma changes) +- [ ] Docker / CI + +## How did you test this? + + + +## Checklist + +- [ ] I ran `pnpm run lint` +- [ ] I ran `pnpm run check-types` +- [ ] I ran `pnpm run build` +- [ ] The app still starts with `docker-compose up` +- [ ] I updated documentation if this changes behaviour or setup +- [ ] I did not commit any `.env` file, API key or other secret + + + +--- + +First pull request here? [CONTRIBUTING.md](../CONTRIBUTING.md) walks through the +whole process, and a checkbox left unticked is not a problem — say so and we +will help. diff --git a/.gitignore b/.gitignore index 7ff26ec..49eecf4 100644 --- a/.gitignore +++ b/.gitignore @@ -40,3 +40,6 @@ yarn-error.log* # Misc .DS_Store *.pem + +# Local scratch: issue bodies to paste into GitHub +ISSUES-TO-CREATE.local.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..e953e26 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,123 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility, apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +Rexial is a project where many contributors are making their first-ever open +source contribution. Dismissing or mocking a beginner's question falls under +unacceptable behavior. If you know the answer, explain it or point to the docs. + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces — the repository, +issues, pull requests, discussions — and also applies when an individual is +officially representing the community in public spaces. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement by opening a +[private security advisory](https://github.com/TheCodeHeist-Coder/Rexial/security/advisories/new) +or by contacting a maintainer directly. + +All complaints will be reviewed and investigated promptly and fairly. All +community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. Violating +these terms may lead to a temporary or permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. Violating +these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +[homepage]: https://www.contributor-covenant.org +[Mozilla CoC]: https://github.com/mozilla/diversity diff --git a/contribution.md b/CONTRIBUTING.md similarity index 96% rename from contribution.md rename to CONTRIBUTING.md index b17c8a4..243b1a7 100644 --- a/contribution.md +++ b/CONTRIBUTING.md @@ -15,14 +15,14 @@ Welcome! This guide will help you make your first contribution to the project. ## 2. Clone Your Fork ```bash -git clone https://github.com//.git -cd +git clone https://github.com//Rexial.git +cd Rexial ``` ## 3. Add Upstream Remote *This lets you sync with the original repository:- ```bash -git remote add upstream https://github.com//.git +git remote add upstream https://github.com/TheCodeHeist-Coder/Rexial.git git remote -v ``` diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..624bfe2 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Rexial Contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 1e1bd6d..4fb6eb7 100644 --- a/README.md +++ b/README.md @@ -1,123 +1,140 @@ -# ***Real-Time Quiz Platform*** +
-## Overview -Rexial is a **real-time quiz hosting platform** where users can create, host, and participate in quizzes seamlessly using a unique join code. It is designed to provide an interactive and engaging experience with live dashboards, avatars, and collaborative hosting. +# Rexial -The platform evolves in multiple versions: +**An open-source real-time quiz platform — host a live quiz, share a code, watch the leaderboard move as people answer.** --**Version 1:** Core real-time quiz system --**Version 2:** AI-powered quiz generation --**Version 3:** Live video-based quiz experience +[![CI](https://github.com/TheCodeHeist-Coder/Rexial/actions/workflows/ci.yml/badge.svg)](https://github.com/TheCodeHeist-Coder/Rexial/actions/workflows/ci.yml) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) +[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md) +[![Good First Issues](https://img.shields.io/github/issues/TheCodeHeist-Coder/Rexial/good%20first%20issue?label=good%20first%20issues)](https://github.com/TheCodeHeist-Coder/Rexial/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) ---- - -## Version - 1 (DEMO-VIDEO) -## [[Watch the Demo video of version-1]](/assets/versio1-video//Screencast%20From%202026-04-18%2000-37-22.mp4) - -## Tech Stack +[Demo](assets/versio1-video/demo.mp4) · [Architecture](ARCHITECTURE.md) · [Setup](setup.md) · [Contributing](CONTRIBUTING.md) · [Good first issues](https://github.com/TheCodeHeist-Coder/Rexial/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) -### Monorepo & Tooling --**TurboRepo** – High-performance monorepo setup --**pnpm Workspaces** – Efficient dependency management +
-### Frontend --**React** – UI development +--- -### Backend --**Node.js + Express** – API and server logic --**WebSockets** – Real-time communication +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. -### Database --**PostgreSQL** – Relational database --**Prisma ORM** – Type-safe database access +Hosts can also upload a PDF and let the AI service write the questions for them. -### Version 2 (AI Features) --**Python** – AI/ML services for quiz generation --**GenAI APIs / LLMs** – Content-based question generation +## Why it might interest you -### Version 3 (Live Streaming) --**WebRTC** – Real-time video/audio communication +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. +- **Monorepo architecture** — Turborepo + pnpm workspaces across four services and a + shared Prisma package. +- **Deployment** — Docker Compose for dev and prod, GitHub Actions CI, Jenkins, nginx. ## Features -### Version 1 – Core Features -- Create and host quizzes -- Unique quiz join code system -- Participants can join using code -- Co-host support -- Real-time quiz flow using WebSockets -- Live dashboard after each question -- Final leaderboard/dashboard at the end -- Random avatar assigned to participants +**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, planned)** — WebRTC host streaming, in-quiz explanations. + +## Architecture + +``` + React frontend + │ + ┌────────────┴────────────┐ + REST API WebSocket + │ │ + ▼ ▼ + http-server ws-server ──────┐ + (Express) (live quiz) │ + │ │ ▼ + └────────────┬────────────┘ Redis + ▼ (pub/sub, + PostgreSQL leaderboard) + (Prisma ORM) + + genAI service (FastAPI) ── PDF → RAG → questions +``` + +| Service | Stack | Port | +|---|---|---| +| `apps/frontend` | React | 5173 | +| `apps/http-server` | Node + Express | 4000 | +| `apps/ws-server` | WebSockets | 8080 | +| `apps/genAI` | Python + FastAPI | 8000 | +| `packages/db` | Prisma + PostgreSQL | 5432 | + +**[Read the full architecture guide →](ARCHITECTURE.md)** — service boundaries, data +model, request flows, caching, and the reasoning behind each decision. + +## Quick start + +**Prerequisites:** Node.js ≥ 20, pnpm ≥ 9, Docker, Docker Compose (Python ≥ 3.11 only +if you are working on the AI service). ---- +```bash +git clone https://github.com/TheCodeHeist-Coder/Rexial.git +cd Rexial +pnpm install +``` -### Version 2 – AI Integration -- Generate quizzes using prompts -- Subject-based quiz generation -- Upload PDFs/PPTs to auto-generate questions -- Smart content understanding using GenAI -- Dynamic quiz creation pipeline +Create the environment files — the exact values are in [setup.md](setup.md): ---- - -### Version 3 – Live Streaming Experience -- Real-time video quiz sessions -- Host-guided quiz interactions -- Interactive learning environment -- Combine live discussion with quiz attempts -- Feedback and explanations during quiz +```bash +cp apps/genAI/.env.example apps/genAI/.env # AI keys are optional +``` ---- +Then start everything: -### DevOps & Deployment --**Docker** – Containerization --**GitHub Actions** – CI/CD pipelines --**AWS** – Cloud hosting and infrastructure +```bash +docker-compose up --build +``` -### Future DevOps Enhancements --**Kubernetes** – Container orchestration --Advanced scaling and monitoring tools +The frontend comes up at **http://localhost:5173**. ---- +> The AI features need free API keys from [Groq](https://console.groq.com/keys), +> [Google AI Studio](https://aistudio.google.com/apikey) and [Tavily](https://tavily.com). +> Without them the rest of the app still runs — only the AI endpoints return an error +> naming the missing key. -## Architecture Overview +Full walkthrough, including running without Docker: **[setup.md](setup.md)** --**Monorepo structure** using TurboRepo --Separate apps/services: - -`frontend` (React) - -`http-server` (Express REST API) - -`ws-server` (WebSockets, live quiz) - -`genAI` (Python / FastAPI – RAG, question generation, chat) --Real-time communication via **WebSockets** --Containerized using **Docker** --CI/CD pipelines via **GitHub Actions** — see [.github/CI-CD.md](.github/CI-CD.md) --Hosted on **AWS** --Future scalability with **Kubernetes** +## Contributing - **[Read the full architecture guide →](ARCHITECTURE.md)** — service -boundaries, data model, request flows, caching, and the design decisions -behind them. +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](https://github.com/TheCodeHeist-Coder/Rexial/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) + are scoped to a few files and say exactly which ones. +- **Want something meatier?** → [help wanted](https://github.com/TheCodeHeist-Coder/Rexial/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) + covers race conditions, RAG caching, and WebSocket scaling. -## Getting Started +[CONTRIBUTING.md](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. -### Prerequisites --Node.js --pnpm --PostgreSQL +Please also read our [Code of Conduct](CODE_OF_CONDUCT.md). To report a security +issue, see [SECURITY.md](SECURITY.md) — do not open a public issue. -### Installation +## Roadmap -```bash -# Clone the repository -git clone +See **[ROADMAP.md](ROADMAP.md)** for what is shipped, in progress, and open for +contribution. -# Install dependencies -pnpm install +## License -# Start development -pnpm dev +[MIT](LICENSE) — free to use, modify and distribute. diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..c80573e --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,61 @@ +# Rexial Roadmap + +Where the project is going. Anything unchecked is open — if you want to work on +something here, open an issue saying so and we will scope it with you. + +## v1 — Real-time quizzes (shipped) + +- [x] Quiz creation and hosting for registered users +- [x] Unique join code, no account needed for participants +- [x] Co-host invitations by email +- [x] Real-time quiz flow over WebSockets +- [x] Live dashboard after every question +- [x] Final leaderboard +- [x] Random avatars for participants +- [x] Quiz history for organisers + +## v2 — AI quiz generation (shipped) + +- [x] PDF upload → generated multiple-choice questions +- [x] Prompt-driven generation (count, difficulty, topic) +- [x] Host review step before anything is saved +- [x] Output validation (exactly 4 options, exactly 1 correct answer) +- [x] RAG question answering over an uploaded PDF (`/ask-pdf`) +- [x] Chat with web search (`/chat`) +- [ ] Regenerate a single question without redoing the whole set +- [ ] Cache the vector store per PDF so repeat requests skip embedding +- [ ] Persist uploaded PDFs between requests +- [ ] PPT and DOCX input alongside PDF + +## v3 — Live video quizzes (planned) + +- [ ] WebRTC host streaming +- [ ] Participant interaction during a live session +- [ ] In-quiz explanations after each question +- [ ] Recording and replay + +## Infrastructure and scaling + +- [x] Dockerised development environment +- [x] GitHub Actions CI (lint, type-check, build) +- [x] Redis for pub/sub and live leaderboards +- [x] WebSocket latency work — 466ms → ~9ms at thousands of concurrent users +- [ ] Horizontal WebSocket scaling across multiple nodes +- [ ] Kubernetes deployment +- [ ] Metrics and monitoring +- [ ] Automated test suite — currently the largest gap +- [ ] Load-testing harness + +## Quality and developer experience + +- [ ] Clear the ~20 eslint errors and make lint a blocking CI gate +- [ ] API documentation for the REST endpoints +- [ ] End-to-end test covering a full quiz run +- [ ] Mobile-responsive leaderboard and quiz screens +- [ ] Accessibility pass on the participant flow + +--- + +Want to pick something up? Check +[good first issues](https://github.com/TheCodeHeist-Coder/Rexial/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) +or read [CONTRIBUTING.md](CONTRIBUTING.md). diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..fad5a7d --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,77 @@ +# Security Policy + +## Reporting a vulnerability + +**Please do not open a public issue for a security vulnerability.** A public +report tells everyone about the weakness before there is a fix. + +Instead, use GitHub's private reporting: + +1. Go to the [Security tab](https://github.com/TheCodeHeist-Coder/Rexial/security/advisories/new) +2. Click **Report a vulnerability** +3. Describe the issue and how to reproduce it + +This creates a private advisory only the maintainers can see. + +> Maintainers: private reporting must be switched on once, under +> Settings → Code security and analysis → Private vulnerability reporting. + +## What to include + +The more of this you can give us, the faster we can act: + +- What kind of issue it is (authentication bypass, injection, XSS, exposed + secret, and so on) +- Which service is affected — `http-server`, `ws-server`, `frontend`, `genAI`, + or the database layer +- File paths and the affected version or commit +- Step-by-step reproduction, ideally with a minimal example +- What an attacker could do with it + +## What to expect + +Rexial is maintained by a small team, so please treat these as intentions +rather than guarantees: + +| Stage | Target | +|---|---| +| Acknowledgement | within 72 hours | +| Initial assessment | within 7 days | +| Fix or mitigation plan | depends on severity, communicated in the assessment | + +We will keep you updated as we work, and credit you in the advisory when the +fix ships unless you would rather stay anonymous. + +## Scope + +Rexial is a self-hosted application, so this policy covers the **code in this +repository**. Your own deployment — your server hardening, your API keys, your +database configuration — is yours to secure. + +Areas worth particular attention: + +- Authentication and JWT handling in `apps/http-server` +- Quiz join-code generation and guessability +- WebSocket message authorisation in `apps/ws-server` — can a participant send + a host-only message? +- File upload handling in `apps/genAI` (PDF parsing) +- Prompt injection through uploaded documents +- Secrets accidentally committed to the repository + +## Out of scope + +- Vulnerabilities in third-party dependencies that already have a public CVE + and an available upgrade — please open a normal issue or PR instead +- Denial of service through sheer traffic volume against a self-hosted instance +- Social engineering of maintainers or contributors +- Findings from automated scanners with no demonstrated exploit + +## Good practice when self-hosting + +- Set a strong, unique `JWT_SECRET` — never the example value from the docs +- Keep `.env` files out of version control (`.gitignore` already covers them) +- Do not expose PostgreSQL or Redis directly to the internet +- Serve the application over HTTPS +- Rotate API keys if you suspect they have leaked + +Thank you for helping keep Rexial and its users safe. diff --git a/apps/frontend/src/components/Navbar.tsx b/apps/frontend/src/components/Navbar.tsx index 54495e3..2537ab5 100644 --- a/apps/frontend/src/components/Navbar.tsx +++ b/apps/frontend/src/components/Navbar.tsx @@ -22,7 +22,7 @@ function Navbar() { {/* Github */} diff --git a/apps/frontend/src/screens/Signup.tsx b/apps/frontend/src/screens/Signup.tsx index cc6ea6d..019f306 100644 --- a/apps/frontend/src/screens/Signup.tsx +++ b/apps/frontend/src/screens/Signup.tsx @@ -62,7 +62,7 @@ function Signup() {

- Join the arena of knowledge. Join Qtrive and transform the way you learn through interactive archives. + Join the arena of knowledge. Join Rexial and transform the way you learn through interactive archives.

diff --git a/docker-compose.yml b/docker-compose.yml index ad2d77f..e351fbd 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -3,7 +3,7 @@ services: build: context: . dockerfile: apps/frontend/Dockerfile - container_name: QtriveFrontend + container_name: RexialFrontend ports: - "5173:5173" volumes: @@ -16,7 +16,7 @@ services: build: context: . dockerfile: apps/ws-server/Dockerfile - container_name: QtriveWsServer + container_name: RexialWsServer ports: - "8080:8080" volumes: @@ -37,7 +37,7 @@ services: build: context: . dockerfile: apps/http-server/Dockerfile - container_name: QtriveBackend + container_name: RexialBackend ports: - "4000:4000" volumes: @@ -54,7 +54,7 @@ services: build: context: . dockerfile: apps/genAI/Dockerfile - container_name: QtriveGenAI + container_name: RexialGenAI ports: - "8000:8000" volumes: @@ -75,7 +75,7 @@ services: db: image: postgres:15-alpine - container_name: Qtrive_db + container_name: Rexial_db ports: - "5432:5432" environment: @@ -93,7 +93,7 @@ services: redis: image: redis:7-alpine - container_name: Qtrive_redis + container_name: Rexial_redis ports: - "6379:6379" command: redis-server --requirepass thisistheredisPassword --bind 0.0.0.0 diff --git a/package.json b/package.json index ed9dbc1..3294bf2 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "name": "Qtrive", + "name": "rexial", "private": true, "scripts": { "build": "turbo run build", diff --git a/planning.md b/planning.md index 4ff01c1..8f0cc3a 100644 --- a/planning.md +++ b/planning.md @@ -116,6 +116,6 @@ AI work stays out of the Node servers and can scale on its own. ## Schema planning... - #### Here is the basic version of schema of Qtrive + #### Here is the basic version of schema of Rexial ![alt text]() diff --git a/setup.md b/setup.md index bc6291c..9ef85be 100644 --- a/setup.md +++ b/setup.md @@ -29,8 +29,8 @@ #### (1) Now, fork & clone the repository ```bash -git clone https://github.com/TheCodeHeist-Coder/Qtrive.git -cd Qtrive +git clone https://github.com/TheCodeHeist-Coder/Rexial.git +cd Rexial ``` #### (2) Install pnpm globally if not installed