Skip to content

PROJECT_DOCUMENTATION.md

Latest commit

 

History

History
481 lines (369 loc) · 12.9 KB

PROJECT_DOCUMENTATION.md

File metadata and controls

481 lines (369 loc) · 12.9 KB
Raw

Adaptive AI-Based Learning Assessment Platform

Project Overview

Live Demo: https://sahayak-deployment-frontend.onrender.com/

Team: [Your Team Name]
Date: September 2025
Hackathon Project

Table of Contents

  1. Problem Statement
  2. Solution Overview
  3. System Architecture
  4. Key Features
  5. Technical Implementation
  6. User Journey
  7. Analytics & Reporting
  8. Impact & Benefits
  9. Future Roadmap
  10. Installation & Setup
  11. API Documentation
  12. Screenshots

Problem Statement

Background

Students in the same classroom often receive vastly different scores on identical tests, yet traditional assessment methods fail to identify the root causes of these performance gaps. Four critical learning fundamentals affect student outcomes:

  • Listening Skills (concentration during lessons)
  • Grasping Power (comprehension ability)
  • Retention Power (memory during home revision)
  • Practice Application (applying concepts in different situations)

Current evaluation systems overlook these individual differences, leading to superficial labeling of students as "good" or "poor" without actionable insights.

Real-World Example

Consider Ram, Shyam, and Sanga—three 8th-grade classmates learning "time and distance" in mathematics. After identical instruction and practice, their exam scores were 90, 65, and 35 respectively. While Ram is labeled "excellent" and Sanga "weak," we don't know where each student actually struggles or how to help them improve effectively.

Challenge

Design and develop an adaptive AI-based assessment and practice platform that moves beyond one-size-fits-all testing to provide personalized learning support for school students.

Solution Overview

Our platform implements an intelligent assessment system that:

  • Adaptive Assessment: Starts with easy questions and dynamically adjusts difficulty based on student responses
  • Learning Gap Identification: Analyzes performance across four learning fundamentals
  • Personalized Practice: Generates targeted content for individual weaknesses
  • Comprehensive Analytics: Provides detailed insights for students, teachers, and parents

Key Objectives

  • Identify specific learning gaps for each student
  • Generate personalized practice content targeting individual weaknesses
  • Allow flexible practice modes (student-selected difficulty or mixed questions)
  • Provide clear diagnostic reports showing areas for improvement
  • Demonstrate targeted support for students with unique challenges

System Architecture

Technology Stack

Frontend

  • Framework: React 18 with Next.js 14
  • Language: TypeScript
  • Styling: Tailwind CSS
  • State Management: Zustand
  • UI Components: Radix UI, Lucide Icons
  • Charts: Recharts

Backend

  • Runtime: Node.js
  • Framework: Express.js
  • Database: MongoDB with Mongoose ODM
  • Authentication: JWT (JSON Web Tokens)
  • Validation: Express Validator
  • File Upload: Multer

Deployment

Core Components

├── Frontend (React/Next.js)
│   ├── Student Interface
│   ├── Teacher Dashboard
│   ├── Analytics Components
│   └── Authentication
├── Backend (Node.js/Express)
│   ├── User Management
│   ├── Assessment Engine
│   ├── Analytics Service
│   └── Question Bank
└── Database (MongoDB)
    ├── Users Collection
    ├── Questions Collection
    ├── Screening Tests Collection
    └── Attempt Records Collection

Key Features

1. Adaptive Assessment System

  • Dynamic Difficulty Adjustment: Questions adapt based on student performance
  • Real-time Scoring: Immediate feedback and difficulty modification
  • Comprehensive Coverage: Tests across all learning fundamentals

2. Intelligent Question Bank

  • 180+ MCQ Questions: Categorized by subject, difficulty, and learning objectives
  • Manual Question Selection: Teachers can manually select questions for tests
  • Automated Question Generation: AI-powered question selection based on student needs

3. Personalized Learning Paths

  • Gap Analysis: Identifies specific areas of weakness
  • Targeted Practice: Generates exercises for identified gaps
  • Flexible Practice Modes: Student-controlled difficulty or mixed chapter questions

4. Advanced Analytics Dashboard

  • Student Performance: Individual progress tracking
  • Teacher Insights: Class-wide performance analytics
  • Parent Reports: Progress summaries and recommendations
  • Real-time Monitoring: Live assessment progress

5. Role-Based Access Control

  • Students: Take assessments, view progress, practice exercises
  • Teachers: Create tests, monitor students, access analytics
  • Parents: View child progress and recommendations

Technical Implementation

Adaptive Algorithm

// Difficulty adjustment logic
function adjustDifficulty(currentScore, questionDifficulty, isCorrect) {
  const scoreChange = isCorrect ? 10 : -15;
  const newScore = Math.max(0, Math.min(100, currentScore + scoreChange));

  // Adjust difficulty based on performance
  let newDifficulty;
  if (newScore >= 80) newDifficulty = 'hard';
  else if (newScore >= 50) newDifficulty = 'medium';
  else newDifficulty = 'easy';

  return { newScore, newDifficulty };
}

Database Schema

User Model

{
  name: String,
  email: String,
  password: String,
  role: ['student', 'teacher', 'parent'],
  profile: {
    grade: String,
    school: String,
    subjects: [String]
  }
}

Question Model

{
  question: String,
  options: {
    A: String,
    B: String,
    C: String,
    D: String
  },
  correctAnswer: String,
  category: String,
  difficulty: String,
  explanation: String
}

Screening Test Attempt

{
  student: ObjectId,
  screeningTest: ObjectId,
  answers: Map,
  questionAttempts: [{
    question: ObjectId,
    selectedAnswer: String,
    isCorrect: Boolean,
    timeSpent: Number
  }],
  analytics: {
    categoryPerformance: Object,
    difficultyPerformance: Object,
    speedMetrics: Object
  }
}

User Journey

Student Experience

  1. Registration & Login

    • Create account with role selection
    • Profile setup with grade and subjects

  2. Assessment Taking

    • Start screening test with adaptive difficulty
    • Real-time question adjustment based on responses
    • Time tracking and navigation controls

  3. Practice Sessions

    • Choose difficulty level or mixed practice
    • Targeted exercises for weak areas
    • Progress tracking and feedback

  4. Progress Monitoring

    • View detailed performance analytics
    • Track improvement over time
    • Access personalized recommendations

Teacher Experience

  1. Test Creation

    • Manual question selection from question bank
    • Set test parameters and time limits
    • Assign tests to students

  2. Student Monitoring

    • Real-time assessment progress
    • Individual student performance tracking
    • Class-wide analytics and insights

  3. Intervention Planning

    • Identify students needing support
    • Generate personalized improvement plans
    • Track intervention effectiveness

Analytics & Reporting

Performance Metrics

Category Performance

  • Quantitative Aptitude: Mathematical problem-solving
  • Logical Reasoning: Pattern recognition and analysis
  • Verbal Ability: Language comprehension and usage

Difficulty Analysis

  • Easy: Basic concept understanding
  • Medium: Application of concepts
  • Hard: Complex problem-solving

Speed Metrics

  • Average time per question
  • Time spent per category
  • Fastest/slowest question completion

Dashboard Features

Student Dashboard

  • Individual performance scores
  • Category-wise breakdown
  • Progress over time charts
  • Personalized recommendations

Teacher Dashboard

  • Class performance overview
  • Individual student details
  • Test analytics and insights
  • Exportable reports

Parent Dashboard

  • Child's progress summary
  • Areas needing attention
  • Teacher recommendations
  • Achievement milestones

Impact & Benefits

Educational Impact

  • Personalized Learning: Each student receives appropriate challenge level
  • Early Intervention: Identify and address learning gaps promptly
  • Improved Outcomes: Better academic performance through targeted support
  • Reduced Frustration: Adaptive difficulty prevents boredom and discouragement

Technical Benefits

  • Scalable Platform: Supports multiple schools and thousands of students
  • Real-time Analytics: Immediate insights for timely interventions
  • Data-Driven Decisions: Evidence-based teaching strategies
  • Cost-Effective: Reduces need for individual tutoring

Social Impact

  • Educational Equity: Bridge performance gaps in diverse classrooms
  • Inclusive Education: Support for students with different learning needs
  • Teacher Empowerment: Tools for effective classroom management
  • Parent Engagement: Active participation in child's education

Future Roadmap

Phase 1 (Completed)

  • ✅ Adaptive assessment system
  • ✅ Basic analytics dashboard
  • ✅ Question bank management
  • ✅ Role-based authentication

Phase 2 (Next 3 Months)

  • 🔄 Advanced AI recommendations
  • 🔄 Mobile application development
  • 🔄 Integration with learning management systems
  • 🔄 Multi-language support

Phase 3 (6 Months)

  • 📋 Predictive learning analytics
  • 📋 Gamification features
  • 📋 Offline assessment capabilities
  • 📋 Advanced reporting tools

Long-term Vision

  • 🤖 AI-powered curriculum adaptation
  • 🤖 Virtual reality learning experiences
  • 🤖 Global education platform
  • 🤖 Research partnerships for educational innovation

Installation & Setup

Prerequisites

  • Node.js 18+
  • MongoDB 5+
  • npm or yarn

Backend Setup

cd backend
npm install
cp .env.example .env
# Configure environment variables
npm run dev

Frontend Setup

cd frontend
npm install
cp .env.example .env
# Configure API endpoints
npm run dev

Environment Variables

# Backend
MONGODB_URI=mongodb://localhost:27017/sahayak
JWT_SECRET=your-secret-key
PORT=3001

# Frontend
NEXT_PUBLIC_API_URL=http://localhost:3001/api

API Documentation

Authentication Endpoints

POST /api/auth/login

Login user with email and password

{
  "email": "student@example.com",
  "password": "password123"
}

POST /api/auth/register

Register new user

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "password123",
  "role": "student"
}

Assessment Endpoints

GET /api/screening-tests

Get available screening tests

POST /api/screening-tests/attempt/:testId/start

Start a new test attempt

POST /api/screening-tests/attempt/:attemptId/answer

Submit answer for a question

POST /api/screening-tests/attempt/:attemptId/submit

Submit completed test

GET /api/screening-tests/attempt/:attemptId/analytics

Get attempt analytics

Teacher Endpoints

POST /api/screening-tests

Create new screening test

GET /api/screening-tests/:testId/analytics

Get test analytics

GET /api/questions

Get question bank

Screenshots

1. Student Dashboard

Student Dashboard

2. Adaptive Assessment Interface

Assessment Interface

3. Teacher Analytics Dashboard

Teacher Dashboard

4. Question Bank Management

Question Bank

5. Performance Analytics

Analytics

Contact Information

Project Repository: [GitHub Link]
Live Demo: https://sahayak-deployment-frontend.onrender.com/
Team Email: [team@example.com]
Documentation Version: 1.0
Last Updated: September 2025

Acknowledgments

This project was developed as part of [Hackathon Name] to address critical challenges in personalized education. We would like to thank our mentors, judges, and the hackathon organizers for providing this platform to innovate in education technology.

This documentation provides a comprehensive overview of the Adaptive AI-Based Learning Assessment Platform. For technical details, API specifications, or implementation guidance, please refer to the project repository or contact the development team.