Skip to content
BranchesTags

Repository files navigation

MiniCode

MiniCode Next.js FastAPI Python PostgreSQL

The Modern Coding Arena for Colleges & Clubs

A full-stack coding arena that combines real GitHub workflows with an AI-powered judge, role-based learning paths, live events, XP progression, and faculty/admin operations.

Features • Quick Start • Documentation • Contributing

Table of Contents

Overview

MiniCode transforms competitive programming from a cold, intimidating terminal experience into an engaging, gamified learning journey. Built for:

  • Students who want to practice coding with real GitHub workflows
  • Clubs that run hackathons and coding events
  • Faculty who need analytics and student tracking
  • Admins who manage the platform

What Makes MiniCode Different

Traditional Judges MiniCode
Raw terminal aesthetics Modern SaaS UI with animations
Fear-based feedback AI Mentor that empowers
Solo practice Real GitHub workflow integration
Static problems Dynamic events & team collaboration
Mysterious scoring Transparent XP & level progression

Features

Core Features

  • GitHub-Native Workflow - Students code in their own private repositories
  • AI-Powered Judge - Gemini-powered code evaluation with detailed feedback
  • Role-Based Access - Student, Faculty, and Admin roles with distinct workflows
  • XP & Levels - Gamified progression system with leaderboards
  • Learning Paths (Roadmaps) - Curated streams (Cybersecurity, AI/ML, Web Dev, Data Science, Cloud & DevOps, Mobile Development, Blockchain, System Design, Open Source) with milestone-based progression
  • Dynamic Milestone Generation - New milestones auto-created by AI as you complete them
  • AI Stream Chatbot - Per-stream assistant answering questions about that learning path
  • AI-Generated Learning Materials - Personalized hints and resources for each milestone
  • Events System - Hackathons, contests, and team collaboration
  • Real-time Updates - WebSocket-powered submission status
  • AI Plagiarism Detection - Identifies AI-generated submissions
  • Cohorts & Labs - Organized student groups for faculty management
  • Dynamic Email Verification - Secure student email verification flow correctly routing codes to users
  • CI/CD Pipeline - Automated testing, linting, and deployment via GitHub Actions
  • Code Execution Sandbox - Isolated Docker-based execution for Python, Node.js, and Java with seccomp security profiles
  • Collaborative Coding - Real-time collaborative sessions with WebSocket-based synchronization
  • Discussion Forum - Per-problem threaded discussions with voting and markdown support
  • AI Chatbot Assistant - Platform-wide AI assistant for coding help, hints, and explanations
  • Achievements & Badges - Gamified achievement system with unlockable badges and progress tracking
  • Streaks - Daily login streaks with motivational tracking and rewards
  • Contests - Timed coding competitions with live leaderboards and auto-scoring
  • Team Formation - Matchmaking system for finding coding partners and forming teams
  • Code Reviews - Peer code review system with inline comments and approval workflow
  • Plugin System - Extensible plugin architecture for custom functionality
  • Code Snippets - Reusable code snippet library with search and voting
  • Learning Dashboard - Personalized recommendations and weak area analysis
  • Interview Mode - Simulated technical interview environment with timed sessions
  • Portfolio Pages - Public portfolio profiles with XP charts and activity heatmaps
  • External Judges - Import and sync submissions from LeetCode, Codeforces, and CodeChef
  • Dark Mode - System-aware dark mode with toggle support

Authentication

  • GitHub OAuth - Primary student login
  • Google OAuth - Faculty/Admin institutional login (@scet.ac.in auto-faculty)
  • Username/Password - Development and fallback

For Faculty

  • Problem creation with AI generation assistance
  • Student analytics and submission tracking
  • XP awarding and progress monitoring
  • Event management
  • Cohort and lab organization

For Admins

  • User role management
  • Global system statistics
  • XP synchronization
  • Platform configuration

Architecture

┌───────────────────────────────────────────────────────────────────────┐
│                             MINICODE STACK                            │
├───────────────────────────────────────────────────────────────────────┤
│                                                                       │
│  ┌──────────────┐        ┌──────────────────────────────────────────┐ │
│  │              │        │                                          │ │
│  │   Student    │───────▶│           FRONTEND                       │ │
│  │   Browser    │        │     Next.js 16 + React 19                │ │
│  │              │        │     - App Router                         │ │
│  └──────────────┘        │     - Tailwind CSS                       │ │
│                          │     - Real-time WebSockets               │ │
│                          └─────────────────┬────────────────────────┘ │
│                                            │                          │
│                          ┌─────────────────▼────────────────────────┐ │
│                          │                                          │ │
│                          │          BACKEND API                     │ │
│                          │     FastAPI + SQLModel                   │ │
│                          │     - REST Endpoints                     │ │
│                          │     - Auth Middleware                    │ │
│                          │     - Rate Limiting                      │ │
│                          └──────────────┬───────────────────────────┘ │
│                                         │                             │
│     ┌─────────────────────────────────────────────────────────────────┤
│     │                    │                         │                  │
│     ▼                    ▼                         ▼                  │
│  ┌──────────┐     ┌──────────┐             ┌──────────────┐           │
│  │          │     │          │             │              │           │
│  │  Redis   │     │PostgreSQL│             │  GitHub API  │           │
│  │ (Cache + │◀───▶│ (Data)   │             │  (OAuth +    │           │
│  │  Broker) │     │          │             │    Repos)    │           │
│  └────┬─────┘     └──────────┘             └────────┬─────┘           │
│       │                                             │                 │
│       ▼                                             │                 │
│  ┌──────────────┐                                   │                 │
│  │              │                                   │                 │
│  │     Celery   │◀──────────────────────────────────┘                 │
│  │     Worker   │                                                     │
│  │    (Judge)   │         ┌──────────────────────────┐                │
│  └────┬─────────┘         │                          │                │
│       │                   │         Gemini AI        │                │
│       └──────────────────▶│        (AI Judge)        │                │
│                           │                          │                │
│                           └──────────────────────────┘                │
│                                                                       │
└───────────────────────────────────────────────────────────────────────┘

Tech Stack

Layer Technology Version
Frontend Next.js 16+
UI Framework React 19
Styling Tailwind CSS 4+
Backend FastAPI 0.115+
Database SQLModel + PostgreSQL 15
Cache/Broker Redis + Celery 5.4+
AI Judge Google Gemini 2.5
Auth JWT + OAuth2 -
Container Docker 24+
Sandbox Docker + seccomp Python/Node/Java
CI/CD GitHub Actions Auto-test + lint
WebSocket FastAPI WebSockets Real-time collab
Plugin Engine Python import hook Extensible modules

Repository Structure

Minicode/
├── frontend/                  # Next.js application
│   ├── src/
│   │   ├── app/            # App Router pages (roadmap, faq, terms, privacy, problems, events, contests, interviews, ...)
│   │   ├── components/      # React components (AchievementBadge, ChatAssistant, CodeReviewPanel, ...)
│   │   ├── contexts/       # React contexts (ThemeContext, AuthContext)
│   │   ├── lib/           # Utilities & API wrappers
│   │   └── styles/        # Global styles
│   └── public/            # Static assets
├── backend/                 # FastAPI application
│   ├── routers/           # API route handlers (problems, contests, collab, reviews, plugins, ...)
│   ├── core/              # Database & SQLModel definitions (models for all features)
│   ├── services/          # Business logic (auth, judge, sandbox, collab_manager, achievement_service, ...)
│   ├── sandbox/           # Code execution sandbox (runner.py, Dockerfiles, seccomp profile)
│   ├── plugins/           # Plugin system (extensible via Python import hooks)
│   ├── utils/             # Shared utilities (caching, sandbox helpers)
│   ├── worker.py          # Celery worker
│   └── scripts/          # DB migration & seeding
├── Docs/                    # Documentation (USER_MANUAL, DEPLOYMENT, DESIGN_VISION, ...)
├── .github/workflows/      # GitHub Actions CI/CD pipeline
├── docker-compose.yml       # Full local stack
├── .env.example         # Environment template
└── README.md            # This file

Quick Start

Prerequisites

  • Docker & Docker Compose
  • GitHub OAuth App credentials
  • Google OAuth credentials (optional for faculty)
  • Gemini API key

1. Clone & Configure

git clone https://github.com/your-repo/Minicode.git
cd Minicode
cp .env.example .env

2. Set Environment Variables

Edit .env with your credentials:

# Essential
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GEMINI_API_KEY=your_gemini_api_key
JWT_SECRET=your_jwt_secret

# Security (generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")
FERNET_KEY=your_fernet_key

# Optional
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

3. Start the Stack

docker-compose up -d --build

Access points:

4. Development Accounts

Seed data provides:

Role Username Password
Admin admin admin123
Faculty faculty faculty123
Student student student123

Environment Variables

Essential

Variable Description Example
DATABASE_URL PostgreSQL connection string postgresql://...
REDIS_URL Redis connection string redis://localhost:6379
CELERY_BROKER_URL Celery broker URL redis://...
GITHUB_CLIENT_ID GitHub OAuth App ID Iv1.xxx
GITHUB_CLIENT_SECRET GitHub OAuth App Secret xxx
GEMINI_API_KEY Google AI API Key AIza.xxx
JWT_SECRET JWT signing secret (32+ bytes) hex-encoded
FERNET_KEY Token encryption key FernetKey

Optional

Variable Description
GOOGLE_CLIENT_ID Google OAuth App ID
GOOGLE_CLIENT_SECRET Google OAuth App Secret
CORS_ORIGINS Allowed frontend origins
FRONTEND_API_URL Backend URL for frontend
RESEND_API_KEY Email provider API key
SMTP_EMAIL / SMTP_PASSWORD SMTP fallback credentials

Documentation

Document Description
API Reference Interactive Swagger/OpenAPI documentation (auto-generated)
USER_MANUAL.md Complete user guide by role
backend/Dev.md Backend developer reference (models, APIs, sandbox, plugins)
DEPLOYMENT.md Deployment guide
DESIGN_VISION.md UI/UX design philosophy
UI_Blueprint.md Detailed site map and component inventory

Submission Pipeline

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Start     │───▶│    Code     │───▶│   Submit    │───▶│   Pending   │
│  Problem    │    │   Locally   │    │   Code      │    │   Queue     │
└─────────────┘    └─────────────┘    └─────────────┘    └─────┬───────┘
                                                                │
         ┌──────────────────────────────────────────────────────┘
         ▼
┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Fetch     │───▶│   Sandbox   │───▶│   AI Judge  │───▶│   Update    │
│  from GitHub│    │  Execution   │    │  (Gemini)   │    │  & Score    │
└─────────────┘    └─────────────┘    └─────────────┘    └──────┬──────┘
                                                                 │
                                                          ┌──────▼──────┐
                                                          │   Notify    │
                                                          │ (WebSocket) │
                                                          └─────────────┘
  1. Start Problem - Creates private GitHub repository
  2. Code Locally - Student writes solution with Git commits
  3. Submit - Triggers async evaluation pipeline
  4. Pending - Celery worker picks up task
  5. Fetch - Worker retrieves code from GitHub
  6. Sandbox Execution - Runs code in isolated Docker container with seccomp security (Python/Node/Java)
  7. AI Judge - Gemini analyzes code, test results, and provides detailed feedback
  8. Update - Stores score, feedback, XP, achievements, and streak
  9. Notify - Real-time WebSocket and Redis pub/sub update to UI

Troubleshooting

Common Issues

Issue Solution
OAuth login fails Verify callback URLs match frontend origin
Submissions stuck pending Check Celery worker and Redis
Repo creation fails Ensure FERNET_KEY is stable
AI judge error Verify GEMINI_API_KEY and quota
WebSocket disconnect Check Redis connectivity

Debug Commands

# View logs
docker-compose logs -f backend
docker-compose logs -f celery_worker

# Restart services
docker-compose restart backend frontend

# Check health
curl http://localhost:8000/health

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit changes (git commit -m 'Add amazing feature')
  4. Push to branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Built with passion for the next generation of developers

About

MiniCode is a full-stack coding ecosystem that integrates GitHub workflows, AI-powered evaluation, gamification, and academic management tools into a single platform.

minicode-web.vercel.app

Resources

Readme
MIT license
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages