Py be jhd

[JahnviPaliwal]

This PR introduces a completely rewritten version of PyBe. Since this is a brand-new codebase rather than an incremental update, there isn't a meaningful file-by-file diff. Please review it by feature area instead of focusing on line-level changes.

Documentation Included

• product.md – Complete product and feature specification
• architecture.md – System architecture, data flow, and high-level diagram
• to_run.md – Prerequisites and setup instructions
• future_enhancements.md – Known limitations and planned improvements
• README.md – Updated installation and usage guide

What's New

• Completely rebuilt codebase from scratch
• Five storytelling themes:
  • Sports
  • Daily Life
  • Philosophy
  • Food
  • Environmental
• Three-part lesson structure for every concept:
  • Discovery scenarios
  • Concept introduction with visualizer
  • Fill-in-the-blank reinforcement
• 18 Python concepts arranged by increasing difficulty
• Core user features:
  • Registration/Login
  • Onboarding
  • Dashboard
  • Modules
  • Lessons
  • Practice Questions
  • Progress Tracking
• Admin dashboard with:
  • Question management
  • Analytics
  • Login logs
  • Feedback management
• Dedicated Practice Questions section

Database & Compatibility

• Uses a completely new database schema (no migration from the previous version).
• Introduces nine new Mongoose models:
  • User
  • Concept
  • Progress
  • Feedback
  • Challenge
  • Question
  • PracticeProblem
  • PracticeProgress
  • LoginLog
• A fresh database is required. Do not reuse the old database.
• Existing seed data is incompatible. Run the following seed scripts before first use:
  • seed:concepts
  • seed:challenges
  • seed:practice
  • seed:admin (optional, creates an admin account)
• Required environment variables:
  • MONGO_URI
  • JWT_SECRET
  • FRONTEND_URL
  • GROQ_API_KEY
  • GROQ_API_URL
  • GROQ_MODEL
  • PYTHON_BIN
  • EXEC_TIMEOUT_MS

See to_run.md for the complete configuration details.

External Requirements

• Groq API key (used for AI-generated lesson explanations)
• Python 3 installed on the server (used for Practice Questions code execution and grading)

Review Checklist

• Register, complete onboarding, and access the dashboard
• Test the full lesson flow:
  • Discovery scenarios
  • AI explanation
  • Decision scenario
  • Visualizer
  • Fill-in-the-blanks
• Switch themes during the course and verify that progress remains unchanged
• Test Practice Questions by submitting code and confirming grading and progress persistence
• Test the Admin dashboard:
  • Add a question
  • View analytics
  • View login logs
  • View feedback

Testing

All major user flows were tested multiple times to verify functionality, consistency, and edge-case handling before submission.

Contribution Breakdown

Development responsibilities for the rewrite were divided as follows:

• Divy
  • Scenario-Based Learning
  • Discovery scenarios
  • AI learning flow
  • Theme integration
  • Lesson navigation
• Harshita
  • Fill-in-the-Blanks
  • Syntax reinforcement
  • Feedback system
  • Progress flow
  • Authentication support
• Jahnvi
  • Python concepts
  • Practice Questions
  • Code execution
  • Visualization
  • PyTutor integration
  • Practice tracking
  • Theme frontend design

Known Gaps

Refer to future_enhancements.md for current limitations, including:

• Admin login improvements
• Frontend/dashboard UI enhancements
• Python Practice Questions editor improvements