CodeVerse Scoreboard

A Real-Time, Sci-Fi Themed Competition Scoreboard

Live, animated, and immersive — built for competitive programming events.

Screenshots · Features · Get Started · Architecture

---

About

CodeVerse Scoreboard is a purpose-built, real-time competition scoreboard designed for multi-round competitive programming events. It automatically scrapes live standings from VJudge, processes and validates submissions, and pushes updates to all connected clients via WebSockets — all wrapped in a stunning sci-fi themed UI with synthesized sound effects.

---

Screenshots

Round 1 — Live Scoreboard

Real-time leaderboard with animated rank changes, problem status cells, and countdown timer

---

Top 3 Podium

Post-round celebration with Gold, Silver, and Bronze podiums + round navigation

---

Features

• Real-Time Updates — WebSocket-powered live scores every ~30 seconds via Socket.IO
• 3-Round Support — Independent rounds with configurable questions and separate leaderboards
• Top 3 Podium — Animated podium view (Gold / Silver / Bronze) with round navigation
• Sci-Fi Sound System — 8 synthesized sound effects using Web Audio API
• Smart Timer — Auto-syncing countdown: Starts in → Ends in → Contest Over
• Fully Responsive — Optimized for desktop, tablet, and mobile with sticky columns
• Smooth Animations — Framer Motion spring animations for rank changes and layout shifts

---

Tech Stack

Frontend (/client)

• React 19 · TypeScript · Vite
• Tailwind CSS 4 · Framer Motion
• Socket.IO · React Router 7 · Web Audio API

Backend (/server)

• Express 5 · Socket.IO · CORS
• In-Memory Buffer with versioning

Scraping Script (/script)

• Puppeteer · dotenv · User-Agents

Deployment

• Vercel (frontend) · Render (backend)

---

Architecture

codeverse-scoreboard/
│
├── client/          # React Frontend Application
│   ├── src/
│   │   ├── components/    # Reusable UI components
│   │   ├── pages/         # Page-level components
│   │   └── utils/         # Helper functions and utilities
│   └── public/
│
├── server/          # Express.js Backend
│   └── src/
│       ├── routes/        # API endpoints
│       ├── middleware/    # Auth and other middleware
│       └── bufferController/  # Data buffering logic
│
└── script/          # VJudge Scraping Script
    └── main.js            # Main scraping logic

Data Flow

┌─────────────┐     scrape every 30s     ┌──────────────┐     POST /api     ┌──────────────┐
│   VJudge    │ ────────────────────────► │   Script     │ ────────────────► │   Server     │
│  Contests   │      (Puppeteer)         │  (Node.js)   │   (sanitized)    │  (Express)   │
└─────────────┘                          └──────────────┘                   └──────┬───────┘
                                                                                   │
                                                                          Socket.IO emit
                                                                                   │
                                                                            ┌──────▼───────┐
                                                                            │   Client     │
                                                                            │  (React)     │
                                                                            └──────────────┘

---

Getting Started

Prerequisites

• Node.js ≥ 18
• npm ≥ 9

1. Clone the Repository

git clone https://github.com/your-username/codeverse-scoreboard.git
cd codeverse-scoreboard

2. Setup Environment Variables

Create .env files from the examples in each directory:

client/.env

VITE_BACKEND_URL=http://localhost:4000

server/.env

PORT=4000
KEY=your-secret-api-key

script/.env

KEY=your-secret-api-key

Important

The KEY value must match between server/.env and script/.env for the scraper to authenticate with the backend.

3. Install Dependencies

# Install all dependencies (run from root)
cd client && npm install && cd ..
cd server && npm install && cd ..
cd script && npm install && cd ..

4. Start Development Servers

Open 3 separate terminals:

# Terminal 1 — Backend
cd server
npm run dev

# Terminal 2 — Frontend
cd client
npm run dev

# Terminal 3 — Scraper
cd script
npm run dev

5. Open in Browser

Navigate to http://localhost:5173 — the scoreboard will load and connect via WebSocket.

---

Deployment

Frontend → Vercel

1. Import the client/ directory to Vercel
2. Set the VITE_BACKEND_URL environment variable to your backend URL
3. Vercel auto-detects Vite and builds accordingly (vercel.json handles SPA rewrites)

Backend → Render

1. Import the server/ directory to Render
2. Set PORT and KEY environment variables
3. render.yaml is pre-configured for automatic deployment

Scraper → Any Server / Local Machine

The scraper runs as a long-lived Node.js process. It can be deployed on:

• A VPS (via pm2 or systemd)
• A local machine during the competition
• Any cloud VM

---

License

This project is open source under the ISC License.

---

Acknowledgements

• Backend logic adapted from acmnuceskhi/coderscup-scoreboard-2025 — we appreciate their open-source contribution which served as a foundation for our scoring system.

---

Star this repo if you found it useful!

Made by the CodeVerse Team