CtrlK

Official Docs

CodeArena

A full-stack online judge and competitive programming platform — built with Next.js 16, MongoDB, Redis, and Docker-sandboxed code execution.

Next.js 16

React 19

MongoDB

Redis

Docker

Firebase Auth

Socket.IO

Tailwind v4

01What is CodeArena?

CodeArena is an online competitive programming platform that allows users to browse coding problems, write and submit solutions in multiple programming languages, and compete in timed contests — all from a browser-based code editor. The platform judges submitted code automatically by executing it inside isolated Docker containers and comparing its output against predefined test cases.

It is a team-built full-stack application following a monolithic Next.js architecture with a clean separation between frontend features, API controllers, business services, and database models.

Docker Sandbox Execution

Real containerized code runner. Your solutions execute in isolated, secure Docker containers with strict resource limits for fair and safe evaluations.

Multi-Verdict Judge

Beyond pass/fail. Get granular feedback with standard verdicts including ACCEPTED, TLE, MLE, and detailed RUNTIME_ERROR reports.

Firebase + JWT Auth

Real secure login system. Enterprise-grade security combining Firebase for identity and JWT for stateless session management.

Problem Browser

Search, filter, and paginate through challenges by difficulty, tags, or title to find the perfect problem for your skill level.

03Project Status

✅ Implemented & Working

User authentication — register, login, logout, Firebase sync, JWT cookie session
Problem list with search, filter, and pagination
Per-user solved-status lookup on problem browser
Problem detail page and in-browser Monaco code editor
Code submission and verdict evaluation pipeline
Docker sandboxed execution for C++, Python, Java, and JavaScript
Contest, participant, and leaderboard API surfaces
Admin log APIs
User profile pages with activity calendar
Docker Compose stack (MongoDB, Redis, app, docker-proxy)
Prometheus metrics endpoint

🚧 In Progress / Partial

Note

Some sections still use static/mock data on the frontend. The Practice page is a placeholder ("Coming Soon"). Real-time WebSocket UI updates are not fully wired yet, though the Socket.IO + Redis adapter server layer is present.

04System Architecture

CodeArena is a monolithic Next.js application where both the frontend and backend live in the same codebase. The App Router handles page-level rendering while /api/* routes act as a REST API. The architecture separates concerns into Controllers → Services → Models layers within that monolith.

┌─────────────────────────────────────────────────────────┐

│ BROWSER / CLIENT │

│ React 19 · Monaco Editor · Framer Motion · Socket.IO │

└────────────────────────┬────────────────────────────────┘

│ HTTPS + WSS

┌────────────────────────▼────────────────────────────────┐

│ NEXT.JS 16 APP SERVER │

│ Pages (App Router) │ API Routes (/api/*) │

│ Server Components │ Controllers → Services │

│ Middleware (JWT auth) │ Mongoose Models │

└──────────┬──────────────────────────────┬───────────────┘

│ │

┌──────────▼──────────┐ ┌────────────▼──────────────────┐

│ MongoDB (Mongoose)│ │ Redis (Cache + BullMQ Queue) │

│ Users · Problems │ │ Sessions · Job Queue │

│ Submissions │ │ Socket.IO Adapter │

│ Contests · Logs │ └────────────────────────────────┘

└─────────────────────┘

│ Judge Jobs

┌──────────▼──────────────────────────────────────────────┐

│ DOCKER EXECUTION SANDBOX │

│ dockerode → docker-socket-proxy → Docker Engine │

│ Per-submission isolated containers │

│ C++ · Python · Java · JavaScript images │

└─────────────────────────────────────────────────────────┘

Request Lifecycle (Code Submission)

User submits code

Monaco editor POSTs to POST /api/problems/[id]/submit with language and source code.

Auth middleware validates JWT cookie

The request passes through middleware that verifies the user's JWT before reaching the controller.

Submission record created (PENDING)

The submission controller creates a MongoDB document with status PENDING and enqueues a BullMQ job.

Judge worker picks up the job

A BullMQ worker (backed by Redis) processes the job by calling the judge service.

Docker container spun up via dockerode

The judge calls POST /api/evaluation/execute which uses dockerode → docker-proxy → Docker Engine to create a sandboxed container.

Output compared against test cases

Stdout is compared to expected output. Timing and memory are measured. A verdict is produced.

Submission updated in MongoDB

The submission document is updated with the final verdict (e.g., ACCEPTED, WRONG_ANSWER) and execution stats.

Client polls for result

Frontend polls GET /api/evaluation/status or GET /api/submissions/[id] until the verdict is available.

05Project Structure

tree

codearena/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── (pages)/            # Frontend page routes
│   │   │   ├── page.jsx        # Landing page (/)
│   │   │   ├── login/          # /login
│   │   │   ├── signup/         # /signup
│   │   │   ├── problems/       # /problems + /problems/[id]
│   │   │   ├── leaderboard/    # /leaderboard
│   │   │   ├── profile/        # /profile, /profile/[id]
│   │   │   ├── practice/       # /practice (placeholder)
│   │   │   └── test-docker/    # /test-docker (dev tool)
│   │   └── api/                # REST API routes
│   │       ├── auth/           # Auth endpoints
│   │       ├── problems/       # Problem CRUD + submit
│   │       ├── submissions/    # Submission read
│   │       ├── evaluation/     # Judge execution endpoints
│   │       ├── contests/       # Contest management
│   │       ├── user/           # Per-user queries
│   │       ├── users/          # User listing/lookup
│   │       ├── admin/          # Admin log management
│   │       └── health/         # Health check
│   │
│   ├── components/             # Shared UI components
│   │   ├── ui/                 # Shadcn/Radix base components
│   │   ├── layout/             # Header, Footer, Sidebar, Nav
│   │   └── shared/             # Cards, Badges, Loaders, etc.
│   │
│   ├── features/               # Feature-scoped frontend modules
│   │   ├── auth/               # Login/signup forms & logic
│   │   ├── problems/           # Problem list, filters, workspace
│   │   ├── contests/           # Contest UI
│   │   ├── leaderboard/        # Leaderboard UI
│   │   └── profile/            # Profile page sections
│   │
│   ├── controllers/            # API route handlers (thin layer)
│   ├── services/               # Business logic / data layer
│   ├── models/                 # Mongoose schemas
│   ├── middlewares/            # Request middleware
│   └── lib/                    # Utilities & infrastructure
│
├── docker/                     # Docker build scripts
├── redis/                      # Redis config files
├── public/                     # Static assets
├── Dockerfile                  # Multi-stage production build
├── docker-compose.yml          # Production stack
└── package.json

06Data Models

User

Field	Type	Description
`_id`	ObjectId	MongoDB document ID
`uid`	String	Firebase UID (synced from client auth)
`username`	String	Unique display name
`email`	String	User email address (unique)
`passwordHash`	String	bcryptjs-hashed password
`role`	String	Enum: user \| admin
`solvedProblems`	ObjectId[]	References to solved Problem documents
`createdAt`	Date	Account creation timestamp

Problem

Field	Type	Description
`_id`	ObjectId	Document ID
`title`	String	Problem title
`slug`	String	URL-friendly identifier
`difficulty`	String	Enum: easy \| medium \| hard
`tags`	String[]	Algorithm/topic tags (e.g., "dp", "graph")
`description`	String	Markdown problem statement (supports LaTeX via KaTeX)
`inputFormat`	String	Input specification
`outputFormat`	String	Output specification
`testCases`	Array	Array of {input, expectedOutput} objects
`timeLimit`	Number	Time limit in milliseconds
`memoryLimit`	Number	Memory limit in MB
`sampleTestCases`	Array	Publicly visible sample cases

Submission

Field	Type	Description
`_id`	ObjectId	Document ID
`userId`	ObjectId	Reference to User
`problemId`	ObjectId	Reference to Problem
`language`	String	Enum: cpp \| python \| java \| javascript
`code`	String	Raw source code
`verdict`	String	One of the 9 possible verdicts
`executionTime`	Number	Runtime in ms
`memoryUsed`	Number	Memory consumption in KB
`testCaseResults`	Array	Per-test-case result details
`createdAt`	Date	Submission timestamp

Contest

Field	Type	Description
`_id`	ObjectId	Document ID
`title`	String	Contest name
`description`	String	Contest description
`startTime`	Date	Contest start datetime
`endTime`	Date	Contest end datetime
`problems`	ObjectId[]	List of Problem references
`participants`	ObjectId[]	Registered user references
`createdBy`	ObjectId	Admin user reference

07Authentication System

CodeArena implements a dual-layer authentication strategy combining Firebase Auth on the client side with JWT cookies on the server side.

Register / Login (Native)

POST /api/auth/register or POST /api/auth/login — password hashed with bcryptjs, user stored in MongoDB, JWT issued as an HttpOnly cookie.

Firebase Sync

POST /api/auth/sync — client sends Firebase ID token; server verifies it via Firebase Admin SDK, then upserts the user in MongoDB and issues its own JWT cookie.

Authenticated Requests

All protected API routes run through authMiddleware.js which reads and verifies the token HttpOnly cookie using jsonwebtoken.

Logout

POST /api/auth/logout — clears the JWT cookie on the server side.

Security Note

JWT tokens are stored as HttpOnly cookies (not localStorage), protecting them from XSS attacks. The Docker socket is also proxied through tecnativa/docker-socket-proxy to restrict container API access.

08Judge Engine

The judge is the most technically complex subsystem of CodeArena. It compiles and executes user-submitted code inside ephemeral Docker containers, measuring execution time and memory, and comparing output against expected test results.

Supported Languages

C++

Compiled with g++; fastest execution.

Python

Interpreted; python3 runtime.

Java

Compiled with javac and run on JVM.

JavaScript

Run with Node.js runtime.

10Contests

CodeArena supports timed competitive contests. Each contest has a defined start time, end time, and a set of problems. Users can register for a contest and make submissions during the contest window. A leaderboard is computed per-contest based on accepted problems and penalty time.

Contest States

Upcoming — Before startTime; registration is open.
Active — Between startTime and endTime; submissions accepted.
Ended — After endTime; read-only, final leaderboard visible.

11Leaderboard

The platform maintains both a global leaderboard and per-contest leaderboards. Rankings are computed by the leaderboard service from submission data stored in MongoDB. The global leaderboard is accessible at /leaderboard and via GET /api/contests/[id]/leaderboard for contest-specific rankings.

12API Reference — Auth

Method	Endpoint	Auth	Description
POST	`/api/auth/register`	None	Create a new account. Body: {username, email, password}. Sets JWT cookie.
POST	`/api/auth/login`	None	Authenticate with email/password. Sets JWT cookie on success.
POST	`/api/auth/logout`	JWT	Clears the JWT cookie. Logs out the session.
POST	`/api/auth/sync`	Firebase Token	Syncs a Firebase-authenticated user to MongoDB. Issues JWT cookie.

13API Reference — Problems

Method	Endpoint	Auth	Description
GET	`/api/problems`	Optional	List problems with search (?q=), tag filter, difficulty filter, and pagination (?page=&limit=). Returns solved status if authenticated.
GET	`/api/problems/[id]`	Optional	Get a single problem by ID, including description, sample test cases, time/memory limits.
POST	`/api/problems/[id]/submit`	JWT Required	Submit code for a problem. Body: {language, code}. Returns submission ID immediately; judging is async.

14API Reference — Evaluation

Method	Endpoint	Auth	Description
POST	`/api/evaluation/execute`	Internal	Run code in a Docker container. Body: {language, code, stdin}. Returns stdout, stderr, exitCode.
POST	`/api/evaluation/judge`	Internal	Full judge run: execute against all test cases and compute verdict.
POST	`/api/evaluation/test`	JWT Required	Run code against a single custom test input (for the "Run" button). Not recorded as a submission.
GET	`/api/evaluation/status`	JWT Required	Poll for the current verdict of a pending/judging submission. Query: ?id=submissionId.

15API Reference — Contests

Method	Endpoint	Auth	Description
GET	`/api/contests`	None	List all contests (upcoming, active, ended).
POST	`/api/contests`	Admin JWT	Create a new contest.
GET	`/api/contests/[id]`	None	Get contest details including problems list.
POST	`/api/contests/[id]/register`	JWT Required	Register the authenticated user for the contest.
GET	`/api/contests/[id]/participants`	None	List all registered participants for the contest.
GET	`/api/contests/[id]/leaderboard`	None	Fetch the contest leaderboard, ranked by accepted problems and penalty.

16API Reference — Users

Method	Endpoint	Auth	Description
GET	`/api/users`	JWT	List all users (admin use).
GET	`/api/users/[id]`	None	Get public profile data for a user by ID.
GET	`/api/user/problems-status`	JWT Required	Returns the authenticated user's solved/attempted problem list.
GET	`/api/submissions`	JWT Required	List submissions for the authenticated user (or all, for admins).
GET	`/api/submissions/[id]`	JWT Required	Get full details of a specific submission including per-test-case results.
GET	`/api/health`	None	Health check endpoint. Returns server/DB/Redis status.

17API Reference — Admin

Method	Endpoint	Auth	Description
GET	`/api/admin/logs`	Admin JWT	Retrieve all admin action logs with pagination.
GET	`/api/admin/logs/[id]`	Admin JWT	Get a specific admin log entry by ID.

18Page Routes

Route	Auth	Description
`/`	None	Landing page with 3D hero, animations (Three.js, GSAP, Framer Motion)
`/login`	None	Email/password + Firebase login form
`/signup`	None	Registration form with validation (Zod + React Hook Form)
`/problems`	None	Paginated problem browser with search and tag/difficulty filters
`/problems/[id]`	JWT for Submit	Problem detail + Monaco editor + Run + Submit
`/leaderboard`	None	Global user leaderboard
`/profile`	JWT	Own profile page with activity calendar and stats
`/profile/[id]`	None	Public profile view for any user
`/profile/settings`	JWT	Account settings (avatar, username, etc.)
`/userdashboard`	JWT	Personal dashboard: recent submissions, stats, activity
`/practice`	None	Placeholder — "Coming Soon"
`/test-docker`	None (dev)	Debug interface to test Docker execution pipeline

19Local Development Setup

Prerequisites

Node.js 20+, npm, Docker Desktop (required for code execution), and either local MongoDB + Redis services or Docker.

Step 1 — Clone & Install

bash

git clone <repository-url>
cd CodeArena-TeamProject
git checkout development
npm install

Step 2 — Create Environment File

.env.local

MONGODB_URI=mongodb://localhost:27017/codearena
JWT_SECRET=your_super_secret_jwt_key

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password

# Firebase (from Firebase Console → Project Settings → General)
NEXT_PUBLIC_FIREBASE_API_KEY=
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=
NEXT_PUBLIC_FIREBASE_PROJECT_ID=
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=
NEXT_PUBLIC_FIREBASE_APP_ID=
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=

Step 3 — Build Judge Executor Images

bash

npm run docker:build
# Runs docker/scripts/build-images.sh
# Builds: judge-cpp, judge-python, judge-java, judge-js Docker images

Step 4 — Start Dev Server

bash

npm run dev
# App available at http://localhost:3000

20Docker Compose

The repository includes a production-ready docker-compose.yml that wires together all services. It runs the app on port 3001 (mapped from internal 3000).

Services

Service	Image	Port	Purpose
`mongodb`	mongo:latest	27017	Primary database with health check and persistent volume
`redis`	redis:7	6379	Cache, BullMQ queue, Socket.IO adapter; AOF persistence enabled, 256 MB limit
`app`	Local build	3001→3000	Next.js production app; waits for MongoDB and docker-proxy
`docker-proxy`	tecnativa/docker-socket-proxy	2376 (host)	Restricted Docker socket proxy; only exposes CONTAINERS, IMAGES, EXEC, POST

bash

docker compose up -d --build

bash

docker compose -f docker-compose.yml -f docker-compose.dev.yml up

21Environment Variables

Variable	Required	Description
`MONGODB_URI`	✅	Full MongoDB connection string (with auth if applicable)
`JWT_SECRET`	✅	Secret key used to sign/verify JWT tokens — keep this private
`REDIS_HOST`	✅	Redis server hostname (e.g., localhost or redis in Docker)
`REDIS_PORT`	✅	Redis port (default 6379)
`REDIS_PASSWORD`	✅	Redis auth password
`REDIS_URL`	—	Full Redis URL (alternative to HOST/PORT/PASSWORD)
`DOCKER_HOST`	—	Docker API host. Set to http://docker-proxy:2375 in Docker Compose
`NODE_ENV`	—	development \| production
`NEXT_PUBLIC_FIREBASE_API_KEY`	✅	Firebase project API key (client-side)
`NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN`	✅	Firebase auth domain
`NEXT_PUBLIC_FIREBASE_PROJECT_ID`	✅	Firebase project ID
`NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET`	✅	Firebase storage bucket
`NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID`	✅	Firebase messaging sender
`NEXT_PUBLIC_FIREBASE_APP_ID`	✅	Firebase app ID
`NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID`	—	Firebase Analytics measurement ID

22NPM Scripts

Script	Command	Description
`npm run dev`	next dev	Start Next.js development server with hot reload on port 3000
`npm run build`	next build	Create an optimized production build
`npm run start`	next start	Run the production build (requires npm run build first)
`npm run lint`	eslint	Run ESLint across the codebase
`npm run docker:build`	bash docker/scripts/build-images.sh	Build all language executor Docker images for the judge
`npm run prepare`	husky install	Set up Husky Git hooks (auto-runs on npm install)

Git Hooks

Husky + lint-staged is configured to run Prettier on all staged .js, .jsx, .ts, .tsx, .json, .css, .md, .mjs files before each commit, ensuring consistent code formatting.

23Dockerfile (Multi-Stage)

The production Dockerfile uses a 3-stage build to keep the final image lean and secure:

Stage: deps (node:20-alpine)

Installs only npm dependencies. Husky is disabled in CI/Docker via ENV HUSKY=0.

Stage: builder (node:20-alpine)

Copies deps and source, accepts Firebase env vars as build-time ARGs, and runs next build with telemetry disabled.

Stage: runner (node:20-alpine)

Copies only the Next.js standalone output and static assets. Runs as a non-root nextjs user (UID 1001) on port 3000.

24Team

CodeArena was built by a six-person team with specialized responsibilities across backend, frontend, and project leadership.

Team Lead

Rabiul Islam

Backend

Arafat Salehin

Backend

AH Muzahid

Frontend

Shahnawas Adeel

Frontend

Abdullah Noman

Frontend

Ummey Salma Tamanna

CodeArena · Team Project · Next.js 16 · MongoDB · Docker · docs generated April 2026