University Timetable Management System

A production-grade, constraint-based timetable generation system for universities, built with a clean three-repository architecture.

🚀 Quick Start

For detailed setup instructions, see SETUP_GUIDE.md

Prerequisites

• Python 3.10+
• Node.js 18+
• PostgreSQL 14+

Quick Setup (macOS/Linux)

# 1. Set up database
psql postgres -c "CREATE DATABASE timetable_db;"
psql postgres -c "CREATE USER timetable_user WITH PASSWORD 'timetable_password';"
psql postgres -c "GRANT ALL PRIVILEGES ON DATABASE timetable_db TO timetable_user;"

# 2. Run setup script
./QUICK_START.sh

# 3. Create superuser
cd backend
source venv/bin/activate
python manage.py createsuperuser
deactivate
cd ..

# 4. Start services (in separate terminals)
# Terminal 1 - Backend:
cd backend && source venv/bin/activate && python manage.py runserver

# Terminal 2 - Frontend:
cd frontend && npm start

Then open http://localhost:3000 in your browser!

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    Frontend (React)                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                  │
│  │  Admin   │  │ Faculty  │  │ Student  │                  │
│  └──────────┘  └──────────┘  └──────────┘                  │
└──────────────────────┬──────────────────────────────────────┘
                       │ REST API
┌──────────────────────▼──────────────────────────────────────┐
│              Backend (Django)                                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Auth &     │  │   CRUD APIs  │  │  Timetable   │     │
│  │  Permissions │  │              │  │  Management  │     │
│  └──────────────┘  └──────────────┘  └──────┬───────┘     │
└──────────────────────────────────────────────┼─────────────┘
                                               │ Library Call
┌──────────────────────────────────────────────▼─────────────┐
│         Timetable Engine (Python/GA)                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │  Constraint  │  │   Genetic    │  │   Fitness    │     │
│  │  Validator   │  │  Algorithm   │  │  Evaluator   │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└────────────────────────────────────────────────────────────┘

📦 Repository Structure

1. tt-engine/ - Timetable Generation Engine

Purpose: Pure constraint-based timetable generation logic
Tech: Python, Genetic Algorithm, Constraint Optimization
Status: Stateless, library/service

Key Features:

• Genetic Algorithm for conflict-free timetable generation
• Multi-constraint validation (faculty, room, section, time)
• Lab block continuity enforcement
• Deterministic generation with seeds
• Export to structured JSON

2. backend/ - Django REST API

Purpose: Data management, orchestration, integration
Tech: Django, Django REST Framework, PostgreSQL
Status: Stateful, persistent storage

Key Features:

• CRUD APIs for all entities
• Timetable lifecycle management
• Authentication & role-based authorization
• Integration with TT engine
• Versioning & audit logs

3. frontend/ - React UI

Purpose: Role-based user interface
Tech: React, TypeScript, Material-UI
Status: Static SPA

Key Features:

• Admin dashboard with drag-and-drop
• Faculty availability management
• Student read-only views
• Export to PDF/Excel

📋 Data Flow

1. Configuration: Admin configures departments, faculty, rooms, subjects via FE
2. Generation: Admin triggers generation → BE calls TT engine with constraints
3. Storage: BE stores generated timetable with versioning
4. Display: FE fetches timetable via BE APIs and renders in grid/views
5. Modification: Admin can manually override → BE validates → Updates stored timetable

🔐 Roles & Permissions

Role	Permissions
Admin	Full CRUD, timetable generation, manual overrides, export
Faculty	View personal timetable, set availability, view workload
Student	Read-only timetable view (section-wise)

📊 Core Entities

• Department: Academic department (e.g., Computer Science)
• Course: Degree program (e.g., B.Tech CSE)
• Subject: Individual course subject (e.g., Data Structures)
• Faculty: Teaching staff with availability constraints
• Room/Lab: Physical spaces with capacity and type
• Section: Student batch (e.g., CSE-A, CSE-B)
• TimeSlot: Time period (e.g., 9:00-10:00, Mon-Fri)
• Timetable: Generated schedule mapping (Subject, Faculty, Room, Section, TimeSlot)

🎯 Constraints

Hard Constraints (Must Satisfy)

• No faculty overlap (same faculty, same time)
• No room overlap (same room, same time)
• No section overlap (same section, same time)
• Room capacity ≥ section size
• Room type matches subject requirement (lab vs classroom)
• Lab blocks are continuous (no gaps)

Soft Constraints (Optimize For)

• Faculty daily/weekly load limits
• Balanced distribution across days
• Preference for morning slots
• Minimize room changes for sections

📝 Documentation

• Setup Guide - Detailed setup instructions
• API Contracts - Complete API specification
• GA Constraints - Constraint definitions
• Architecture - System architecture details
• Deployment - Production deployment guide

🧪 Testing

Each repository includes comprehensive tests:

• TT Engine: Unit tests for constraints, GA fitness, generation
• Backend: API tests, integration tests, model tests
• Frontend: Component tests, E2E tests

🔄 Development Workflow

1. Make changes in respective repo
2. Run tests locally
3. Update documentation if needed
4. Commit with clear messages
5. Deploy independently (each repo is deployable separately)

📄 License

MIT License

🤝 Contributing

See CONTRIBUTING.md for guidelines.

🆘 Getting Help

1. Check SETUP_GUIDE.md for common issues
2. Review error messages in terminal
3. Ensure all services are running
4. Verify environment variables are set correctly