⚔️ CanonForces

The Ultimate Gamified Codeforces Companion

Collaborate. Compete. Conquer.

Transform your competitive programming journey with real-time battles, deep analytics, AI-powered hints, and a gamified ecosystem — all in one platform.

📌 Table of Contents

About the Project
Key Features
Screenshots
System Architecture
Tech Stack
Project Structure
Getting Started
Environment Variables
API Reference
Maintainers

🚀 About the Project

CanonForces is a full-stack multiplayer competitive programming platform built on top of the Codeforces ecosystem. It bridges the gap between isolated practice and community engagement by combining a powerful in-browser IDE, real-time PvP battles, AI-assisted learning, and deep cross-platform analytics.

Why CanonForces?

Your Codeforces submissions and rating history sync automatically
Challenge friends or random opponents to real-time 1v1 coding duels
Compare your Codeforces and LeetCode stats side-by-side with visual charts
Stay consistent with daily POTD challenges, streaks, and leaderboards
Track upcoming contests across Codeforces, LeetCode, CodeChef, AtCoder, and HackerEarth in one feed

📸 Screenshots

Practice Arena	CP IDE with AI Hints

Performance Analytics and 1v1 comparisons	Global Leaderboard

✨ Key Features

Gamified Arena

Feature	Description
1v1 Real-time Battles	Challenge friends or get matched instantly via Redis-backed queues. Both players solve the same problem — fastest correct solution wins coins.
Battle Royale Lobbies	20–30 player "King of the Hill" quiz sessions powered by Gemini-generated questions.
Coin & Streak System	Earn coins for every problem solved, POTD completed, daily streak maintained, or past contest solution uploaded.
Global Leaderboard	Multi-tiered: "Top Earners" (coins) and "Top Solvers" (problems). Includes a weekly POTD-specific board and a sticky "My Rank" footer for users outside the top 50.

Integrated Practice Suite

Feature	Description
Full CP IDE	Monaco Editor + Judge0 API. Multi-language support: C++, Python, Java, JavaScript, TypeScript, C#. Real stdin/stdout, test case runner.
AI Hint System	Gemini-powered progressive hints inside the IDE. Hints reveal incrementally and reduce the coin reward — encouraging you to try first.
Rating-wise Problem Explorer	Browse Codeforces problems filtered by difficulty band (800–1600+). Track per-rating and overall solve progress.
Practice Mode	Progress bars, solved-problem tracking saved to Firestore, and a UI optimized for deep-focus sessions.

Analytics & Growth

Feature	Description
Performance Dashboard	Aggregates rating, rank, max rating, problems solved, and submissions from both Codeforces and LeetCode.
Head-to-Head Comparison	Enter any Codeforces handle to see a rating progression chart capped to your own contest count.
PDF Export	Download a full personal analytics report as a PDF.
Problem-of-the-Day (POTD)	Auto-rotates daily based on a reference date. Admins can override. Solving POTD increments your streak and awards coins.

Social & Discovery

Feature	Description
Cross-Platform Contest Feed	Unified upcoming contest calendar for Codeforces, LeetCode, CodeChef, AtCoder, and HackerEarth.
Contest Archive & Solution Upload	Submit your code to past contest problems. A correct submission triggers the coin reward system.
Follow / Following	Discover and follow other competitive programmers. See suggestions in the sidebar.
User Profiles	Profile photos (Cloudinary), handle linkage, activity, rank, and an expandable stats card.

🏗️ System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Client (Browser)                         │
│         Next.js 14 · Tailwind CSS · ShadCN UI · Framer Motion  │
└────────────────────────────┬────────────────────────────────────┘
                             │ HTTP / WebSocket
          ┌──────────────────┼──────────────────┐
          ▼                  ▼                  ▼
  ┌───────────────┐  ┌──────────────┐  ┌────────────────┐
  │  Next.js API  │  │  Socket.IO   │  │  Firebase Auth │
  │  Routes       │  │  Server      │  │  (Google/Email)│
  └───────┬───────┘  └──────┬───────┘  └────────┬───────┘
          │                 │                   │
          ▼                 ▼                   ▼
  ┌───────────────┐  ┌──────────────┐  ┌────────────────┐
  │  Firestore DB │  │  Redis       │  │  Cloudinary    │
  │  (Users,      │  │  (Matchmak-  │  │  (Profile      │
  │   Problems,   │  │   ing queues,│  │   Photos)      │
  │   POTD, Coins)│  │   Leaderbd.) │  └────────────────┘
  └───────────────┘  └──────────────┘
          │
          ▼
  ┌──────────────────────────────────────────┐
  │              External APIs               │
  │  Codeforces API · LeetCode API           │
  │  Judge0 (Code Execution)                 │
  │  Gemini AI (Hints & Quiz Generation)     │
  │  Contest APIs (CF, LC, CC, AC, HE)       │
  └──────────────────────────────────────────┘

🧰 Tech Stack

Layer	Technology	Purpose
Framework	Next.js 14 (App Router)	SSR, routing, API routes
Language	TypeScript (76.6%)	Type safety across the codebase
Styling	Tailwind CSS + ShadCN UI	Utility-first design system
Auth	Firebase Authentication	Google OAuth + Email/Password
Database	Firestore (Firebase)	Users, problems, POTD, coins, sessions
Real-time	Socket.IO	Live 1v1 battle state synchronization
Queue / Cache	Redis	Matchmaking queues, leaderboard sorting
Code Execution	Judge0 API (via RapidAPI)	Multi-language sandbox execution
Code Editor	Monaco Editor	VS Code-grade in-browser editor
AI	Gemini AI (Google)	Progressive hints + quiz generation
File Storage	Cloudinary	Profile photo upload and delivery
Containerization	Docker	Consistent local and production environments
Testing	Jest	Unit and integration tests
External APIs	Codeforces API, LeetCode API, Contest APIs	Stats sync, problem data, contest calendar

📁 Project Structure

canonforces/
├── .github/                    # GitHub Actions workflows, issue templates
├── public/                     # Static assets (icons, images, fonts)
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── (auth)/             # Auth pages: login, signup
│   │   ├── (dashboard)/        # Protected dashboard layout
│   │   │   ├── home/           # Home feed, follow suggestions
│   │   │   ├── stats/          # Analytics dashboard (CF + LC)
│   │   │   ├── practise/       # Practice arena, rating-wise explorer
│   │   │   ├── potd/           # Problem of the Day
│   │   │   ├── contests/       # Cross-platform contest calendar
│   │   │   ├── leaderboard/    # Global & POTD leaderboards
│   │   │   ├── quiz/           # Battle Royale lobby + 1v1 duels
│   │   │   └── profile/        # User profile, edit, photo upload
│   │   └── api/                # Next.js API routes
│   │       ├── auth/           # Auth helpers (CF handle linking)
│   │       ├── battle/         # Battle session management
│   │       ├── hints/          # Gemini hint generation endpoint
│   │       ├── judge/          # Judge0 proxy (code execution)
│   │       ├── leaderboard/    # Coin/solver ranking endpoints
│   │       ├── potd/           # Daily problem assignment
│   │       └── stats/          # CF/LC stats aggregation
│   ├── components/             # Reusable UI components
│   │   ├── ui/                 # ShadCN base components
│   │   ├── ide/                # Monaco Editor wrapper, test runner
│   │   ├── charts/             # Recharts rating line charts, bar charts
│   │   ├── leaderboard/        # Leaderboard table, rank badge
│   │   ├── problem/            # Problem card, difficulty tag
│   │   └── layout/             # Sidebar, navbar, footer
│   ├── lib/                    # Core utilities and service wrappers
│   │   ├── firebase/           # Firestore helpers, auth config
│   │   ├── redis/              # Redis client, queue helpers
│   │   ├── codeforces/         # CF API client (rating, problems, submissions)
│   │   ├── leetcode/           # LC API client (stats, problems)
│   │   ├── gemini/             # Gemini AI client (hints, quiz gen)
│   │   ├── judge0/             # Judge0 submission + polling
│   │   └── cloudinary/         # Upload helpers
│   ├── hooks/                  # Custom React hooks
│   │   ├── useAuth.ts          # Firebase auth state
│   │   ├── useBattle.ts        # Socket.IO battle state
│   │   └── useLeaderboard.ts   # Real-time leaderboard polling
│   ├── types/                  # TypeScript type definitions
│   └── constants/              # App-wide constants (difficulty bands, etc.)
├── tests/                      # Jest test suites
├── .env.example                # Environment variable template
├── Dockerfile                  # Docker configuration
├── next.config.js
├── tailwind.config.js
├── tsconfig.json
└── package.json

⚡ Getting Started

Prerequisites

Node.js v18+
npm v9+
Firebase project (free Spark plan works)
Redis — optional for local dev, required for 1v1 matchmaking
Judge0 API key via RapidAPI
Gemini API key from Google AI Studio

Local Setup

1. Clone the repository

git clone https://github.com/OpenLake/canonforces.git
cd canonforces

2. Install dependencies

npm install

3. Configure environment variables

cp .env.example .env.local

Fill in your keys — see Environment Variables below.

4. Start the development server

npm run dev

Open http://localhost:3000.

Docker Setup

docker build -t canonforces .
docker run -p 3000:3000 --env-file .env.local canonforces

Running Tests

npm test              # run all tests
npm test -- --watch   # watch mode
npm test -- --coverage

⚙️ Environment Variables

Create a .env.local file in the root directory. All variables prefixed with NEXT_PUBLIC_ are exposed to the browser.

# ─── Firebase ──────────────────────────────────────────────
NEXT_PUBLIC_FIREBASE_API_KEY=your_firebase_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id

# ─── Code Execution (Judge0 via RapidAPI) ──────────────────
NEXT_PUBLIC_JUDGE0_API_KEY=your_rapidapi_key

# ─── Real-time & Queues ────────────────────────────────────
REDIS_URL=redis://localhost:6379        # or your Redis Cloud URL

# ─── AI (Google Gemini) ────────────────────────────────────
GEMINI_API_KEY=your_gemini_api_key

# ─── File Storage (Cloudinary) ─────────────────────────────
NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_cloudinary_api_key
CLOUDINARY_API_SECRET=your_cloudinary_secret

Tip: For local development without Redis, 1v1 matchmaking and real-time leaderboard updates will be unavailable. All other features work without it.

🔌 API Reference

All API routes live under /src/app/api/. Key endpoints:

Method	Route	Description
`GET`	`/api/stats/codeforces?handle=`	Fetch rating, rank, and submission history for a CF handle
`GET`	`/api/stats/leetcode?handle=`	Fetch LeetCode stats for a given username
`GET`	`/api/potd`	Get today's Problem of the Day
`POST`	`/api/potd/solve`	Mark POTD as solved, award coins and increment streak
`POST`	`/api/judge/submit`	Proxy a code submission to Judge0 and return the verdict
`POST`	`/api/hints`	Request a progressive AI hint for a given problem
`GET`	`/api/leaderboard`	Get top earners and top solvers lists
`GET`	`/api/contests`	Fetch upcoming contests across all platforms
`POST`	`/api/battle/create`	Create a new 1v1 battle session
`POST`	`/api/battle/join`	Join an existing battle via invite code

Click to expand Feature Deep Dives

-> AI Hint System

The IDE integrates a Gemini-powered hint engine designed to teach rather than reveal. Hints are tiered:

Hint 1 — Topic: Names the algorithmic category (e.g., "Binary Search on Answer")
Hint 2 — Approach: Describes the high-level strategy without implementation detail
Hint 3 — Algorithm: Outlines the algorithm step-by-step, but leaves the code to you

Each revealed hint reduces the coin reward for that problem. This creates a deliberate trade-off between getting unstuck and maximising your score.

-> Real-time 1v1 Matchmaking

Built on Redis queues + Socket.IO:

User joins the matchmaking queue (LPUSH to Redis)
Server polls the queue; when 2 players are available, it pops them and creates a battle session
Both clients receive a match-found event and are directed to the same battle room
Problem is fetched from the Codeforces API and rendered in the split-pane IDE
Submissions are evaluated by Judge0; the first accepted solution ends the match
Coins are atomically credited to the winner via a Firestore transaction

-> Cross-Platform Stats Dashboard

The analytics page aggregates data from two sources:

Codeforces API — rating history, max rating, rank, contest count, submission count, problem tags
LeetCode API (unofficial) — solved count by difficulty, submission calendar

All data is displayed with Recharts visualizations: rating line charts, bar charts by problem tag, donut charts for difficulty breakdown. Users can also compare head-to-head with any other Codeforces handle, with the x-axis capped to the logged-in user's contest count for a fair comparison.

-> Problem of the Day (POTD)

POTD uses a deterministic daily rotation based on a reference date, so no cron jobs or admin action is required. Admins can override the daily problem via a protected UI. Solving POTD within the day:

Increments your daily streak
Awards coins (scaled by difficulty rating)
Appears on the weekly POTD leaderboard

🛡️ Maintainers

Aviral Saxena
@aviralsaxena16

Kamireddi Jaswanth Kumar
@Jaswanth-Kumar-2007

📄 License

Distributed under the MIT License. See LICENSE for details.

⭐ Star this repo if CanonForces has helped your CP journey!

Built with ❤️ by Aviral Saxena @ Openlake

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

⚔️ CanonForces

📌 Table of Contents

🚀 About the Project

📸 Screenshots

✨ Key Features

Gamified Arena

Integrated Practice Suite

Analytics & Growth

Social & Discovery

🏗️ System Architecture

🧰 Tech Stack

📁 Project Structure

⚡ Getting Started

Prerequisites

Local Setup

Docker Setup

Running Tests

⚙️ Environment Variables

🔌 API Reference

-> AI Hint System

-> Real-time 1v1 Matchmaking

-> Cross-Platform Stats Dashboard

-> Problem of the Day (POTD)

🛡️ Maintainers

📄 License

About

Uh oh!

Releases

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 369 Commits
.github		.github
public		public
src		src
tests		tests
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.firebaserc		.firebaserc
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
MAINTAINERS.md		MAINTAINERS.md
README.md		README.md
jest.config.js		jest.config.js
next.config.js		next.config.js
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

⚔️ CanonForces

📌 Table of Contents

🚀 About the Project

📸 Screenshots

✨ Key Features

Gamified Arena

Integrated Practice Suite

Analytics & Growth

Social & Discovery

🏗️ System Architecture

🧰 Tech Stack

📁 Project Structure

⚡ Getting Started

Prerequisites

Local Setup

Docker Setup

Running Tests

⚙️ Environment Variables

🔌 API Reference

-> AI Hint System

-> Real-time 1v1 Matchmaking

-> Cross-Platform Stats Dashboard

-> Problem of the Day (POTD)

🛡️ Maintainers

📄 License

About

Topics

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages