🎯 Insighted - AI-Powered Student Early Warning System

A comprehensive full-stack web application that leverages machine learning and behavioral analytics to predict student dropout risk with user-specific data isolation and provides educators with an intelligent dashboard to monitor and support at-risk students.

🚀 Smart India Hackathon 2025 Project

This project addresses the critical challenge of student retention in educational institutions using cutting-edge technology and data-driven insights with multi-tenant architecture for institutional deployment.

🏗️ Architecture Overview

🔒 Multi-Tenant Security Architecture

• User-Specific Data Isolation: Each user only sees students they have uploaded
• JWT Authentication: Secure role-based access control with token-based API protection
• Database-Level Filtering: All queries automatically filter by user ownership
• No Admin Privileges: Even admins only see their own uploaded student data

🧠 Hybrid ML Architecture

• Frontend: React 18 + Vite + TailwindCSS + Zustand state management
• Backend API: Node.js + Express.js + Prisma ORM with authentication middleware
• ML Pipeline: Enhanced Hybrid ML Service with FastAPI + Python + Scikit-learn
• Database: PostgreSQL with comprehensive student analytics and user relationships
• File Processing: Excel/CSV bulk upload with real-time processing and user tagging
• Service Management: Automated shell scripts for development and deployment

🎯 Core Features

• 🔐 Secure Multi-User System: Complete data isolation between users
• ⚡ Fast ML Predictions: HTTP-based microservice architecture
• 📊 Real-time Dashboard: Live risk score updates with behavioral assessments
• 🧪 Dual Risk Assessment: Academic + Behavioral risk analysis
• 📁 Bulk Processing: Efficient multi-file student data analysis with user attribution
• 🕸️ Graph View Integration: Interactive modal-based student risk visualization

✨ Key Features

🔒 Authentication & Security

• JWT Authentication: Secure token-based authentication system
• User Registration: Role-based user registration (Admin/Mentor)
• Protected Routes: All API endpoints require authentication
• Data Isolation: Users only access their uploaded student data
• Session Management: Persistent login with secure token storage

📊 Advanced Analytics Dashboard

• Interactive Modal Graph: Risk visualization without page navigation
• Dual Risk Display: Separate academic and behavioral risk analysis
• Risk Level Hierarchy: Graduated color-coded risk levels (Low/Medium/High/Very High)
• Continuous Risk Scores: Realistic percentage-based risk calculations
• Combined Risk Matrix: Integrated academic and behavioral risk assessment
• Smart Recommendations: Actionable intervention suggestions

🎓 Student Management System

• User-Specific Students: Each user manages only their uploaded students
• Detailed Profiles: Comprehensive student information with risk history
• Academic Tracking: GPA, marks, attendance, and performance metrics
• Financial Monitoring: Fee payment status and outstanding dues
• Behavioral Assessment: 5-factor behavioral risk evaluation system

📁 Enhanced Bulk Upload System

• 4-File Support: Attendance, Academics, Fees, and Student Profiles
• User Attribution: All uploads automatically tagged with uploader ID
• Real-time Processing: Live progress tracking with detailed results
• Data Validation: Smart validation with error reporting
• Template Download: Pre-formatted Excel templates for easy data entry

🧠 Behavioral Assessment Framework

• 5-Factor Analysis: Peer interaction, class participation, collaboration, help-seeking, teacher relationships
• Teacher-Driven Evaluation: Manual assessment by educators
• Risk Integration: Combines with academic risk for holistic view
• Historical Tracking: Timeline of behavioral assessments
• Intervention Recommendations: Targeted support suggestions

Project Structure

📁 Aegis/
├── 📁 backend/                       # Express.js API Server
│   ├── 📁 routes/                   # API endpoints
│   │   ├── 📄 bulkUploadRoutes.js   # Excel bulk upload endpoints
│   │   ├── 📄 dashboardRoutes.js    # Dashboard data endpoints
│   │   ├── 📄 enhancedBulkUploadRoutes.js  # Advanced bulk processing
│   │   ├── 📄 graphViewRoutes.js    # Network graph API
│   │   └── 📄 smartStudentRoutes.js # Enhanced student management
│   ├── 📁 services/                 # Business logic layer
│   │   ├── 📄 ExcelProcessingService.js     # Excel file handling
│   │   ├── 📄 HybridMLService.js           # ML integration service
│   │   ├── 📄 MLFeatureService.js          # Feature engineering
│   │   └── 📄 StudentProfileService.js     # Student data management
│   ├── 📁 src/                     # Core application logic
│   │   ├── 📁 routes/              # Additional API routes
│   │   │   └── 📄 behavioral.js    # Behavioral assessment API
│   │   ├── 📁 utils/               # Utility functions
│   │   │   └── 📄 behavioralRisk.js # Behavioral risk calculations
│   │   └── 📁 middleware/          # Authentication & validation
│   ├── 📁 prisma/                  # Database schema & migrations
│   │   └── 📄 schema.prisma        # Database schema definition
│   ├── 📁 models/                  # ML model storage
│   │   ├── 📄 hybrid_ml_model.pkl  # Trained hybrid model
│   │   └── 📄 student_risk_model.pkl # Primary risk model
│   ├── 📁 uploads/                 # File upload storage
│   ├── 📄 app.js                   # Express server entry point
│   ├── 📄 enhanced_hybrid_ml_service.py # Python ML service
│   └── [utility scripts]        # Database management utilities
├── 📁 frontend/                     # React Application
│   ├── 📁 src/
│   │   ├── 📁 components/          # Reusable UI components
│   │   │   └── 📄 BehavioralAssessment.jsx # Behavioral evaluation UI
│   │   ├── 📁 pages/               # Page components
│   │   │   ├── 📄 DashboardPage.jsx # Main dashboard with dual risk display
│   │   │   └── 📄 StudentDetailPage.jsx # Detailed student profiles
│   │   ├── 📁 utils/               # Helper functions
│   │   │   └── 📄 helpers.js       # Risk styling utilities
│   │   ├── 📁 services/            # API communication
│   │   ├── 📁 store/               # State management (Zustand)
│   │   └── [other directories]  # Standard React structure
│   ├── 📄 vite.config.js           # Vite configuration
│   └── 📄 tailwind.config.js       # TailwindCSS configuration
├── 📁 ml services/                 # Standalone ML Services
│   ├── 📄 enhanced_hybrid_ml_service.py # Enhanced ML service
│   ├── 📄 student_risk_ml_python.py     # Core ML implementation
│   ├── 📁 models/                  # Model storage
│   └── 📄 requirements.txt         # Python dependencies
├── 📁 sample_data/                 # Test data files
│   ├── 📄 attendance.xlsx          # Sample attendance data
│   ├── 📄 academics.xlsx           # Sample academic records
│   └── 📄 fees.xlsx                # Sample fee information
├── 📁 test_data/                   # Additional test datasets
├── 📁 student-early-warning/       # Additional ML research
├── � Service Management Scripts:
│   ├── 📄 start-services.sh        # Start all services
│   ├── 📄 stop-services.sh         # Stop all services
│   ├── 📄 setup.sh                 # Environment setup
│   └── 📄 check-status.sh          # Service health check
├── 📄 ml-service.py                # FastAPI ML microservice
├── 📄 ml_pipeline.py               # ML data processing pipeline
├── 📄 requirements.txt             # Python dependencies
└── 📄 README.md                    # This documentation

🚀 Quick Start Guide

📋 Prerequisites

• Node.js 18+ and npm
• PostgreSQL database
• Python 3.8+ with pip
• Git for version control

1. 📥 Clone Repository

git clone https://github.com/kayden-vs/iScheduler.git
cd "SIH TABLE MAKER"

2. 🗄️ Database Setup

-- Create PostgreSQL database
CREATE DATABASE student_risk_db;

3. ⚡ Automated Setup (Recommended)

# Windows users
setup-dev.bat

# Linux/macOS users
./setup.sh

4. 🔧 Manual Backend Setup

cd backend

# Install dependencies
npm install

# Configure environment variables
# Create .env file with:
DATABASE_URL="postgresql://postgres:700075Aa@localhost:5432/student_risk_db"
JWT_SECRET="your-super-secret-jwt-key-2024-sih"
ML_SERVICE_URL=http://127.0.0.1:8000
API_KEY_FOR_ML="ml-api-key-2024-secure"
PORT=5000

# Setup database with user-specific schema
npx prisma generate
npx prisma db push

# Start backend server
npm start
# ✅ Backend running on http://localhost:5000

5. 🧠 ML Service Setup

# Install Python dependencies
pip install -r requirements.txt

# Start ML microservice
python ml-service.py
# ML service running on http://localhost:8000

6. 🎨 Frontend Setup

cd frontend

# Install dependencies
npm install

# Start frontend development server
npm run dev
# ✅ Frontend running on http://localhost:5173

7. 🔄 Service Management

# Start all services at once
./start-services.sh

# Check service status
./check-status.sh

# Stop all services
./stop-services.sh

8. 🌐 Access Application

• Frontend: http://localhost:5173
• Backend API: http://localhost:5000
• ML Service: http://localhost:8000
• Database Admin: http://localhost:5555 (Prisma Studio)

👤 Authentication & User Management

🔐 Multi-User System Architecture

• Complete Data Isolation: Each user only sees students they have uploaded
• Role-Based Access: Admin and Mentor roles (both have equal data access)
• Secure Authentication: JWT tokens with 24-hour expiration
• Protected API Routes: All endpoints require authentication tokens

📝 User Registration Flow

1. Navigate to Register page
2. Fill in user details:
   • Email (unique identifier)
   • Password (minimum 6 characters)
   • Full Name
   • Role (Admin/Mentor)
3. System creates user account with empty student list
4. Auto-login after successful registration

🚪 Login Process

1. Visit the Login page at http://localhost:5173/
2. Demo Accounts Available:
   • Admin: admin@university.edu / password123
   • Mentor 1: mentor1@university.edu / password123
   • Mentor 2: mentor2@university.edu / password123
3. JWT token stored securely in localStorage
4. Automatic redirect to dashboard upon successful login

📊 Complete User Workflow

1. 🔑 Initial Access

• Login/Register with secure credentials
• Dashboard loads showing only your uploaded students (initially empty)
• Navigation menu provides access to all features

2. 📁 Data Upload Process

• Navigate to Enhanced Bulk Upload section
• Download template for student profiles (if needed)
• Select Excel files for:
  • Attendance data (attendance.xlsx) - student attendance percentages
  • Academic records (academics.xlsx) - marks, GPA, academic performance
  • Fee information (fees.xlsx) - payment status, dues, financial data
  • Student profiles (profiles.xlsx) - demographic and profile information
• Click "Upload & Analyze" for ML processing
• Real-time progress tracking with detailed results
• All uploaded students automatically tagged with your user ID

3. 📊 Dashboard Analytics

• Risk Statistics: Overview of your students' risk distribution
• Interactive Graph View: Modal-based risk visualization (no page navigation)
• Dual Risk Display: Academic vs. Behavioral risk analysis
• Student List: Sortable and filterable table of your students only
• Quick Actions: Direct access to student details and assessments

4. 🎓 Student Management

• Detailed Profiles: Click any student for comprehensive information
• Risk History: Timeline of risk assessments and changes
• Academic Tracking: GPA, marks, attendance trends
• Financial Status: Fee payments, outstanding dues
• Contact Information: Student and guardian details

5. 🧠 Behavioral Assessment

• Teacher-Driven Evaluation: Manual assessment by educators
• 5-Factor Analysis:
  • Peer Group Interaction (1-10 scale)
  • Class Participation (1-10 scale)
  • Collaborative Learning (1-10 scale)
  • Help Seeking Nature (1-10 scale)
  • Teacher-Student Relationship (1-10 scale)
• Behavioral Notes: Additional observations and comments
• Combined Risk Calculation: Integrates with academic risk
• Historical Tracking: Timeline of behavioral assessments
• Continuous Risk Indicators: Realistic percentage-based risk scores
• Risk Level Hierarchy: Low/Medium/High/Very High with distinct colors

4. Behavioral Assessment

• Access individual student profiles
• Complete 5-factor behavioral evaluation:
  • Peer Group Interaction
  • Class Participation
  • Collaborative Learning
  • Help-Seeking Nature
  • Teacher-Student Relationship
• View combined academic + behavioral risk analysis

5. Student Details

• Click on any student for detailed profile
• View risk history and trends
• Academic performance charts
• Behavioral assessment status
• Intervention recommendations

6. Graph View Integration

• Network visualization of student relationships
• Interactive risk correlation analysis
• Peer influence mapping

Hybrid ML Risk Assessment Model

Academic Risk Features

• Academic Performance: GPA, marks percentage, credit units
• Financial Status: Outstanding fees, payment history patterns
• Attendance: Class participation rates and trends
• Demographics: Course, year, semester information
• Historical Patterns: Performance trends over time

Behavioral Risk Features

• Peer Group Interaction (15% weight): Social integration and peer relationships
• Class Participation (25% weight): Active engagement in classroom activities
• Collaborative Learning (15% weight): Team work and group project participation
• Help-Seeking Nature (20% weight): Willingness to seek academic support
• Teacher-Student Relationship (25% weight): Quality of mentorship connections

Risk Categories

• Low Risk: 0-29% (Good standing, minimal intervention needed)
• Medium Risk: 30-59% (Needs attention and monitoring)
• High Risk: 60-79% (Requires intervention and support)
• Very High Risk: 80-100% (Immediate intervention critical)

Hybrid ML Pipeline

1. Data Processing: Clean and normalize academic and behavioral data
2. Feature Engineering: Calculate weighted risk indicators
3. Academic Model: Scikit-learn Random Forest for academic risk
4. Behavioral Assessment: Rule-based thresholds for behavioral risk
5. Risk Combination: Matrix-based academic + behavioral risk integration
6. Continuous Scoring: Realistic percentage-based risk calculations
7. Intervention Triggers: Auto-notify mentors for high-risk students

Combined Risk Matrix

Academic → Behavioral	Low	Medium	High
Low	Low (20%)	Low (30%)	Medium (60%)
Medium	Medium (40%)	Medium (50%)	High (80%)
High	Medium (60%)	High (80%)	High (90%)

Development

Adding New Features

# Backend API endpoints
cd backend/routes/
# Create new route file (e.g., newFeatureRoutes.js)

# Backend services
cd backend/services/
# Create new service (e.g., NewFeatureService.js)

# Frontend components  
cd frontend/src/components/
# Create new React component

# ML model updates
cd "ml services"/
# Update enhanced_hybrid_ml_service.py

Database Operations

# Clear database
cd backend && node clear-database.js

# Reset with sample data
node clear-db-simple.js

# Check behavioral assessments
node check-behavioral.js

# Check database status
node check-db.js

Service Management

# Check all service status
./check-status.sh

# Restart all services
./stop-services.sh && ./start-services.sh

# View service logs
# (Check individual terminal windows)

Testing ML Service

# Test ML service health
curl http://localhost:8000/health

# Test prediction endpoint
curl -X POST http://localhost:8000/predict \
  -H "Content-Type: application/json" \
  -d '{"students": [{"studentId": "TEST", "attendance": 85, "gpa": 3.2, ...}]}'

# Test enhanced hybrid service
python backend/enhanced_hybrid_ml_service.py

API Documentation

Authentication Endpoints

• POST /api/auth/login - User login
• POST /api/auth/register - User registration

Student Management

• GET /api/students - Get all students (role-filtered)
• GET /api/students/:id - Get student details with risk history
• GET /api/dashboard - Dashboard data with risk statistics

Behavioral Assessment

• GET /api/behavioral/student/:studentId - Get behavioral assessment
• PUT /api/behavioral/student/:studentId - Update behavioral assessment
• GET /api/behavioral/overview - Behavioral assessment overview

Bulk Upload & Processing

• POST /api/bulk-upload - Standard bulk upload
• POST /api/enhanced-bulk-upload - Enhanced bulk processing with validation
• GET /api/bulk-upload/status - Upload status check

ML Integration

• POST /api/ml/update-risk-score - Manual risk score update
• GET /api/ml/model-info - ML model information

Graph View

• GET /api/graph-view/students - Student network data
• GET /api/graph-view/relationships - Relationship mappings

ML Microservice

• GET /health - Service health check
• POST /predict - Batch risk prediction
• POST /predict-single - Single student prediction
• GET /model-info - Model metadata

SIH 2025 Hackathon Highlights

Innovation Points

• Real-time ML Predictions: FastAPI microservice architecture
• Dual Risk Assessment: Academic + Behavioral risk integration
• Bulk Data Processing: Multi-file Excel upload with instant analysis
• Responsive Design: Modern UI/UX with TailwindCSS
• Scalable Architecture: Microservice-based design with service management
• Educational Impact: Direct benefit to student retention

Technical Excellence

• Clean Code: Well-structured, documented codebase
• Performance: Optimized database queries and ML processing
• Security: JWT authentication and input validation
• Responsive: Mobile-friendly interface
• Tested: Comprehensive error handling and continuous risk calculations

Social Impact

• Student Success: Early intervention for at-risk students with behavioral insights
• Educator Support: Data-driven decision making with teacher assessments
• Institutional Benefits: Improved retention rates through hybrid analytics
• Evidence-based: Combined academic and behavioral student support

Demo Accounts

For testing purposes, you can use these accounts:

Admin Account:
Email: admin@university.edu
Password: password123

Mentor Account:
Email: mentor@university.edu  
Password: password123

Deployment

Production Deployment

1. Environment Setup

   # Set production environment variables
   NODE_ENV=production
   DATABASE_URL=your_production_db_url
   JWT_SECRET=your_production_jwt_secret
   ML_SERVICE_URL=your_ml_service_url

2. Database Migration

   npx prisma migrate deploy

3. Build & Deploy

   # Backend
   npm start
   
   # Frontend
   npm run build
   # Deploy dist/ folder to CDN/hosting
   
   # ML Service
   python ml-service.py

Docker Deployment (Optional)

# Build containers (if docker-compose.yml exists)
docker-compose up --build

# Run in production
docker-compose -f docker-compose.prod.yml up -d

Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

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

Team Information

Project: Insighted - Student Early Warning System
Event: Smart India Hackathon 2025
Category: Software Development
Team: onlyStack Repository: GitHub Repository

---

Support

For questions or support, please:

• Email: rkr.iot.tmsl@ticollege.org
• Issues: GitHub Issues
• Documentation: This README and inline code comments

---

Built with ❤️ for Smart India Hackathon 2025 🇮🇳