Skip to content

Daku3011/Minicode

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

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+

Repository Structure

Minicode/
├── frontend/                  # Next.js application
│   ├── src/
│   │   ├── app/            # App Router pages (roadmap, faq, terms, privacy, problems, events, ...)
│   │   ├── components/      # React components
│   │   ├── lib/           # Utilities
│   │   └── styles/        # Global styles
│   └── public/            # Static assets
├── backend/                 # FastAPI application
│   ├── routers/           # API route handlers (roadmap, problems, submissions, auth, ...)
│   ├── core/              # Database & SQLModel definitions
│   ├── services/          # Business logic (auth, judge, email, ai_generator)
│   ├── utils/             # Shared utilities (caching)
│   ├── worker.py          # Celery worker
│   └── scripts/          # DB migration & seeding
├── Docs/                    # Documentation (USER_MANUAL, DEPLOYMENT, DESIGN_VISION, ...)
├── 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
DEPLOYMENT.md Deployment guide
DESIGN_VISION.md UI/UX design philosophy
SKILLS.md Development guidelines

Submission Pipeline

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Start     │───▶│    Code     │───▶│   Submit    │───▶│   Pending   │
│  Problem    │    │   Locally   │    │   Code      │    │   Queue     │
└─────────────┘    └─────────────┘    └─────────────┘    └─────┬───────┘
                                                               │
         ┌─────────────────────────────────────────────────────┘
         ▼
┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Fetch     │───▶│   AI Judge  │───▶│   Update    │───▶│   Notify    │
│  from GitHub│    │  (Gemini)   │    │  & Score    │    │ (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. AI Judge - Gemini analyzes code and test cases
  7. Update - Stores score, feedback, and XP
  8. Notify - Real-time WebSocket 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

License

MIT license
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages