Constraint-aware academic timetabling that just works
Rooms + Faculty + Sections + Courses → one click → collision-free weekly schedule
-4285F4?style=flat-square&logo=googlechrome&logoColor=white){kind=icon}
- Overview
- Why University Scheduler?
- System Architecture
- General Processing Overview
- Features and User Interface Guides
- Scheduling Engine and Constraint System
- Quick Start and Usage
- Project Structure and Key Components
- Seed Data
- Technology Stack
- Improvement Ideas
- Author
University Scheduler is a client-side web application that generates conflict-free university timetables through a guided 7-step wizard. Input your classrooms, faculty, student sections, and courses — the constraint-satisfaction engine handles the rest.
The app supports two scheduling paradigms:
| Mode | Time Model | Best For |
|---|---|---|
| Fixed | 10 discrete 45-min slots per day (09:10–17:25) | Traditional universities with rigid bell schedules |
| Fluid | Continuous time packing (08:00–22:00, 15-min granularity) | Business schools / flexible programs with 60–180 min blocks |
All processing runs entirely in the browser. No backend, no API keys, no data leaves your machine. Schedule data persists automatically via
localStorage.
Manual timetabling for 28 sections, 18 faculty, and 61 courses is a multi-week nightmare. University Scheduler does it in under 5 seconds.
| Manual Timetabling | University Scheduler | |
|---|---|---|
| Time | Days to weeks of spreadsheet wrangling | < 5 seconds automatic generation |
| Conflicts | Discovered after the fact — faculty double-booked, rooms overflowing | Hard constraints enforced at generation time — zero conflicts guaranteed |
| Open Electives | Manually synchronize 25 OE courses across all sections of a year | Automatic year-wide OE synchronization with section-conflict exemption |
| Adjustments | Re-do the spreadsheet | Drag-and-drop with real-time constraint validation |
| Lunch Breaks | Easy to forget | Automatically preserved (slots 5 & 6 protected) |
| Visiting Faculty | Track availability manually | Time-window constraints built into the engine |
| Views | One giant spreadsheet | Four perspectives — Weekly, by Section, by Faculty, by Classroom |
graph TD
subgraph UI["UI Layer — React 19"]
App["App.jsx\nStep Router"] --> R["🏫 RoomsStep"]
App --> F["👨🏫 FacultyStep"]
App --> Sec["🎒 SectionsStep"]
App --> C["📚 CoursesStep"]
App --> A["🔗 AssignmentsStep"]
App --> G["🚀 GenerateStep"]
App --> V["📅 ViewScheduleStep\n4 views · drag-and-drop"]
Sidebar["Sidebar.jsx\nNavigation · Mode Toggle"] --> App
end
subgraph Core["Core Engine"]
Ctx["AppContext.jsx\nrooms · faculty · sections\ncourses · schedule · mode"] -->|feeds data| Sched
Sched["scheduler.js\ngenerateSchedule — Greedy CSP\ngenerateFluidSchedule — Duration Packing"]
Ctx -->|auto-persist| LS[(localStorage)]
end
G -->|triggers| Sched
Sched -->|scheduleEntries| V
Ctx --> UI
ASCII fallback (click to expand)
┌─────────────────────────────────────────────────────────────────┐
│ University Scheduler │
│ │
│ ┌───────────────┐ ┌──────────────────────────────────────┐ │
│ │ App.jsx │ │ UI Layer (React 19) │ │
│ │ Step Router │ │ │ │
│ │ │ │ ┌────────┐ ┌────────┐ ┌──────────┐ │ │
│ │ currentStep ├───►│ │ Rooms │ │Faculty │ │Sections │ │ │
│ │ state drives │ │ │ Step │ │ Step │ │ Step │ │ │
│ │ rendering │ │ └────────┘ └────────┘ └──────────┘ │ │
│ └───────────────┘ │ ┌────────┐ ┌────────┐ ┌──────────┐ │ │
│ │ │Courses │ │Assign- │ │Generate │ │ │
│ ┌───────────────┐ │ │ Step │ │ ments │ │ Step │ │ │
│ │ Sidebar.jsx │ │ └────────┘ └────────┘ └──────────┘ │ │
│ │ │ │ ┌─────────────────────────────────┐ │ │
│ │ Navigation │ │ │ ViewScheduleStep (784 lines) │ │ │
│ │ Mode toggle │ │ │ - 4 view modes │ │ │
│ │ Data actions │ │ │ - Drag & drop editing │ │ │
│ │ Summary │ │ │ - Constraint validation │ │ │
│ └───────────────┘ │ └─────────────────────────────────┘ │ │
│ └──────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Core Engine │ │
│ │ │ │
│ │ ┌──────────────────┐ ┌──────────────────────────┐ │ │
│ │ │ AppContext.jsx │ │ scheduler.js (722 lines)│ │ │
│ │ │ │ │ │ │ │
│ │ │ rooms[] │ │ generateSchedule() │ │ │
│ │ │ faculty[] │───►│ - Greedy CSP engine │ │ │
│ │ │ sections[] │ │ - OE priority system │ │ │
│ │ │ courses[] │ │ - Slot scoring │ │ │
│ │ │ schedule │ │ │ │ │
│ │ │ scheduleMode │ │ generateFluidSchedule() │ │ │
│ │ └────────┬─────────┘ │ - Duration packing │ │ │
│ │ │ │ - Continuous intervals │ │ │
│ │ ▼ └──────────────────────────┘ │ │
│ │ ┌──────────────────┐ │ │
│ │ │ localStorage │ Auto-persist on every change │ │
│ │ └──────────────────┘ │ │
│ └──────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
flowchart LR
A["📝 Define Data\nSteps 1–4"] --> B["🔗 Build Assignments\nStep 5"]
B --> C["⚙️ Generate Schedule\nStep 6"]
C --> D["📅 View & Edit\nStep 7"]
B --- B1["Faculty → Components\nL · D · P1 · P2"]
B --- B2["Sections → Courses\nSingle or Combined"]
C --- C1["1. Collect tasks"]
C --- C2["2. Sort: OE → Visiting → Large"]
C --- C3["3. Greedy-assign with scoring"]
C --- C4["4. Report unscheduled"]
D --- D1["Weekly · Section · Faculty · Room"]
D --- D2["Drag-and-drop editing"]
ASCII fallback (click to expand)
Define Data (Steps 1-4)
│
▼
Build Assignments (Step 5):
Faculty → Course Components (L, D, P1, P2)
Sections → Courses (single or combined)
│
▼
Generate Schedule (Step 6):
1. Collect tasks from all course×section×component combos
2. Sort: OE first → Visiting faculty → Large enrollment
3. Schedule OE at hardcoded slots (all same time, different rooms)
4. Greedy-assign remaining: score each day×slot, pick best
5. Report unscheduled tasks with reasons
│
▼
View & Edit (Step 7):
4 perspectives + drag-and-drop manual adjustment
The scheduling workflow processes user inputs through a streamlined pipeline:
- Resource Definition & Assignment Matrix: Users define rooms, faculty, sections, and courses, then link professors to components (Lecture, Discussion, Practical) and sections to courses.
- Task Prioritization: Tasks are prioritized automatically — Open Electives (OE) are assigned first at standardized time windows, followed by Visiting Faculty with restricted availability, and finally high-enrollment courses requiring larger rooms.
- Constraint Resolution Engine: For Fixed mode, candidate day×slot combinations are evaluated against 8 hard constraints and scored with heuristics. For Fluid mode, continuous duration blocks are packed into the 08:00–22:00 daily window using 15-minute intervals.
- Interactive Adjustment & Fallbacks: Drag-and-drop operations trigger real-time constraint validation. If a room conflict occurs, the system automatically searches for alternative matching rooms and prompts the user for reassignment.
Each step gates progression to ensure all prerequisite data is entered before generating:
| Step | Icon | Purpose & Controls |
|---|---|---|
| 1. Classrooms | 🏫 | Define room names, seating capacities, room types (Regular / Lab / Boardroom), and available equipment. |
| 2. Faculty | 👨🏫 | Add professors, set Home vs. Visiting status, max teaching hours per day, and visiting time availability grids. |
| 3. Sections | 🎒 | Create student sections grouped by academic year, department, and student headcount. |
| 4. Courses | 📚 | Define course codes, credit distribution (LDP model: Lecture / Discussion / Practical-1 / Practical-2), and Open Elective flags. |
| 5. Assignments | 🔗 | Map faculty members to course components and assign student sections (individual or combined) to courses. |
| 6. Generate | 🚀 | One-click schedule creation using the CSP solver; displays generation status and unscheduled task reports. |
| 7. View | 📅 | Interactive 4-view timetable dashboard supporting drag-and-drop adjustments with constraint feedback. |
Toggle modes at any time via the sidebar header pill buttons:
| Feature | Fixed Mode | Fluid Mode |
|---|---|---|
| Time Model | 10 discrete 45-min slots (09:10–17:25) | Continuous minutes (08:00–22:00) |
| Granularity | Fixed bell schedule | 15-minute snap intervals |
| Component Handling | Standard LDP slots (P2 = consecutive 2-slot pair) | Custom duration blocks (60–180 min) |
| Rendering | Grid-based weekly timetable | Absolute-positioned timeline with 30-min markers |
| Seed Dataset | 61 courses, 28 sections, 18 faculty | 5 MBA courses, 4 sections, 5 faculty |
flowchart TD
Start["Drag Block to New Slot"] --> E1{"Slot is Lunch?"}
E1 -->|Yes| FailLunch["❌ LUNCH_CONFLICT\nRed banner alert"]
E1 -->|No| E2{"Faculty or Section Conflict?"}
E2 -->|Yes| FailConflict["❌ FACULTY/SECTION CONFLICT\nRed banner alert"]
E2 -->|No| E3{"Room Occupied?"}
E3 -->|No| Valid["✅ Move Accepted"]
E3 -->|Yes| Search["🔍 Find Alternative Room\n(matching type & capacity)"]
Search --> Found{"Alternative Found?"}
Found -->|Yes| Prompt["⚠️ Show Reassignment Prompt\n[Accept Reassignment] [Cancel]"]
Found -->|No| FailRoom["❌ ROOM_CONFLICT\nRed banner alert"]
ASCII fallback (click to expand)
Drag Block to New Slot
├── Slot is Lunch? ──► Yes ──► Red banner: LUNCH_CONFLICT
├── Faculty or Section Conflict? ──► Yes ──► Red banner: CONFLICT
└── Room Occupied?
├── No ──► Move Accepted
└── Yes ──► Search Alternative Room (matching type & capacity)
├── Found? Yes ──► Show Prompt: "Accept Reassignment / Cancel"
└── Found? No ──► Red banner: ROOM_CONFLICT
- Real-time validation: Validates professor, section, and room constraints instantly on drop.
- Automated room search: On room conflict, searches for free rooms of matching type and sufficient capacity.
- User prompt: Displays an "Accept Reassignment / Cancel" interactive prompt.
- Alert banners: Invalid moves trigger auto-dismissing (4s) red warning banners.
| View | Description | Filters |
|---|---|---|
| Weekly | Comprehensive 5-day × 10-slot grid displaying all scheduled events | — |
| By Section | Personalized weekly schedule for a specific student section | Section selector |
| By Faculty | Teaching schedule and daily/weekly hour load per professor | Faculty selector |
| By Classroom | Room utilization timeline with free/busy indicators and percentage metrics | Classroom selector |
The fixed-mode solver organizes tasks into a priority queue:
- Open Electives (OE): High priority, scheduled into dedicated uniform slots.
- Visiting Faculty: Restricted availability windows prioritize these tasks early.
- Large Enrollment Courses: Scheduled next to secure high-capacity rooms.
Slot Scoring Matrix (Base 100):
- Mid-day slots (3–7): +10 bonus
- Lunch slots (5–6): -20 penalty
- Daily distribution penalty: -2 per existing class on that day (ensures balanced workload)
| # | Constraint | Description |
|---|---|---|
| 1 | Professor Daily Hour Limit | Prevents exceeding faculty max teaching hours per day. |
| 2 | Visiting Faculty Availability | Restricts scheduling to specified day/slot time windows. |
| 3 | Professor Conflict | Ensures a professor is not double-booked in the same time slot. |
| 4 | Section Conflict | Prevents student sections from having overlapping classes (exempt for OE). |
| 5 | Lunch Break Preservation | Ensures at least one lunch slot (slot 5 or 6) remains free daily. |
| 6 | Room Availability | Prevents double-booking of classrooms. |
| 7 | Room Capacity | Guarantees room capacity meets or exceeds section headcount. |
| 8 | Wednesday 6-Period Cap | Limits total teaching periods on Wednesdays to a maximum of 6. |
- Lecture / Discussion / P1: Scheduled on Monday, slot 9 (15:50–16:35).
- Practical-2 (P2): Scheduled on Tuesday, slots 8–9 (15:00–16:35).
- Multi-room Sync: All OE courses share identical time slots across different rooms, allowing students from any section to enroll in their chosen elective without timetable clashes.
- Node.js: 18.0.0 or higher
- npm: 9.0.0 or higher
# Clone the repository
git clone https://github.com/Felix-au/schedule-step-by-step-.git
# Navigate into the project directory
cd university-scheduler
# Install dependencies
npm install
# Start development server
npm run devApplication URL: http://localhost:5173
Click "📥 Load Sample Data" in the sidebar to populate pre-configured datasets:
- Fixed Mode: 20 classrooms, 18 faculty members, 28 sections, 61 courses (including 25 Open Electives).
- Fluid Mode: 5 classrooms, 5 faculty members, 4 MBA/BBA sections, 5 pre-assigned custom duration courses.
university-scheduler/
├── src/
│ ├── components/
│ │ ├── Sidebar.jsx # Navigation, mode toggle, data actions
│ │ ├── Sidebar.css # Responsive sidebar styling
│ │ └── steps/
│ │ ├── RoomsStep.jsx # Classroom CRUD & capacity controls
│ │ ├── FacultyStep.jsx # Faculty management & availability grid
│ │ ├── SectionsStep.jsx # Section definition by year & department
│ │ ├── CoursesStep.jsx # Course & LDP distribution editor
│ │ ├── AssignmentsStep.jsx # Component & section assignment linking
│ │ ├── GenerateStep.jsx # Schedule generator trigger & status
│ │ ├── ViewScheduleStep.jsx # Interactive 4-view timetable & drag-drop
│ │ ├── Steps.css # Shared step styling
│ │ └── ViewSchedule.css # Timetable layout & drag-drop styles
│ ├── context/
│ │ └── AppContext.jsx # Global state manager & localStorage sync
│ ├── data/
│ │ └── seedData.js # Fixed and Fluid sample datasets
│ ├── utils/
│ │ └── scheduler.js # Fixed & Fluid scheduling engine
│ ├── App.jsx # Main step router
│ ├── App.css # Application container layout
│ ├── index.css # Design system tokens & global styling
│ └── main.jsx # Application entry point
├── index.html # HTML entry document
├── package.json # Project manifests & dependencies
├── vite.config.js # Vite build configuration
├── vercel.json # Deployment routing rules
├── eslint.config.js # Linter configuration
├── README.md # Project documentation
├── guide.md # Quick start reference
└── LICENSE # MIT License
| Component | File | Role |
|---|---|---|
| App Controller | App.jsx |
Step router managing active wizard views. |
| State Manager | AppContext.jsx |
Global state context managing rooms, faculty, sections, courses, schedule, and mode auto-synced to localStorage. |
| Navigation Sidebar | Sidebar.jsx |
Step navigation, mode toggling, sample data loader, and storage reset actions. |
| Fixed Solver | scheduler.js:generateSchedule() |
Greedy CSP engine enforcing 8 hard constraints with slot heuristic scoring. |
| Fluid Solver | scheduler.js:generateFluidSchedule() |
Continuous-time duration packing engine operating on 15-minute intervals. |
| Timetable Viewer | ViewScheduleStep.jsx |
Multi-perspective renderer supporting drag-and-drop adjustments and automatic room reassignment prompts. |
| Seed Data Registry | seedData.js |
Built-in engineering and business school datasets for testing. |
| Entity | Count | Overview |
|---|---|---|
| Classrooms | 20 | Capacities ranging from 30 to 80 (GA-series, NB-series, Lab facilities). |
| Faculty | 18 | Computer Science (10), Mathematics (3), Physics (2), Skills (2), Liberal Studies (1). |
| Sections | 28 | Batches 2025 (9 sections), 2024 (10 sections), 2023 (9 sections). |
| Courses | 61 | 36 core curriculum courses + 25 Open Elective (OE) offerings. |
| Entity | Count | Overview |
|---|---|---|
| Classrooms | 5 | Capacities from 30 to 100 (Lecture halls, seminar rooms, boardrooms). |
| Faculty | 5 | Finance, Marketing, Strategy, HR, Operations management. |
| Sections | 4 | MBA 2024 (2 sections), BBA 2025 (2 sections). |
| Courses | 5 | Continuous duration modules (60–180 min duration blocks). |
| Layer | Technology | Version |
|---|---|---|
| Core Library | React | 19.2 |
| Build System | Vite | 8 (Beta) |
| State Persistence | Web Storage API (localStorage) |
Native |
| Styling | Vanilla CSS (Custom Properties) | CSS3 |
| Linting | ESLint | 9.x |
| Deployment | Vercel SPA | Rewrite Configured |
- Export Capabilities: PDF calendar generation and CSV schedule data exports.
- Algorithmic Solver Enhancements: Backtracking fallback solver for tightly constrained scenarios.
- Analytics Dashboard: Visual reports covering room occupancy percentages and faculty workload distribution.
- Data Mobility: CSV/Excel bulk import utilities for quick setup.
- Theme & UX Polish: Full dark mode support and keyboard accessible ARIA navigation.
Felix-au (Harshit Soni)
- 🔗 GitHub: github.com/Felix-au
- 📧 Email: felixaugum@gmail.com
Built for registrars who refuse to wrestle with spreadsheets.