About · Screenshots · Features · Tech Stack · Architecture · Getting Started · Configuration · Usage
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
Live rankings![]() |
Display mode![]() |
Tabulator scoring![]() |
Event setup![]() |
Master report![]() |
Grievance deductions![]() |
Admin analytics![]() |
Light theme![]() |
Phone (tabulator)![]() |
Phone (live rankings, light)![]() |
- 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
| 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 |
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]
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.
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:3000The 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.
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) |
- Admin creates an event with its criteria (or sets for sports), adds contestants and assigns a tabulator.
- Tabulator records each judge's scores; rankings update immediately.
- Grievance files deductions with a reason when a rule is broken.
- 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=0to pin). Press F for full screen, Space to pause. - 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.
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 |










