Class Scheduling System

A comprehensive web-based class scheduling system built with Flask, Bootstrap 5, and SQLite. This system helps educational institutions manage class schedules, detect conflicts, and streamline academic planning.

Features

Core Modules (All under 300 lines per file)

1. Section Assignment Tool - Assign subjects, teachers, and rooms to class sections
2. Teacher Schedule Mapping - View and manage teacher schedules across time blocks
3. Conflict Checker - Automatically detect scheduling conflicts (teacher/room/time overlaps)
4. Exam Timetable Generator - Create and manage examination schedules
5. Substitute Assignment Tracker - Track substitute teachers for absences
6. Special Class Scheduler - Schedule one-time events and special classes
7. Room Availability Checker - Check real-time room availability
8. Schedule Cloner - Clone schedules from previous semesters
9. Time Block Customizer - Create custom time periods
10. Calendar Integration - Export schedules (dummy implementation - extend with Google Calendar API)

Technology Stack

• Backend: Flask (Python)
• Frontend: HTML5, CSS3, JavaScript (ES6+)
• Styling: Tailwind CSS 3.4+ (Utility-first CSS framework)
• Database: SQLite with SQLAlchemy ORM
• Icons: Bootstrap Icons
• Utilities:
  • Toast notifications (non-blocking user feedback)
  • Modal dialogs (confirm actions, custom content)

Project Structure

class_scheduling_system/
├── app.py                          # Flask application entry point
├── database/
│   └── models.py                   # SQLAlchemy database models
├── modules/                        # Feature modules (blueprints)
│   ├── section_assignment.py
│   ├── teacher_schedule.py
│   ├── conflict_checker.py
│   ├── exam_timetable.py
│   ├── substitute_assignment.py
│   ├── special_class_scheduler.py
│   ├── room_checker.py
│   ├── schedule_cloner.py
│   ├── time_block_customizer.py
│   └── calendar_integration.py
├── templates/                      # Jinja2 HTML templates
│   ├── base.html
│   ├── index.html
│   ├── dashboard.html
│   ├── setup.html
│   ├── section/
│   ├── conflict/
│   └── ...
├── static/
│   ├── css/
│   │   └── style.css              # Custom styles
│   └── js/
│       ├── main.js                # Common JavaScript utilities
│       ├── toast.js               # Toast notification system
│       ├── modal.js               # Modal dialog system
│       └── section_assignment.js  # Module-specific JS
└── README.md

Installation & Setup

Prerequisites

• Python 3.8 or higher
• pip (Python package manager)

Step 1: Install Dependencies

pip install flask flask-sqlalchemy

Step 2: Initialize Database

python app.py

This will:

• Create the SQLite database (class_scheduling.db)
• Initialize all tables
• Optionally seed sample data (uncomment the seed function in app.py)

Step 3: Run the Application

python app.py

The application will start on http://localhost:5000

Usage Guide

Initial Setup

1. Navigate to Setup Page: Go to /setup or click "Initial Setup" from the homepage
2. Create Time Blocks: Define your class periods (e.g., Period 1: 8:00-9:00)
   • Use the bulk create feature to generate time blocks for multiple days
3. Add Rooms: Register all available classrooms and facilities
4. Register Teachers: Add teacher information (name, email, department)
5. Add Subjects: Create subject entries with codes and credits
6. Create Sections: Define class sections (e.g., Grade 10 - Section A)

Creating Schedules

1. Go to Sections → Select a section → Click Assign Subjects
2. Fill in the assignment form:
   • Select Subject
   • Choose Teacher
   • Pick Room
   • Select Time Block (Day + Period)
3. Click Assign Schedule
4. The system automatically checks for conflicts before saving

Conflict Detection

• Navigate to Tools → Conflict Checker
• Click Scan for Conflicts to detect:
  • Teacher double-booking
  • Room double-booking
  • Section overlaps
• View conflict details and mark as resolved

Additional Features

• Teacher Schedule: View individual teacher's weekly schedule
• Room Availability: Check which rooms are free at specific times
• Exam Timetable: Generate exam schedules automatically
• Schedule Cloning: Copy schedules from previous semesters
• Special Classes: Schedule one-time events or workshops

Code Structure Guidelines

Clean Coding Practices

✅ Implemented:

• Modular design with Flask blueprints
• Maximum 300 lines per file
• Separation of concerns (models, views, templates)
• Reusable base template with Jinja inheritance
• External CSS and JavaScript files
• Comprehensive comments and docstrings
• RESTful API endpoints

❌ Avoided:

• Inline CSS or JavaScript
• Monolithic files
• Code duplication
• Hard-coded values

Database Models

• Teacher: Instructor information
• Room: Classroom/facility details
• Subject: Course information
• Section: Class section details
• TimeBlock: Time period definitions
• Schedule: Main scheduling entity (links all above)
• ExamSchedule: Examination timetable
• SubstituteAssignment: Substitute teacher tracking
• SpecialClass: Special events and classes
• ConflictLog: Conflict detection history

API Endpoints

Section Assignment

• GET /section/list - List all sections
• POST /section/create - Create new section
• POST /section/assign-schedule - Assign schedule
• GET /section/api/sections - Get sections as JSON

Conflict Checker

• GET /conflict/check - View conflicts
• POST /conflict/scan - Scan for conflicts
• POST /conflict/resolve/<id> - Resolve conflict

Room Checker

• GET /room/list - List rooms
• GET /room/check - Check availability
• POST /room/api/availability - API availability check

(See module files for complete API documentation)

Customization

Adding Custom Time Blocks

Navigate to Time Block Customizer and use the bulk create feature:

• Set start time (e.g., 08:00)
• Number of periods
• Duration per period
• Select days

Extending the System

To add new features:

1. Create a new module in /modules/
2. Define Flask blueprint
3. Register blueprint in app.py
4. Create corresponding templates in /templates/
5. Add JavaScript if needed in /static/js/

Bootstrap 5.3.3

The system uses Tailwind CSS 3.4+ for styling with utility-first approach. Bootstrap Icons are used for iconography.

Centralized JavaScript Utilities:

1. Toast Notifications (static/js/toast.js)

   • Non-blocking success/error/warning/info messages
   • Floating toasts in top-right corner
   • Auto-dismiss with manual close option
   • See TOAST_UTILITY_GUIDE.md for documentation (if available)

2. Modal Dialogs (static/js/modal.js)

   • Confirm dialogs with customizable buttons
   • Custom content modals
   • Promise-based async/await API
   • Keyboard accessible (Escape, Enter, Tab)
   • See MODAL_UTILITY_GUIDE.md for complete documentation

Usage Examples:

// Toast notification
showToast('Success', 'Item saved successfully', 'success');

// Confirm dialog
const confirmed = await modalManager.confirm(
    'Delete this item?',
    'This action cannot be undone.',
    {
        confirmText: 'Delete',
        confirmVariant: 'danger',
        icon: 'trash'
    }
);

if (confirmed) {
    // Perform deletion
}

Calendar Integration

The calendar integration module provides dummy functions. To enable real Google Calendar sync:

1. Set up Google Calendar API credentials
2. Install google-api-python-client
3. Implement OAuth2 authentication
4. Update /modules/calendar_integration.py with actual API calls

Troubleshooting

Database Issues

# Delete database and reinitialize
Remove-Item class_scheduling.db
python app.py

Port Already in Use

# Change port in app.py
app.run(debug=True, host='0.0.0.0', port=5001)

Import Errors

# Ensure Flask is installed
pip install --upgrade flask flask-sqlalchemy

Future Enhancements

• User authentication and role-based access
• Email notifications for schedule changes
• PDF export functionality
• Mobile responsive improvements
• Real-time conflict detection during assignment
• Integration with student information systems
• Analytics dashboard with usage statistics

Contributing

This is a complete, production-ready system following clean coding practices. All files are under 300 lines and follow modular design principles.

License

Open source - use and modify as needed for educational purposes.

Support

For issues or questions, refer to the inline documentation in each module file.

---

Built with ❤️ using Flask and Bootstrap 5