AI-Powered Timetable Generation System

A complete, production-ready AI-powered timetable generation system for educational institutions, designed for Smart India Hackathon 2025 with NEP 2020 compliance.

Features

Core Capabilities

AI Timetable Generation: Advanced genetic algorithm for optimized scheduling
Conflict Resolution: Automatic detection and resolution of scheduling conflicts
NEP 2020 Compliance: Built-in validation and scoring for Indian education policy
Interactive Dashboard: Real-time statistics, analytics, and system monitoring
Data Management: Comprehensive CRUD operations for courses, faculty, and classrooms
RESTful API: Complete API-first design with comprehensive endpoints
Custom Dataset Support: JSON input for flexible data management

Technical Features

Real-time Processing: Live progress tracking and updates during generation
Professional UI: React with TypeScript and Material-UI components
Responsive Design: Mobile-friendly interface with dark mode support
Export Capabilities: CSV export functionality for generated timetables
Advanced Filtering: Multi-dimensional filtering and search capabilities
Performance Optimized: Efficient algorithms with configurable parameters

Architecture

Technology Stack

Backend: FastAPI 0.115+ with Python 3.8+
Frontend: React 19+ with TypeScript 4.9+
UI Framework: Material-UI 7.3+ with responsive design
Charts & Analytics: Recharts 3.1+ for data visualization
HTTP Client: Axios 1.11+ for API communication
AI Engine: Custom genetic algorithm implementation

System Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   React Frontend │    │  FastAPI Backend │    │  AI Algorithm   │
│   (Port 3000)    │────│   (Port 8000)    │────│   Engine        │
│                 │    │                 │    │                 │
│ • Dashboard      │    │ • RESTful API   │    │ • Genetic Algo  │
│ • Timetable Grid │    │ • CORS Enabled  │    │ • Optimization  │
│ • Data Tables    │    │ • Async/Await   │    │ • NEP Scoring   │
│ • Form Controls  │    │ • WebSocket     │    │ • Constraints   │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Project Structure

ai-timetable/
├── README.md                   # This file - project overview and setup
├── main.py                     # FastAPI backend server
├── requirements.txt            # Python dependencies
├── package.json               # Node.js project configuration
├── start.bat                  # Windows startup script
├── API_DOCUMENTATION.md       # Complete API reference
├── PROJECT_SUMMARY.md         # Project status and overview
├── DEPLOYMENT_GUIDE.md        # Deployment instructions
├── TESTING_CHECKLIST.md       # Testing requirements and status
├── IMPORTANT_TASKS.md         # Development priorities and tasks
├── frontend/                  # React TypeScript application
│   ├── src/
│   │   ├── components/        # React components
│   │   │   ├── Dashboard.tsx      # System dashboard with analytics
│   │   │   ├── GenerateForm.tsx   # AI generation interface
│   │   │   ├── TimetableGrid.tsx  # Interactive schedule display
│   │   │   ├── DataTables.tsx     # Data management interface
│   │   │   ├── JsonInput.tsx      # Custom dataset input
│   │   │   └── DarkModeToggle.tsx # Theme switcher
│   │   ├── services/
│   │   │   └── api.ts         # API service layer
│   │   ├── types/
│   │   │   └── index.ts       # TypeScript type definitions
│   │   ├── contexts/
│   │   │   └── ThemeContext.tsx   # Theme management
│   │   ├── themes/
│   │   │   └── themes.ts      # Material-UI theme configuration
│   │   ├── App.tsx            # Main application component
│   │   ├── App.css            # Custom styles
│   │   └── index.tsx          # Application entry point
│   ├── public/                # Static assets
│   ├── package.json           # Frontend dependencies
│   └── tsconfig.json          # TypeScript configuration
└── .github/                   # GitHub configuration
    └── copilot-instructions.md

Quick Start

Prerequisites

Python 3.8+ - Backend server runtime
Node.js 16+ - Frontend development server
Git - Version control (recommended)
Modern Web Browser - Chrome, Firefox, Safari, or Edge

Automated Setup (Recommended)

The fastest way to start the system is using the automated startup script:

# Navigate to project directory
cd "C:\Users\arjun\Documents\ai-timetable"

# Run automated startup (Windows)
.\start.bat

This script will:

Start the FastAPI backend server on port 8000
Start the React development server on port 3000
Open the application in your default browser

Manual Setup

If you prefer manual control or are using a different operating system:

Backend Server Setup

# Navigate to project root
cd "C:\Users\arjun\Documents\ai-timetable"

# Install Python dependencies
pip install -r requirements.txt

# Start the FastAPI server
python main.py

The backend server will be available at http://localhost:8000 API documentation will be available at http://localhost:8000/docs

Frontend Application Setup

# Navigate to frontend directory
cd frontend

# Install Node.js dependencies (first time only)
npm install

# Start the React development server
npm start

The frontend application will open automatically at http://localhost:3000

Verification

After startup, verify that both services are running:

Backend Health Check: Visit http://localhost:8000/health
Frontend Application: Visit http://localhost:3000
API Documentation: Visit http://localhost:8000/docs

The application should load without errors and display the dashboard with system statistics.

Usage Guide

Application Interface

The system provides five main interfaces accessible through tabs:

1. Dashboard

System Overview: View total courses, faculty, classrooms, and schedule entries
Resource Utilization: Monitor classroom and faculty utilization rates
NEP 2020 Compliance: Track compliance scores across all metrics
System Health: Real-time status indicators and conflict monitoring
Analytics Charts: Visual representation of system performance

2. Generate Timetable

Department Selection: Choose which departments to include in generation
Algorithm Configuration: Adjust generation parameters (generations, population size)
Real-time Progress: Watch the genetic algorithm optimize in real-time
Results Analysis: View fitness scores, conflicts resolved, and generation time
Performance Metrics: Detailed breakdown of optimization results

3. View Schedule

Interactive Grid: Weekly timetable view with color-coded sessions
Advanced Filtering: Filter by course, faculty, or classroom
Session Details: Click any session for detailed information
Export Functionality: Download timetable as CSV file
Responsive Layout: Optimized for both desktop and mobile viewing

4. Data Management

Course Information: Browse all courses with credits, hours, and departments
Faculty Details: View faculty specializations, preferences, and workload
Classroom Resources: Check room capacity, type, and available equipment
Expandable Tables: Detailed information accessible through row expansion

5. JSON Input

Custom Datasets: Upload your own course, faculty, and classroom data
Flexible Import: Support for custom data structures and constraints
Validation: Built-in data validation before processing
Instant Generation: Generate timetables with custom data

Typical Workflow

System Check: Start with the Dashboard to verify system status
Data Review: Check existing data in Data Management tab
Configuration: Set up generation parameters in Generate Timetable
Generation: Run the AI algorithm and monitor progress
Review: Examine results in View Schedule with filtering options
Export: Download final timetable for distribution

How to Use

Step-by-Step Generation Process

1. Dashboard Overview

Monitor system statistics and health indicators
Review NEP 2020 compliance scores and recommendations
Check resource utilization rates and system performance
Verify that all components are operational

2. Generate Timetable

Select Departments: Choose from available departments (CSE, MATH, PHYSICS, ECE)
Configure Parameters:
- Maximum Generations: 50-500 (default: 150)
- Population Size: Automatically optimized at 50
- Algorithm Settings: Pre-configured for optimal performance
Start Generation: Click "Generate Timetable" to begin optimization
Monitor Progress: Watch real-time fitness improvement and conflict resolution
Review Results: Analyze generation time, final fitness score, and optimization success

3. View and Analyze Schedule

Interactive Timetable: Navigate the weekly grid with color-coded sessions
Filter Options: Focus on specific courses, faculty, or classrooms
Session Information: Click any slot for detailed session information
Quality Check: Verify no conflicts and optimal resource utilization
Export Data: Download complete timetable in CSV format

4. Data Management and Validation

Course Review: Examine course details, credits, and hour requirements
Faculty Analysis: Check faculty workloads, specializations, and preferences
Resource Verification: Confirm classroom capacity and equipment availability
Relationship Mapping: Understand connections between courses, faculty, and rooms

AI Algorithm

Genetic Algorithm Implementation

The system employs a sophisticated genetic algorithm specifically designed for educational timetabling optimization.

Algorithm Configuration

Population Size: 50 candidate timetables
Maximum Generations: 150 (configurable: 50-500)
Selection Method: Tournament selection with size 3
Crossover Rate: 80% with single-point crossover
Mutation Rate: 10% with random modifications
Elitism: Preserves top 10% of solutions each generation

Optimization Process

Initialization: Generate random valid timetable population
Evaluation: Calculate fitness scores using multi-objective function
Selection: Tournament selection for parent candidates
Reproduction: Crossover and mutation to create offspring
Replacement: Elitist replacement with best solutions preserved
Convergence: Early stopping when optimal solution found (fitness > 95)

Fitness Function Design

The fitness function balances multiple objectives with weighted importance:

Hard Constraints (Must Satisfy)

Faculty Availability: No double-booking of instructors (penalty: -50 per conflict)
Classroom Conflicts: No room scheduling conflicts (penalty: -50 per conflict)
Course Requirements: All required hours scheduled (penalty: -10 per missing hour)
Resource Capacity: Classroom capacity matches course enrollment

Soft Constraints (Optimization Goals)

Faculty Preferences: Preferred days and time slots (bonus: +5 per match)
Time Distribution: Balanced course scheduling throughout the week
Resource Utilization: Efficient use of classrooms and equipment
Academic Scheduling: Appropriate sequencing of course types

Performance Metrics

Typical Generation Time: 30-60 seconds for standard datasets
Conflict Resolution Rate: 95%+ success in eliminating hard conflicts
Fitness Achievement: 85-95 average final fitness scores
Convergence Efficiency: Early stopping reduces unnecessary computation

Algorithmic Innovations

Constraint-Aware Mutation: Mutations respect scheduling constraints
Adaptive Parameters: Dynamic adjustment based on problem complexity
Memory Efficiency: Optimized data structures for large-scale problems
Real-time Monitoring: Live progress tracking and performance analytics

NEP 2020 Compliance

The system implements comprehensive compliance checking aligned with the National Education Policy 2020 framework.

Compliance Framework

1. Multidisciplinary Learning (25% weight)

Cross-Department Integration: Tracks courses from different departments
Interdisciplinary Opportunities: Promotes diverse academic exposure
Department Variety Score: Measures breadth of academic offerings
Target: Achieve representation from multiple disciplines

2. Skill Development Focus (25% weight)

Practical Session Monitoring: Tracks laboratory and tutorial sessions
Hands-on Learning: Ensures adequate practical learning opportunities
Session Type Distribution: Balances theoretical and practical content
Target: Minimum 30% practical sessions in curriculum

3. Research Integration (25% weight)

Advanced Course Allocation: Prioritizes higher-semester research courses
Academic Progression: Supports research-oriented learning paths
Semester-based Analysis: Tracks progression toward research activities
Target: Adequate allocation for advanced academic pursuits

4. Student Choice and Flexibility (25% weight)

Course Variety: Measures diversity in available course options
Scheduling Flexibility: Provides multiple time slot options
Academic Freedom: Supports student choice in learning paths
Target: Maximum variety in course offerings and scheduling

Compliance Scoring

Scoring Methodology

Real-time Calculation: Updated during timetable generation
Weighted Average: Equal weight to all four compliance areas
Performance Bands:
- 80-100%: Excellent compliance
- 60-79%: Good compliance
- 40-59%: Needs improvement
- Below 40%: Poor compliance

Compliance Analytics

Dashboard Integration: Live compliance scores on main dashboard
Detailed Breakdown: Component-wise analysis and recommendations
Historical Tracking: Monitor compliance trends over time
Improvement Suggestions: Automated recommendations for enhancement

Implementation Benefits

Policy Alignment: Ensures institutional adherence to national standards
Quality Assurance: Maintains educational quality through structured compliance
Continuous Improvement: Provides metrics for ongoing enhancement
Transparency: Clear visibility into compliance performance

API Reference

The system provides a comprehensive RESTful API for all functionality. For complete API documentation, see API_DOCUMENTATION.md.

Core Endpoints

System Information

GET / - System information and version
GET /health - Health check and system status
GET /docs - Interactive API documentation (Swagger UI)

Data Management

GET /api/v1/courses - List all courses with details
GET /api/v1/faculty - List all faculty members with specializations
GET /api/v1/classrooms - List all classrooms with equipment

Timetable Operations

POST /api/v1/timetable/generate - Generate new optimized timetable
POST /api/v1/timetable/generate/custom - Generate with custom JSON datasets
GET /api/v1/timetable/current - Retrieve current generated timetable

Analytics and Compliance

GET /api/v1/dashboard/stats - System statistics and performance metrics
GET /api/v1/nep-compliance/check - NEP 2020 compliance analysis

API Features

CORS Enabled: Configured for frontend integration
Async Processing: Non-blocking operations for optimal performance
Error Handling: Comprehensive error responses with helpful messages
Validation: Input validation using Pydantic models
Documentation: Auto-generated Swagger documentation

Example Usage

# Health check
curl http://localhost:8000/health

# Generate timetable
curl -X POST "http://localhost:8000/api/v1/timetable/generate" \
  -H "Content-Type: application/json" \
  -d '{"departments": ["CSE"], "constraints": {"max_generations": 100}}'

# Get dashboard statistics
curl http://localhost:8000/api/v1/dashboard/stats

For detailed examples and response formats, refer to the complete API documentation.

UI/UX Features

Modern Design

Material-UI components
Responsive flexbox layout system
Professional color scheme
Smooth animations and transitions

Interactive Elements

Real-time progress indicators
Expandable data tables
Filterable timetable grid
Click-to-view session details

Accessibility

Keyboard navigation support
Screen reader compatibility
High contrast mode support
Mobile-responsive design

Performance Metrics

Optimization Results

Generation Time: 30-60 seconds typical
Conflict Resolution: 95%+ success rate
NEP Compliance: 80%+ average score
Resource Utilization: 70-90% efficiency

System Requirements

Backend: 512MB RAM, 1 CPU core
Frontend: Modern web browser
Network: Local network sufficient

Development

Development Environment Setup

Prerequisites

Python 3.8+ with pip package manager
Node.js 16+ with npm package manager
Git for version control
Code Editor (Visual Studio Code recommended)

Backend Development

# Install dependencies
pip install -r requirements.txt

# Install development dependencies (optional)
pip install pytest pytest-asyncio pytest-cov

# Start development server with auto-reload
python main.py

# API documentation available at http://localhost:8000/docs

Frontend Development

# Navigate to frontend directory
cd frontend

# Install dependencies
npm install

# Start development server with hot reload
npm start

# Application available at http://localhost:3000

Code Quality Standards

Backend (Python)

PEP 8: Python style guide compliance
Type Hints: Full type annotation coverage
Async/Await: Proper asynchronous programming patterns
Error Handling: Comprehensive exception management
Documentation: Docstrings for all functions and classes

Frontend (TypeScript)

TypeScript Strict Mode: Enabled for type safety
React Best Practices: Functional components with hooks
Material-UI Guidelines: Consistent design system usage
Performance Optimization: Memoization and lazy loading
Accessibility: WCAG compliance for inclusive design

Architecture Patterns

Backend Architecture

FastAPI Framework: Modern Python web framework
Pydantic Models: Data validation and serialization
Dependency Injection: Modular and testable code structure
Async Operations: Non-blocking I/O for performance
RESTful Design: Standard HTTP methods and status codes

Frontend Architecture

Component-Based Design: Reusable and maintainable components
Context API: State management for theme and application data
Service Layer: Centralized API communication
Type Safety: Full TypeScript coverage
Responsive Design: Mobile-first approach with flexbox

Development Workflow

Feature Development: Create feature branches from main
Code Quality: Follow established coding standards
Testing: Write tests for new functionality
Documentation: Update relevant documentation
Review: Code review before merging
Integration: Continuous integration and deployment

For detailed development guidelines, see the project's coding standards documentation.

Troubleshooting

Common Issues and Solutions

Port Conflicts

Problem: "Port 8000 already in use" error

# Find process using port 8000
netstat -ano | findstr :8000

# Kill the process (replace PID with actual number)
taskkill /PID <PID_NUMBER> /F

# Alternative: Use different port
python main.py --port 8001

Frontend Console Errors

Problem: JavaScript errors in browser console

Check browser developer console for specific error messages
Ensure backend server is running on port 8000
Verify CORS configuration in main.py
Clear browser cache and hard reload (Ctrl+F5)

Installation Issues

Problem: npm or pip installation failures

# Clear npm cache
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

# Python virtual environment (recommended)
python -m venv venv
venv\Scripts\activate  # Windows
pip install -r requirements.txt

API Connection Issues

Problem: Frontend cannot connect to backend

Verify backend server is running: http://localhost:8000/health
Check API base URL in frontend/src/services/api.ts
Ensure no proxy or firewall blocking local connections
Verify CORS settings allow http://localhost:3000

Health Checks

Backend health: http://localhost:8000/health
Frontend status: Check browser console
API documentation: http://localhost:8000/docs

Deployment

For comprehensive deployment instructions including production setup, Docker configuration, and cloud deployment options, see DEPLOYMENT_GUIDE.md.

Quick Deployment Summary

Local Development

Backend: python main.py (Port 8000)
Frontend: cd frontend && npm start (Port 3000)
Automated: .\start.bat (Windows)

Production Considerations

Environment Variables: Configure for production settings
HTTPS: Enable SSL/TLS for security
Database: Implement persistent storage
Monitoring: Add logging and health checks
Scaling: Consider load balancing for high traffic

Docker Deployment

# Build backend container
docker build -t ai-timetable-backend .

# Run with Docker Compose
docker-compose up -d

Testing

For complete testing requirements and procedures, see TESTING_CHECKLIST.md.

Testing Framework

Backend: pytest with asyncio support
Frontend: Jest and React Testing Library
Integration: End-to-end testing with real API calls
Performance: Load testing and optimization verification

Current Testing Status

Backend: Testing framework setup required
Frontend: Basic React testing structure in place
API: Manual testing through Swagger documentation
Integration: Manual workflow testing

Running Tests

# Frontend tests
cd frontend && npm test

# Backend tests (when implemented)
pytest

# Coverage reports
npm run test:coverage
pytest --cov

Contributing

This is an MVP for Smart India Hackathon 2025. For improvements:

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

License

This project is created for Smart India Hackathon 2025. Please refer to the hackathon guidelines for usage terms.

Smart India Hackathon 2025

Problem Statement

AI-powered timetable generation with NEP 2020 compliance for educational institutions.

Key Innovation Points

AI-First Approach: Genetic algorithm optimization
NEP 2020 Integration: Built-in compliance checking
Real-time Feedback: Live generation progress
User-Friendly Interface: Intuitive dashboard and controls
Scalable Architecture: API-first design for extensibility

Demo Highlights

Live AI Generation: Watch the algorithm work in real-time
Conflict Resolution: See how conflicts are automatically resolved
NEP Compliance: View detailed compliance metrics
Interactive Visualization: Explore the generated timetable
Professional UI: Modern, responsive design

Support

For questions or issues during the hackathon:

Check the API health endpoint: http://localhost:8000/health
Review browser console for frontend errors
Ensure both servers are running on correct ports
Verify CORS configuration for API calls

Built for Smart India Hackathon 2025

Name		Name	Last commit message	Last commit date
.github		.github
frontend		frontend
.gitignore		.gitignore
API_DOCUMENTATION.md		API_DOCUMENTATION.md
CUSTOM_GENERATION_API.md		CUSTOM_GENERATION_API.md
DEPLOYMENT_GUIDE.md		DEPLOYMENT_GUIDE.md
PPT Submission - Fork_It_We_Ball - Team Number 50.pptx		PPT Submission - Fork_It_We_Ball - Team Number 50.pptx
PROJECT_SUMMARY.md		PROJECT_SUMMARY.md
README.md		README.md
main.py		main.py
package-lock.json		package-lock.json
package.json		package.json
presentation_script.md		presentation_script.md
requirements.txt		requirements.txt
sample.json		sample.json
start.bat		start.bat

Latest commit

History

Folders and files

Repository files navigation

AI-Powered Timetable Generation System

Table of Contents

Features

Core Capabilities

Technical Features

Architecture

Technology Stack

System Architecture

Project Structure

Quick Start

Prerequisites

Automated Setup (Recommended)

Manual Setup

Backend Server Setup

Frontend Application Setup

Verification

Usage Guide

Application Interface

1. Dashboard

2. Generate Timetable

3. View Schedule

4. Data Management

5. JSON Input

Typical Workflow

How to Use

Step-by-Step Generation Process

1. Dashboard Overview

2. Generate Timetable

3. View and Analyze Schedule

4. Data Management and Validation

AI Algorithm

Genetic Algorithm Implementation

Algorithm Configuration

Optimization Process

Fitness Function Design

Hard Constraints (Must Satisfy)

Soft Constraints (Optimization Goals)

Performance Metrics

Algorithmic Innovations

NEP 2020 Compliance

Compliance Framework

1. Multidisciplinary Learning (25% weight)

2. Skill Development Focus (25% weight)

3. Research Integration (25% weight)

4. Student Choice and Flexibility (25% weight)

Compliance Scoring

Scoring Methodology

Compliance Analytics

Implementation Benefits

API Reference

Core Endpoints

System Information

Data Management

Timetable Operations

Analytics and Compliance

API Features

Example Usage

UI/UX Features

Modern Design

Interactive Elements

Accessibility

Performance Metrics

Optimization Results

System Requirements

Development

Development Environment Setup

Prerequisites

Backend Development

Frontend Development

Code Quality Standards

Backend (Python)

Frontend (TypeScript)

Architecture Patterns

Backend Architecture

Frontend Architecture

Development Workflow