DebugLab 🚀

An Open-Source Real-Time Competitive Programming, Code Debugging & Contest Management Platform.

DebugLab is an end-to-end, high-performance platform designed for hosting debugging challenges, algorithmic competitive programming contests, and fast-paced buzzer events. It features an integrated Monaco code editor, multi-language automated code judge execution inside Docker containers, real-time Socket.IO timer and leaderboard updates, and granular admin controls.

---

🛠 Features

💻 Participant Portal (/client)

• Monaco Code Editor: Rich in-browser IDE with offline capabilities, syntax highlighting, line numbers, auto-closing brackets, and multi-language support (C, C++, Python, Java, JavaScript).
• Real-Time Synchronized Timer: Server-authoritative wall-clock timer synchronization via WebSockets (Socket.IO) ensuring zero timer drift across participants.
• Interactive Leaderboard: Instant leaderboard updates on submission results with score tracking, penalty calculations, and contest ranking.
• Segmented Domain Access: Isolated authentication and contest routing for Debug and Buzzer contest participants.

🛡 Admin Dashboard (/admin)

• Live Contest Duration Control: Dynamic real-time duration modifications (add extra minutes or reduce duration on-the-fly) without interrupting ongoing contests.
• Problem & Test Case Management: Intuitive dashboard to create, update, and manage problem statements, sample test cases, hidden test cases, and memory/time constraints.
• User & Participant Domain Segmentation: Dedicated management for debug_users, buzzer_users, and administrative staff. Bulk user import tools included.
• Complaint & Dispute Resolution System: In-platform ticketing system for handling participant queries and complaint status updates.

⚙ Backend & Judge Sandbox (/server)

• Multi-Language Judge Engine: Automated compilation and test case execution for C, C++, Python, Java, and JavaScript.
• Docker Container Sandboxing: Isolated execution of user submissions inside lightweight Docker containers (alpine) with CPU/memory limits and non-root execution.
• Native Host Fallback: Seamless fallback to host execution if Docker is unavailable, ensuring uninterrupted service.
• Bulk Participant Import: CLI utility to rapidly import participant accounts from text files into PostgreSQL with single-pass password hashing and transaction rollback safety.
• PostgreSQL Relational Storage: Optimized schema for high-concurrency submission logging, leaderboard recalculations, and contest tracking.
• Robust Auth & Security: JWT-based session security, password hashing with bcrypt, Helmet headers, CORS policies, and rate-limiting middleware.

---

🏗 Architecture Overview

graph TD
    subgraph Frontend Applications
        A[Client Participant Portal - React/Vite]
        B[Admin Control Panel - React/Vite]
    end

    subgraph Backend Infrastructure
        C[Express 5 REST API]
        D[Socket.IO Real-Time Server]
        E[Judge Execution Service]
    end

    subgraph Storage Layer
        F[(PostgreSQL Database)]
    end

    A <-->|REST API / JWT| C
    B <-->|REST API / JWT| C
    A <-->|WebSockets| D
    B <-->|WebSockets| D

    C -->|Queries & Transactions| F
    C -->|Trigger Code Runs| E
    E -->|Execute & Compare Output| C

Loading

---

📁 Repository Structure

debuglab/
├── client/              # Participant frontend application (React + Vite + Monaco)
│   ├── src/             # Components, pages, context providers, Monaco setup
│   ├── .env.example     # Client environment variable template
│   └── package.json
├── admin/               # Administrative dashboard (React + Vite + Lucide)
│   ├── src/             # Admin controllers, contest controls, user managers
│   ├── .env.example     # Admin environment variable template
│   └── package.json
├── server/              # Express backend server & execution judge
│   ├── src/
│   │   ├── config/      # System configurations
│   │   ├── controllers/ # REST API route controllers
│   │   ├── db/          # PostgreSQL database initialization & schema SQL
│   │   ├── middleware/  # JWT auth, CORS, rate limiters
│   │   ├── routes/      # Express routes (auth, contests, problems, submissions)
│   │   ├── services/    # Code judge runner & language execution engines
│   │   └── index.js     # Entry point & Socket.IO server initialization
│   ├── .env.example     # Server environment variable template
│   └── package.json
├── package.json         # Root workspace scripts (runs client, admin, server concurrently)
├── CONTRIBUTING.md      # Open-source contribution guidelines
└── LICENSE              # MIT License

---

🚀 Quick Start Guide

Prerequisites

Make sure you have the following installed on your local development machine:

• Node.js: v18.0.0 or higher
• npm: v9.0.0 or higher
• PostgreSQL: v14 or higher
• Docker: Docker Engine / Docker Desktop (Optional, for containerized sandbox execution via alpine)
• Compilers / Runtimes (for native code judge testing fallback): gcc, g++, python3, openjdk-17-jdk, node

1. Clone the Repository

git clone https://github.com/mas173/DebugLab.git
cd debuglab

2. Install Dependencies

Install dependencies for all workspace modules at once using root script:

# Install root workspace dependencies
npm install

# Install dependencies for client, admin, and server
cd client && npm install && cd ..
cd admin && npm install && cd ..
cd server && npm install && cd ..

3. Environment Variables Setup

Copy .env.example files to .env across all workspace folders:

Backend Server (server/.env)

cp server/.env.example server/.env

Edit server/.env:

PORT=5000
NODE_ENV=development

DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=your_postgres_password
DB_NAME=debuglab

JWT_SECRET=your_super_secret_jwt_key
JWT_EXPIRES_IN=30d

CLIENT_ORIGIN=http://localhost:5173
ADMIN_ORIGIN=http://localhost:5174

ADMIN_USERNAME=admin
ADMIN_PASSWORD=admin123

Client Portal (client/.env)

cp client/.env.example client/.env

VITE_API_URL=http://localhost:5000

Admin Dashboard (admin/.env)

cp admin/.env.example admin/.env

VITE_API_URL=http://localhost:5000

4. Database Setup & Initialization

Create the database in PostgreSQL and initialize the schema:

# Log into PostgreSQL CLI or pgAdmin and create the database:
createdb -U postgres debuglab

# Initialize database schema and admin seed user
cd server
npm run start # Will run dbInit automatically on initial server startup

5. Running the Application

From the repository root directory, run all services concurrently:

npm run dev

This starts:

• 🟢 Server: http://localhost:5000
• 🔵 Client Portal: http://localhost:5173
• 🟡 Admin Dashboard: http://localhost:5174

---

🐳 Docker Code Sandbox Setup

DebugLab uses Docker containers to run participant submissions in an isolated sandbox environment.

1. Requirements & Image Setup

Make sure Docker Engine / Docker Desktop is running on your machine, then pull the alpine image:

docker pull alpine

2. Sandbox Security Controls

The judge service (server/src/services/judgeService.js) launches code inside Docker using strict flags:

• Memory Limit: --memory=256m (Prevents memory exhaustion attacks)
• PID Limit: --pids-limit=64 (Prevents fork bombs)
• Privilege Control: --security-opt=no-new-privileges:true
• Automatic Cleanup: --rm (Instantly removes containers after execution)

3. Graceful Fallback

If Docker is not running or unavailable on the host machine, DebugLab automatically falls back to native host execution with a console warning.

---

👥 Bulk User Import Utility

DebugLab includes a fast CLI script for batch creating participant user accounts (ideal for onboarding student groups or contest participants).

1. Populate Username List

Add target usernames (one per line) to server/users.txt:

USER-101
USER-102
USER-103

2. Run Bulk Import Command

Execute the import script from either the root directory or the server directory:

# From root directory:
npm run import-users

# OR from server directory:
cd server
npm run import-users

3. Features & Safeguards

• Default Password: Accounts are created with default password user1234.
• Performance Optimized: Hashes the default password once using bcrypt to efficiently process hundreds of users without CPU delay.
• Transaction Safety: Runs inside a single PostgreSQL database transaction (BEGIN / COMMIT / ROLLBACK). If any fatal error occurs, changes roll back completely.
• Duplicate Protection: Automatically skips usernames that already exist in the database and outputs a summary.
• Status Initialization: Automatically creates participant tracking records in participant_status.

---

📡 API Overview

Endpoint	Method	Description	Auth Required
/api/auth/login	POST	Authenticate user (admin / debug / buzzer domain)	No
/api/contests	GET	List active & upcoming contests	Yes
/api/contests/:id	GET	Retrieve contest details	Yes
/api/contests/:id/time	PUT	Add or reduce contest duration in real-time	Admin
/api/problems	GET	Retrieve problem set for a contest	Yes
/api/submissions	POST	Submit solution for execution & scoring	Yes
/api/leaderboard/:contestId	GET	Fetch current leaderboard standings	Yes
/api/monitoring/health	GET	System health check & metrics	Admin

---

🤝 Contributing

We welcome open-source contributions from developers of all skill levels! Whether you are fixing bugs, improving documentation, adding new feature support, or optimizing code execution performance.

Please read our CONTRIBUTING.md guide for detailed instructions on branch naming conventions, development setup, code quality standards, and pull request workflows.

---

📄 License

DebugLab is open-source software licensed under the MIT License. Feel free to use, modify, and distribute it.

---

Made with ❤️ for competitive programmers and contest organizers worldwide.