Skip to content
Jevoel16Public

About

Live, role-based tabulation and rankings for school events

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

RankIT logo

RankIT

Live, role-based tabulation and rankings for school events.

CI Version Platform React

Public live rankings page with the event list, podium and ranked contestants

About · Screenshots · Features · Tech Stack · Architecture · Getting Started · Configuration · Usage


About

RankIT runs the scoring side of school competitions: admins set up events and criteria, tabulators record judges' scores, grievance officers file deductions, and everyone else watches live rankings on a public page. It replaces spreadsheets passed between judges with one auditable system that computes event, category and overall weighted rankings and prints the official reports. The choices behind it are in docs/decisions.md.

Screenshots

Screenshots
Live rankings
Public leaderboard with event list, podium and ranked list
Display mode
Full-screen projector view with podium, places 4 to 7 and a QR code
Tabulator scoring
Score sheet with contestant, judge and per-criterion inputs
Event setup
Admin console creating an event with weighted criteria
Master report
Master results PDF preview with report tabs
Grievance deductions
Standings table with raw average, deductions and final score
Admin analytics
Platform totals and users-by-role donut chart
Light theme
Public leaderboard in the light theme
Phone (tabulator)
Tabulator scoring on a phone with a pinned record button
Phone (live rankings, light)
Public leaderboard on a phone in the light theme

Features

  • Public live leaderboard by event, category and overall weighted ranking
  • Big-screen display mode for projectors, with auto-rotating views and a QR code
  • Role consoles for admin, tabulator and grievance staff, built for phones and tablets
  • Criteria-based and set-based (sports) scoring with automatic rankings
  • Sign in with Google or GitHub, or a username and password set at first sign-in; admins assign roles
  • Ending an event freezes the official results; grievance deductions keep their reasons
  • Master report PDFs, an audit trail and analytics for admins
  • System, light and dark themes

Tech Stack

Layer Tools
Frontend React 19.3.1, React Router 6.30.6, Vite 6.4.5, @react-pdf/renderer 4.9.0, qrcode 1.5.4
Backend Node.js 26.13.1, Express 5.2.1, Mongoose 9.12.0, Zod 4.6.7, Helmet 8.3.0
Database MongoDB (Atlas in production)
Testing and tooling Vitest 4.1.12, Supertest 7.3.1, mongodb-memory-server 11.3.0, ESLint 10.14.0, Prettier 3.10.1
Hosting Vercel (one project: static app + API function), MongoDB Atlas

Architecture

flowchart LR
  Browser --> SPA[React SPA on Vercel]
  SPA -->|/api, session cookie| API[Express API as a Vercel function]
  API --> Controllers --> DB[(MongoDB Atlas)]
  API -->|sign-in| OAuth[Google and GitHub OAuth]
Loading

The API reference is in docs/api.md, the event and request lifecycles in docs/state-machines.md, and the security measures in docs/security.md.

Getting Started

Prerequisites: Node.js 26+, and MongoDB running locally (or an Atlas URI).

cp backend/.env.example backend/.env           # then set JWT_SECRET
npm ci --prefix backend && npm ci --prefix frontend-react
npm run seed:users --prefix backend && npm run seed:events --prefix backend
npm run dev --prefix backend                   # API on http://localhost:5000
npm run dev --prefix frontend-react            # app on http://localhost:3000

The seeders create demo accounts such as mark (admin) and al (tabulator) with the password from SEED_PASSWORD (default 1234). They only run against a local database.

Configuration

The API reads backend/.env; see backend/.env.example, which has Local, Development and Production blocks (only Local is active). The API won't start without MONGODB_URI and JWT_SECRET. The frontend needs no variables in development: Vite proxies /api to the API.

Environment variables
Variable Where Purpose
MONGODB_URI backend MongoDB connection string (required)
JWT_SECRET backend Signs session cookies; use a long random value (required)
JWT_EXPIRES_IN backend Longest a session can last, e.g. 12h; sessions also end after 2 hours idle
APP_URL backend Public URL used for OAuth redirect URIs and the HTTPS redirect (required in production unless Vercel sets the production domain)
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET backend Enables "Continue with Google" (optional)
GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET backend Enables "Continue with GitHub" (optional)
CORS_ORIGIN backend Extra allowed browser origins (optional: the app and API share one origin)
PORT, HOST backend Local server bind (default 5000, 0.0.0.0)
SEED_PASSWORD backend Demo password for the local seeders
VITE_DEV_API_TARGET frontend Where the dev proxy sends /api (default http://localhost:5000)
VITE_API_URL frontend Only if the API is on another origin (default /api)

Usage

  1. Admin creates an event with its criteria (or sets for sports), adds contestants and assigns a tabulator.
  2. Tabulator records each judge's scores; rankings update immediately.
  3. Grievance files deductions with a reason when a rule is broken.
  4. Everyone follows the public page at /; admins choose which events and ranking views are visible. Put /display (or /display/<eventId>) on a projector: it rotates event, category and overall standings every 15 seconds (?seconds=20, ?rotate=0 to pin). Press F for full screen, Space to pause.
  5. Admin ends the event once every judge's scores are in, which freezes the official results, then prints the master report.

New staff sign in with Google or GitHub, set a password, and wait while an admin assigns their role under Users → New sign-ups. Setup steps and the logos to upload are in docs/deployment.md.

Deploying: import the repo into Vercel as one project (root directory = repo root); see docs/deployment.md.

More

Project structure
backend/          Express API: routes, controllers, models, validation, tests, seed scripts
frontend-react/   React app: pages, components (ui kit), hooks, lib, styles
api/              Vercel serverless entry (loads backend/server.js)
docs/             API, security, decisions, state machines, performance, deployment, screenshots, brand assets
.github/          CI workflow, issue and pull request templates
Scripts
Package Script Does
backend npm run dev API with auto-reload
backend npm test API tests (in-memory MongoDB)
backend npm run lint / npm run format ESLint / Prettier
backend npm run seed:users / seed:events Local demo data
backend npm run create:superadmin Superadmin (admin recovery) for any database
backend npm run migrate:accounts One-off upgrade of pre-3.0 accounts (-- --dry-run to preview)
frontend-react npm run dev Dev server with /api proxy
frontend-react npm test / npm run lint / npm run format Unit tests / ESLint / Prettier
frontend-react npm run build / npm run preview Production build / serve it with production headers

Back to top

About

Live, role-based tabulation and rankings for school events

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages