ExamSphere - Full-Stack Online Examination & A

# Exam Platform — Documentation

A full exam platform: question bank, exam creation, timed exam-taking, auto + manual grading, classes, notifications, PDF/CSV export, and an admin overview. Bilingual UI (Arabic/English, RTL/LTR).

## What's in this package

``` exam-platform/ ├── api/      Node.js + Express + MongoDB backend ├── web/      React frontend (Vite) └── deploy/   Docker Compose setup for both + MongoDB, with backup/restore scripts ```

Each folder also has its own `README.md` with more detail specific to that part.

## Requirements

- Node.js 20+ and a MongoDB database (local or a free tier like MongoDB Atlas) — for running `api`/`web` directly. - **or** Docker + Docker Compose — to run everything with one command (recommended for a quick start). - A modern browser. No other paid services are required. Email notifications and PDF export are optional   features (see below) and work without any paid add-on.

## Quick start (Docker — easiest)

```bash cd deploy cp .env.example .env # open .env and set MONGO_ROOT_PASSWORD and JWT_SECRET to your own random values

docker compose up -d --build docker compose exec api npm run seed   # optional: demo accounts + a sample exam ``` Open **http://localhost**. Full details, backups, and going to production: `deploy/DEPLOY.md`.

## Quick start (manual, without Docker)

```bash # 1) Backend cd api npm install cp .env.example .env            # set MONGODB_URI and JWT_SECRET npm run seed                    # optional demo data npm run dev                     # http://localhost:4000

# 2) Frontend (in a second terminal) cd web npm install npm run dev                     # http://localhost:5173, proxies /api to the backend above ```

## Demo accounts (after `npm run seed`) | Role | Email | Password | |---|---|---| | Admin | admin@example.com | Password123! | | Teacher | teacher@example.com | Password123! | | Student | student@example.com | Password123! |

**Change or remove these before using the app with real data.**

## Features - **Accounts & roles** — admin / teacher / student, JWT auth, bcrypt-hashed passwords. - **Question bank** — multiple choice, true/false, short answer; subject, difficulty, points; optional image per question. - **Exams** — manual or random question selection, timed (enforced server-side), shuffled questions/options,   attempt limits, a start/end window, configurable pass mark. - **Taking an exam** — auto-save, resume after a disconnect, tab-switch logging, copy/paste blocked, auto-submit on timeout. - **Grading** — objective questions grade instantly; short answers are graded manually with comments;   students can request a regrade. - **Classes** — group students, limit an exam's audience to one or more classes, co-teachers per class. - **Notifications** — in-app bell (exam published, reminder before start, result ready, regrade updates)   plus optional email (set `SMTP_*` in `api/.env` — leave blank to use in-app only). - **Bulk student import** — Excel/CSV upload with per-row validation and generated passwords. - **Reports & export** — per-exam analytics (average, pass rate, hardest questions), CSV export,   per-student PDF export and a bulk "PDF per student, zipped" export, and an admin-only platform-wide overview. - **Bilingual UI** — Arabic and English, with automatic RTL/LTR layout switching.

## Support For questions about this item, use the contact/support channel listed on the Codester product page. Please include: what you were trying to do, the exact error message/screenshot, and whether you're running via Docker or manually.

## About the author *(Add your name, store link, and any other products here before publishing.)*

## Third-party notices See `LICENSE-THIRD-PARTY.md` for the open-source packages and web fonts this project depends on.

Features

Bilingual Support (Arabic & English): Full RTL (Right-to-Left) and LTR layout adaptation across all interfaces.Role-Based Access Control (RBAC): Distinct roles for Admin, Teacher, and Student with secure permission boundaries.Advanced Question Bank: Supports Multiple Choice (MCQ), True/False, and Short Answer questions with optional image attachments.Secure Examination Engine:

• Server-enforced timers (tamper-proof).
• Randomized question and option shuffling.
• Attempt limits and strict start/end time windows.
• Anti-Cheat Monitoring: Tracks and logs window/tab switching events with alerts sent to teachers.
• Auto-save and offline reconnection resilience.
• Automatic submission upon timer expiration.

Hybrid Grading System: Instant automated grading for objective questions, manual grading with feedback for essay questions, and student grade review requests.Class & Student Management: Group students into classes, assign targeted exams to specific classes, and manage co-teachers.Bulk Import via Excel/CSV: Easily import student lists with auto-generated passwords and direct class assignment.Comprehensive Reports & Analytics:

• Average scores, pass rates, and score distribution charts.
• Identification of most-missed/hardest questions.
• Export options: CSV exports and bulk zipped PDF reports for individual or class results.

Notifications: In-app notifications and email alerts for exam publishing, reminders, results release, and regrading updates.Security & Auditing: Secure password hashing (bcrypt), JWT authentication, comprehensive audit logs, and prevention of correct answer leaks during active exams.

Requirements

- Node.js (v18.0 or higher) - MongoDB (Local instance or MongoDB Atlas connection string) - Docker & Docker Compose (Optional, required only for containerized deployment) - Modern Web Browser (Chrome, Firefox, Edge, Safari) supporting modern CSS and JavaScript

Instructions

Frontend: React (Vite), Tailwind CSS, Lucide Icons, Recharts.Backend: Node.js, Express, MongoDB (Mongoose), JWT Auth, PDFKit.Deployment & DevOps: Docker & Docker Compose setup with automated backup configuration.