Code Arena

A programming competition platform for university teams. Students solve platform-hosted problems, submit solutions, and compete in a real-time leaderboard with automatic code evaluation via Judge0 and real-time updates via WebSocket (MQTT).

What is Code Arena?

An end-to-end platform for managing programming competitions. Teams register for competitions, solve coding problems, and the system automatically awards points based on difficulty. Includes a maze/labyrinth game mode with automatic evaluation, real-time rankings, and an admin dashboard for competition management.

Technology Stack

Backend: FastAPI + Python, MongoDB (Motor async), JWT HS256, Judge0 sandbox, MQTT
Frontend: Next.js 15 + TypeScript, shadcn/ui, Tailwind CSS v4, MQTT WebSocket
Infrastructure: Docker Compose (local), Vercel (backend + frontend), MongoDB Atlas (production)

Structure

code-arena/
├── backend/app/
│   ├── main.py                    # FastAPI app, CORS, routers, rate limiting
│   ├── database.py                # Motor MongoDB async
│   ├── limiter.py                 # Rate limiting (slowapi)
│   ├── routes/                    # auth, users, teams, competition, ranking, maze
│   ├── models_entity/             # Pydantic v2 models
│   └── services/                  # judge0.py (code sandbox), users.py, scoring.py
├── frontend/src/
│   ├── app/                       # Next.js pages: /, /competition/[id], /ranking/[id], /admin/*
│   ├── components/                # Auth, Competition, Team, Navbar, shadcn/ui
│   ├── hooks/                     # useAuth, useToken, useCompetitionSocket
│   └── lib/                       # apiRequest (fetch wrapper), types.ts
├── docs/context.md                # Domain business rules
├── docker-compose.yml             # Mongo + Backend + Frontend
└── .env.example                   # Environment variables

Key Features

• JWT Authentication (120 min expiry, HS256) with bcrypt password hashing
• Team Management with unique codes and configurable member limits
• Competitions with platform-hosted problems evaluated via Judge0, flexible per-difficulty scoring
• Judge0 Integration for automatic code evaluation (Python, Java, C++, JavaScript)
• Maze/Labyrinth Mode with automatic code evaluation for game-like competitions
• Real-time Leaderboard via MQTT WebSocket with no page refresh needed
• Admin Dashboard for competition creation and participant validation
• Rate Limiting to prevent request abuse
• Security with HSTS, CSP, CORS, non-root Docker user

Key Business Rules

• Submissions: Status always AC (accepted). Code is evaluated via Judge0.
• Scoring: Points awarded per competition.scoring[difficulty]. Accumulated in team.points.
• Ranking: Sorted by points DESC, then totalTime ASC.
• Teams: Can participate in multiple competitions. Linked via teamCode in user profile.
• Private Competition: GET /competition/private/{id} returns competition data + team data in a single call.

Quick Start

With Docker Compose (Recommended)

cp .env.example .env
docker compose up --build

Backend: http://localhost:8000, Frontend: http://localhost:3000

See DEPLOY.md for detailed deployment instructions, including manual setup without Docker.

Manual Development

Backend: cd backend && pip install -r requirements.txt && uvicorn app.main:app --reload

Frontend: cd frontend && npm install && npm run dev

Environment Variables

See .env.example for complete reference. Critical variables:

• MONGO_URL, MONGO_DB — MongoDB connection
• SECRET_KEY — JWT signing key
• JUDGE0_API_URL, JUDGE0_API_KEY — Judge0 code evaluation API
• MQTT_HOST, MQTT_USERNAME, MQTT_PASSWORD — Real-time leaderboard WebSocket
• NEXT_PUBLIC_BASE_URL — Backend URL (default: /backend for proxy mode)

Deployment

→ See DEPLOY.md for complete deployment instructions including Docker, Vercel, and MongoDB Atlas setup.

Data Schema

User: {username, email, password, teamCode, is_admin}
TeamCode: {code, points, members[], submissions[{problemId, time, difficulty, points}]}
Competition: {name, date, duration, problems[], scoring{easy/medium/hard}, teams[], createdBy}

Documentation

• DEPLOY.md — Complete deployment and configuration guide
• docs/context.md — Domain model and business rules
• docs/anti-cheat.md — Anti-cheat mechanisms (hidden instructions, watermarks)

License

See LICENSE file for details.

Last updated: August 2026