feat: Implemented Recovery Missions and Weekly/Custom Contest for Students engagement!

[harshu167]

Summary & TL;DR

Why should this be implemented?

As students progress through the curriculum, they inevitably encounter "setbacks"—whether due to a drop in attendance, missing polls, or failing a quiz. Traditional dashboards merely report these metrics, which can lead to demotivation and dropout.

This PR implements two core engines to convert setbacks into engagement opportunities:

1. Setback Detection & Recovery Engine: Dynamically detects when a student falls behind (via SP drops, missed attendance, or failed quizzes) and recommends personalized, actionable Recovery Missions to help them catch up and earn back SP.
2. Weekly/Custom Contests: A fully gamified learning reinforcement loop consisting of a Word Scramble keyword game, a Time Attack Quiz (timed MCQs), and a Self-Reflection step. Contests can be created instantly by admins uploading a Zoom session transcript, which our backend translates into quizzes using an LLM (with a rule-based backup generator).

---

Key Features Implemented

1. Setback Detection & Dynamic Recovery Engine

• Automated Scans: The backend monitors student state and identifies three setback types:
  • SP Drop: Analyzes the student's recent transaction history to detect drops (default threshold $\le -15$ SP).
  • Missed Attendance: Flags when a student qualifies for $< 75%$ of recent sessions.
  • Contest Failure: Triggers when a student fails one or more recent contests.
• Smart Recommendation Engine: Scores and sorts available missions dynamically. A student experiencing a high-severity setback receives higher-ranked recovery missions tailored to their specific failure point.
• Structured Mission Lifecycle: Students accept missions, track daily checklists with evidence inputs, maintain consecutive-day streaks, and can abandon active missions if needed.

2. Gamified Contests (Reinforcement Loop)

• Word Scramble: Reinforces terminology discussed during lectures. Students must unscramble keywords from the session transcript to unlock the main quiz.
• Time Attack MCQ: Introduces a countdown-timer bar per question to add excitement and prevent session tampering.
• Reflection-Based Rewards: Students receive a bonus SP reward (+5 SP) for submitting a thoughtful reflection detailing their takeaways.

3. Secure AI & Admin Configuration Manager

• Transcript-to-Contest Pipeline: Admins upload raw Zoom transcripts, and the system automatically generates contests using LLMs (OpenAI/Anthropic).
• Robust Security: Encryption-at-rest (AES-256-GCM) secures LLM API keys. Additionally, cookie-derived student identifiers block header-spoofing attempts.
• Deterministic Fallback: In case of API failures or missing keys, the system falls back to a template-driven heuristic question generator to guarantee operational continuity.

---

Visual Walkthrough & UI States

Student Dashboards

Figure 1: Recovery Missions & Setback Alerts

Setback Banner & Recommendations: The "Missions" tab detects a recent setback (SP dropped by 38 points) and displays a customized warning banner alongside recommended recovery missions featuring difficulty badges, durations, and SP reward values.

Figure 2: Available Contests Dashboard

Contests Main Panel: Active contests list displaying the number of questions, passing threshold, remaining retry attempts, and rewards.

Figure 3: Word Scramble Lock

Educational Gatekeeper: Students must complete a Word Scramble matching key terms extracted from the lecture transcript before unlocking the quiz questions.

Figure 4: Time Attack Timed Quiz

Active Quiz Screen: A clean multiple-choice layout with a prominent progress bar displaying the remaining time (e.g., 20s time limit per question).

Figure 5: Reflective Reflection Step

Metacognitive Wrap-up: Encourages students to synthesize what they learned during the session, rewarding them with bonus SP upon text validation.

More: Walkthroughs

---

Codebase Modifications & Additions

Backend Abstractions & Models

• AIConfig.js: Global singleton document managing API credentials, token limits, and daily caps.
• Contest.js & ContestAttempt.js: Stores question structures, scrambled keywords, passing requirements, and logs attempt history.
• Mission.js & MissionAttempt.js: Tracks tasks, trigger rules, dates, active streaks, and current states (active, completed, failed).

Services & Routes

• crypto.js: Symmetric AES-256-GCM key derivation for encrypting external API keys at rest.
• aiProvider.js: Standardized LLM adapter handling text cleanup, prompt layouts, and daily usage guardrails.
• server.js: Integrates JWT/cookie authorization middleware to ensure tamper-proof sessions, and registers /api/contest, /api/missions, and /api/ai-config endpoints.

Client Dashboards (main.jsx / styles.css)

• Implemented new views: <StudentContestTab />, <StudentMissionsTab />, <ContestAdminPanel />, <MissionAdminPanel />, and <ContestAIConfig />.

---

🧪 Verification & Test Coverage

Two automated test suites were run and verified successfully to guarantee transaction ledger consistency, anti-tampering guards, and end-to-end flow completeness:

• tests/contest_balance.test.mjs: Ensures double-spend prevention and that transactions update the student's SP ledger atomically.
• tests/contest_smoke.test.mjs: Validates authentication priority (cookie vs. header), spoofing resistance, and submission rate-limiting.

Test Execution Output

$ node tests/contest_balance.test.mjs
OK Test 1: pass + reflection — running balance is consistent
OK Test 2: alreadyPassed / alreadyReceivedReflection guards block double-award
OK Test 3: failed score awards only reflection bonus
OK Test 4: rate limiter blocks 6th request, allows different email

All tests passed.