🎯 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

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

🚪 Login Process

Visit the Login page at http://localhost:5173/
Demo Accounts Available:
- Admin: admin@university.edu / password123
- Mentor 1: mentor1@university.edu / password123
- Mentor 2: mentor2@university.edu / password123
JWT token stored securely in localStorage
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

Data Processing: Clean and normalize academic and behavioral data
Feature Engineering: Calculate weighted risk indicators
Academic Model: Scikit-learn Random Forest for academic risk
Behavioral Assessment: Rule-based thresholds for behavioral risk
Risk Combination: Matrix-based academic + behavioral risk integration
Continuous Scoring: Realistic percentage-based risk calculations
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

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

Database Migration
```
npx prisma migrate deploy
```

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:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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 🇮🇳

FilesExpand file tree

README.md

Latest commit

History