⚡ CodeCraft — Premium Developer Practice Platform

A high-performance, dark-first full-stack coding platform built for mastering algorithmic practice questions in Java, Python, and JavaScript.

Features • Architecture • Tech Stack • Quick Start • API Reference • Contributing

---

🌟 Key Features

• 🎨 Developer-First Dark Aesthetic: Custom HSL dark tokens, glassmorphism cards, seamless transitions, and responsive mobile layouts.
• 🔐 JWT Authentication & Security: Enterprise-grade registration, password hashing (bcrypt), auto token persistence across page refreshes, and route authorization guards.
• 📚 Dynamic Questions Catalog: Language filtering (JavaScript, Python, Java), search bar, difficulty tags (easy, medium, hard), and server-side pagination.
• 💻 Monaco Code Editor: Embedded VS Code-like editor powered by @monaco-editor/react featuring custom codecraft-dark syntax themes and local draft saving (sessionStorage).
• ⚡ Real Sandbox Code Execution: Express execution proxy running Python, JavaScript, and Java code against hidden test cases via Piston API with strict execution time limits.
• 👁️ Solution Modal & Complexity Analysis: Interactive solution viewer displaying approach breakdowns, time complexity, and space complexity badges.
• 📊 User Analytics Dashboard: Interactive statistics showing total problems solved, attempt history, submission accuracy rate, and category progress bars.
• 🛡️ Admin APIs & Metrics: Dedicated endpoint suites for administrative system oversight and dashboard metrics.

---

🏗️ Architecture

                  ┌───────────────────────────────────────────┐
                  │   React 18 Frontend (Vite + Tailwind)    │
                  │   - Monaco Code Editor                    │
                  │   - Auth & Problem Dashboard Context      │
                  └─────────────────────┬─────────────────────┘
                                        │
                                        │ REST API (Axios + JWT Bearer Interceptor)
                                        ▼
                  ┌───────────────────────────────────────────┐
                  │    Express Backend API (Node.js ESM)     │
                  │   ├── Router & Controllers                │
                  │   ├── Auth Guard & Role Middleware        │
                  │   └── Sandbox Execution Manager           │
                  └──────────────┬────────────────────┬───────┘
                                 │                    │
            ┌────────────────────▼────┐          ┌────▼──────────────────────┐
            │  MongoDB Atlas Database │          │ Piston Code Runner Engine │
            │  - Users                │          │ - JS / Python / Java      │
            │  - Questions            │          │ - Timeout Guards (7s)     │
            │  - Submissions          │          └───────────────────────────┘
            └─────────────────────────┘

---

🛠️ Tech Stack

Frontend

• Framework: React 18 (Vite Bundler)
• Styling: Tailwind CSS & Vanilla CSS Design Tokens
• Code Editor: @monaco-editor/react
• Icons: Lucide React
• HTTP Client: Axios with Bearer Interceptors
• Routing: React Router v6

Backend

• Runtime: Node.js (ES Modules)
• Framework: Express.js
• Database: MongoDB Atlas via Mongoose ORM
• Auth: JSON Web Tokens (jsonwebtoken) & bcryptjs
• Execution Proxy: Piston API Runner with isolated sandboxing

---

📁 Directory Structure

CodeCraft/
  ├── .github/                    # GitHub Workflows & Templates
  │   ├── workflows/ci.yml        # CI Pipeline (Lint, Build, Test)
  │   ├── PULL_REQUEST_TEMPLATE.md
  │   └── ISSUE_TEMPLATE/
  ├── frontend/                   # React Frontend (Vite)
  │   ├── src/
  │   │   ├── components/         # Button, Input, Card, Badge, Modal, Skeleton
  │   │   ├── context/            # AuthContext (JWT State Management)
  │   │   ├── hooks/              # Custom Hooks (useQuestions, useQuestionDetail)
  │   │   ├── layouts/            # Responsive Header & App Layout
  │   │   ├── pages/              # Dashboard, Catalog, IDE, Login, Register
  │   │   └── services/           # Axios Client API Abstractions
  │   ├── .env.example
  │   └── package.json
  │
  ├── server2/                    # Express Backend (Node.js ESM)
  │   ├── config/                 # Mongoose Connection Setup
  │   ├── controllers/            # Auth, Questions, Execution, Submissions, Admin
  │   ├── middleware/             # Auth Guards & Async Error Handlers
  │   ├── models/                 # Mongoose Schemas (User, Question, Submission)
  │   ├── routes/                 # Express API Endpoint Routes
  │   ├── scripts/                # Database Seeder (seed.js) & E2E Tests
  │   ├── services/               # Piston Code Execution Service
  │   ├── .env.example
  │   └── package.json
  │
  ├── .gitignore                  # Root Git Ignore Rules
  ├── CONTRIBUTING.md             # Contribution Guidelines & Commit Rules
  ├── CODE_OF_CONDUCT.md          # Contributor Covenant Code of Conduct
  ├── LICENSE                     # MIT Open Source License
  └── README.md                   # Repository Documentation

---

⚙️ Environment Configuration

Backend (server2/.env)

Create a .env file inside server2/:

PORT=5001
MONGODB_URI=mongodb+srv://<username>:<password>@cluster0.example.mongodb.net/codecraft?retryWrites=true&w=majority
JWT_SECRET=your_super_secret_jwt_key_here
JWT_EXPIRE=30d
PISTON_API_URL=https://emkc.org/api/v2/piston/execute

Frontend (frontend/.env)

Create a .env file inside frontend/:

VITE_API_URL=http://localhost:5001/api

---

🚀 Getting Started & Local Installation

Prerequisites

• Node.js: v18.0.0 or higher
• npm: v9.0.0 or higher
• MongoDB: Free MongoDB Atlas cluster or local MongoDB instance

1. Clone the Repository

git clone https://github.com/YOUR_GITHUB_USERNAME/CodeCraft.git
cd CodeCraft

2. Backend Server Setup

cd server2
npm install

# Seed 100+ Practice Questions into MongoDB Atlas (Idempotent)
npm run seed

# Launch Express Backend Server
npm run dev

(Server starts at http://localhost:5001)

3. Frontend Setup

In a new terminal window:

cd frontend
npm install

# Launch Vite Dev Server
npm run dev

(Frontend starts at http://localhost:3000)

---

📡 API Endpoints Overview

Method	Endpoint	Access	Description
GET	/api/health	Public	System status and MongoDB connection status
POST	/api/auth/register	Public	User registration & password hashing
POST	/api/auth/login	Public	Authenticate user & receive JWT token
GET	/api/auth/me	Protected	Fetch current user session profile
GET	/api/questions	Public	Catalog query with search, language & difficulty filter
GET	/api/questions/:id	Public	Fetch detailed question prompt & test cases
POST	/api/execute	Public	Run code in sandbox against test cases
POST	/api/submissions	Protected	Record code submission & update user metrics
GET	/api/user/progress	Protected	Accuracy %, solved counts, and difficulty breakdown
GET	/api/user/submissions	Protected	User submission logs and result history
GET	/api/admin/dashboard	Admin	Administrative platform statistics

---

🧪 Testing & Quality Assurance

Run Backend E2E Integration Tests

cd server2
npm run test

Verify Frontend Production Build

cd frontend
npx vite build

---

🤝 Contributing

Contributions are warmly welcomed! Please see our CONTRIBUTING.md guide for guidelines on commit messages, branching conventions, and pull request submissions.

Please adhere to our Code of Conduct in all community interactions.

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

_{Built with ❤️ by CodeCraft Contributors. Inspired by modern developer tools.}