Exam Timetable Planner

1 Introduction

Exam Timetable Planner is a standalone desktop application designed to automatically generate optimized exam schedules for educational institutions. The system processes courses, classrooms, student enrollments, and predefined business constraints to produce a conflict-free and efficient exam timetable.

The primary users of this application are Student Affairs personnel responsible for creating and maintaining examination schedules. The application aims to reduce manual scheduling effort and eliminate human errors in the complex process of exam timetabling.

2 Project Objectives

The main objectives of this project are:

• Automation: Eliminate manual exam scheduling by implementing an intelligent algorithm
• Constraint Satisfaction: Ensure all scheduling rules and institutional policies are respected
• User-Friendly Interface: Provide an intuitive GUI for data import, visualization, and manual adjustments
• Flexibility: Allow manual overrides with real-time constraint validation
• Scalability: Support large-scale institutions with 10,000+ students
• Data Export: Enable exporting of finalized timetables for external use

3 Key Features

4 Screenshots & Demo

Visual demonstration of the application's key screens and functionality.

Main Dashboard

Figure 1: Main application dashboard with analytics and quick actions [Screenshot from actual build]

Data Import

Figure 2: CSV Data Import interface with validation feedback [Screenshot from actual build]

Timetable View

Figure 3: Interactive timetable grid with drag-and-drop support [Screenshot from actual build]

Conflict Detection

Figure 4: Real-time conflict detection and warning system [Screenshot from actual build]

Export Options

Figure 5: Flexible export options supporting multiple formats [Screenshot from actual build]

Application Flow

flowchart LR
    A[📁 Import Data] --> B[🔄 Validate]
    B --> C[🧠 Generate Schedule]
    C --> D[📊 View Timetable]
    D --> E[✏ Manual Adjustments]
    E --> F[📤 Export]
                

5 Scheduling Constraints

The scheduling algorithm enforces the following business rules to ensure fair and practical exam schedules:

6 Scheduling Algorithm

1. Binary Search for Optimal Days

Instead of just trying to "fit" exams into a fixed range, the algorithm performs a Binary Search on the number of days. For any given range [low, high], it attempts to find a valid schedule for mid days. If successful, it tries fewer days to find the true minimum.

2. Course Splitting (Exam Parts)

To handle large courses that exceed the capacity of any single classroom, the system implements Dynamic Course Splitting:

• Balanced Partitioning: Students are divided into N parts where N = ceil(Students / MaxRoomCapacity).
• Simultaneous Scheduling: All parts of a split course are forced into the same time slot across different classrooms to maintain exam integrity.

Algorithm Workflow

flowchart TD
    %% Node Styles
    classDef start fill:#2563eb,stroke:#1d4ed8,stroke-width:2px,color:#fff,rx:20,ry:20
    classDef process fill:#fff,stroke:#cbd5e1,stroke-width:2px,color:#334155,rx:5,ry:5
    classDef decision fill:#fff,stroke:#f59e0b,stroke-width:2px,color:#b45309,rx:5,ry:5
    classDef success fill:#10b981,stroke:#059669,stroke-width:2px,color:#fff,rx:20,ry:20
    classDef fail fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#991b1b,rx:5,ry:5
    classDef loop fill:#f8fafc,stroke:#94a3b8,stroke-width:2px,stroke-dasharray: 5 5,color:#475569

    %% Main Flow
    Start([🚀 Start Generation]):::start --> BinSearch{Binary Search Loop}:::decision
    
    subgraph CSP ["Constraint Satisfaction Core"]
        direction TB
        Sort[Sort Courses (Heuristic)]:::process --> Pick[Pick Most Constrained Course]:::process
        Pick --> CheckTime{Valid Time Slot?}:::decision
        
        CheckTime -->|Yes| CheckRoom{Valid Room?}:::decision
        CheckTime -->|No| Backtrack[Unit Propagation / Backtrack]:::fail
        
        CheckRoom -->|Yes| Assign[Assign Resource & Update State]:::process
        CheckRoom -->|No| Backtrack
        
        Assign --> Complete{All Courses Assigned?}:::decision
        Complete -->|No| Pick
        Backtrack -.->|Retry Next| Pick
    end

    BinSearch -->|Try 'k' Days| CSP
    Complete -->|Yes| Success([✨ Feasible Schedule Found]):::success
    
    Success -->|Optimize| BinSearch
    Backtrack -->|Unsatisfiable| BinSearch

    %% Link Styles
    linkStyle default stroke:#64748b,stroke-width:2px,fill:none
                

Figure 6: High-level overview of the CSP-based backtracking algorithm logic.

Scheduling Sequence

sequenceDiagram
    autonumber
    
    %% Participant Definitions
    actor User as 👤 User
    participant UI as 🎨 MainController
    participant Svc as ⚙️ SchedulerService
    participant Logic as 🧠 ConstraintChecker
    participant Repo as 💾 DataRepository
    participant DB as 🗄️ SQLite

    Note over User, UI: User initiates generation process

    User->>UI: Click "Generate Schedule"
    activate UI
    UI->>UI: Show Loading Spinner (Async)
    
    UI->>Svc: generateTimetable(courses, rooms, constraints)
    activate Svc
    
    Note right of Svc: Strategy: Binary Search on Days
    
    loop For Each Day Count [min..max]
        Svc->>Svc: Sort Courses (Difference Heuristic)
        
        loop Recursive Backtracking
            Svc->>Logic: validate(slot, classroom)
            activate Logic
            Logic-->>Svc: ✅ Valid / ❌ Conflict
            deactivate Logic
            
            alt Constraint Violation
                Svc->>Svc: Prune Branch (Backtrack)
            else Feasible Assignment
                Svc->>Svc: Assign & Recurse
            end
        end
    end

    alt Optimal Solution Found
        Svc->>Repo: saveTimetable(finalSchedule)
        activate Repo
        Repo->>DB: Begin Transaction
        activate DB
        DB->>DB: Batch Insert Exams
        DB-->>Repo: Commit Success
        deactivate DB
        Repo-->>Svc: Acknowledge
        deactivate Repo
        
        Svc-->>UI: return ExamTimetable
        UI->>UI: Render Timetable Grid
        UI->>User: Show Success Notification
    else No Feasible Solution
        Svc-->>UI: throw SchedulingException
        UI->>User: Show Error (Check Constraints)
    end
    
    deactivate Svc
    deactivate UI
                

Figure 7: Detailed sequence diagram illustrating the interaction between UI, Service, and Data layers during schedule generation.

3. Advanced Heuristics & Pruning

To avoid the exponential time complexity of pure backtracking, we use several heuristics:

Complexity Analysis

7 System Architecture

The application follows a strictly Layered Architecture pattern to ensure modularity and scalability. Each component belongs to a specific tier, ensuring that business logic is never coupled with UI rendering.

Architectural Flow

flowchart TD
    subgraph UI_Layer ["🎨 UI Layer (JavaFX)"]
        MC[MainController] --> |Triggers| SM[TourManager/Modals]
        MC --> |Interacts| FXML[FXML/CSS Views]
    end

    subgraph Service_Layer ["⚙ Service Layer (Business Logic)"]
        MC --> SS[SchedulerService]
        MC --> IS[DataImportService]
        SS --> CC[ConstraintChecker]
        SS -.-> ST[ScheduleState]
    end

    subgraph Persistence_Layer ["💾 Persistence Layer (SQLite)"]
        IS --> DR[DataRepository]
        SS --> DR
        DR --> DB[(SQLite Database)]
    end

    subgraph My_Domain ["📁 Domain Layer (POJO)"]
        CC --> D[Student/Course/Exam]
        DR --> D
    end
                

Layer Responsibilities

Key Class Relationships

classDiagram
    class Course { +String code }
    class Student { +String id }
    class Exam { +ExamSlot slot }
    class SchedulerService { +generate() }
    class DataRepository { +save() }
    
    SchedulerService --> DataRepository : uses
    DataRepository ..> Course : persists
    Exam o-- Course : contains
    Exam o-- Student : contains
                

8 Performance Analysis

Benchmarking Results

9 Technologies Used

10 Project Structure

src/main/java/com/examplanner/
├── domain/                 # Core data models
│   ├── Course.java
│   ├── Student.java
│   ├── Classroom.java
│   ├── Exam.java
│   ├── ExamSlot.java
│   └── ExamTimetable.java
├── services/               # Business logic
│   ├── SchedulerService.java
│   ├── ConstraintChecker.java
│   └── DataImportService.java
├── persistence/            # Data access
│   └── DataRepository.java
└── ui/                     # Presentation layer
    ├── MainApp.java
    └── MainController.java
src/main/resources/
├── MainView.fxml
├── SplashScreen.fxml
├── style.css
└── messages_*.properties   # i18n files
src/test/java/com/examplanner/
├── domain/                 # Domain tests
└── services/               # Service tests

11 API Documentation

Key service classes and their public methods:

SchedulerService

ConstraintChecker

DataImportService

12 Testing Strategy

To ensure system reliability and correctness, we adopted a robust testing strategy primarily focused on Unit Testing and Integration Testing. The project utilizes JUnit 5 for test execution and Mockito for isolating dependencies in the service layer.

The Test Pyramid

Our testing approach follows the standard Test Pyramid, emphasizing a strong foundation of fast, isolated unit tests.

pyramid
    "Manual / Exploratory Tests" : 10
    "Integration Tests (Repo & DB)" : 20
    "Unit Tests (Domain & Logic)" : 70
                

Test Categories

Approximate Test Distribution

Note: Coverage metrics are not automatically measured. Values below are estimates.

Example Test Case

Below is a simplified example of how we test the conflict detection logic using Mockito:

@Test
@DisplayName("Should detect conflict when student has concurrent usage")
void shouldDetectConflict() {
    // Arrange
    Student student = new Student("S1", "John Doe");
    ExamSlot slot = new ExamSlot(Day.MONDAY, Time.MORNING);
    
    // Act
    boolean hasConflict = constraintChecker.hasConflict(student, slot);
    
    // Assert
    assertTrue(hasConflict, "Student should not be in two exams at once");
}

13 Installation Guide

Prerequisites

• Java Development Kit (JDK) 21 or higher
• Apache Maven 3.9 or higher
• Git (for cloning the repository)

Installation Steps

1. Clone the repository

   git clone https://github.com/utkubilir/ExamTimetablePlanner.git
   cd ExamTimetablePlanner

2. Build the project

   mvn clean install

3. Run the application

   mvn javafx:run

★ Quick Start (2 Minutes)

1. Prerequisites: JDK 21+, Maven 3.9+
2. Clone & Run:

   git clone https://github.com/utkubilir/ExamTimetablePlanner.git
   cd ExamTimetablePlanner
   mvn javafx:run

3. Demo Flow:
   • Navigate to Data Import tab
   • Load sample files from csv's/Small/ directory
   • Click "Generate Schedule"
   • View timetable, make manual adjustments if needed
   • Export the result via Export button

14 Project Team

Doğan Mert İlhan

Developer

Utku Bilir

Developer

Deniz Yıldırım

Developer

Arda Barut

Developer

Furkan Galip

Developer

Mert Barmanbek

Developer

15 Frequently Asked Questions

Technical & Performance

Usage & Configuration

Troubleshooting

★ CSV File Formats

The application imports data from four CSV files. All files must be UTF-8 encoded.

Courses CSV

Single column, one course code per line. First line is a header (ignored).

ALL OF THE COURSES IN THE SYSTEM
CourseCode_01
CourseCode_02
CourseCode_03

Classrooms CSV

Semicolon-delimited: ClassroomID;Capacity. First line is a header.

ALL OF THE CLASSROOMS; AND THEIR CAPACITIES IN THE SYSTEM
Classroom_01;25
Classroom_02;30
Classroom_03;40

Students CSV

Single column list of student IDs. First line is a header.

ALL OF THE STUDENTS IN THE SYSTEM
Std_ID_001
Std_ID_002

Attendance/Enrollment CSV

Course code on one line, followed by a Python-list-style array of student IDs on the next.

CourseCode_01
['Std_ID_001', 'Std_ID_002', 'Std_ID_003']

CourseCode_02
['Std_ID_004', 'Std_ID_005']

16 Data Import Strategy

Smart Format Detection (Heuristic Detection)

A detection mechanism named detectCsvKind was developed to prevent users from uploading the wrong file. This method scans the first 50 lines of the file to analyze column headers and data patterns. For example, if a line contains ';' and the second part is a numeric value, it understands that this is a **Classrooms** file. This allows the system to give the "You uploaded the wrong file" warning before the user even clicks the 'Import' button.

BOM and Character Encoding Solutions

The **BOM (Byte Order Mark)** character frequently found in CSV files exported from Excel could cause invisible errors in standard Java readers. The stripBom method was developed to clean these hidden characters at the beginning of each line. A flexible parser structure was also established that simultaneously supports both semicolon and comma-separated formats.

Data Consistency and Automatic Repair

One of the most critical logics in the system operates during **Attendance** transfer. If a student exists in 'attendance.csv' but is not defined in 'students.csv', instead of stopping the transfer, the system automatically creates this student and saves them to the database. This is an important "fail-safe" mechanism that prevents gaps in the dataset from locking up the entire planning process.

★ Limitations & Known Issues

• "No feasible solution" error: Occurs when constraints are too tight (e.g., too many overlapping enrollments, insufficient classrooms, too few available days). Try increasing the exam period or relaxing constraints.
• Worst-case performance: The backtracking algorithm has exponential worst-case complexity. Highly constrained inputs with many student overlaps may take significantly longer.
• No UI for constraint configuration: Parameters like max exams/day are set programmatically via setter methods; a settings UI is planned for future versions.
• No automated CI/CD: Tests must be run locally with mvn test.
• No coverage reporting: JaCoCo is not configured; coverage metrics are not measured.
• No release packages: The application must be built and run from source. No installer or executable JAR is provided.

17 Conclusion

The Exam Timetable Planner project has successfully achieved its primary objective of automating the exam scheduling process. By leveraging a Constraint Satisfaction Problem (CSP) solver and a user-friendly JavaFX interface, the system transforms a weeks-long manual task into a sub-second automated operation.

Key successes include the robust handling of large datasets (10,000+ students), the "fail-safe" data import strategy, and the implementation of a responsive, modern UI that adheres to strict software engineering principles. The system not only saves time but also guarantees conflict-free schedules, significantly improving the operational efficiency of educational institutions.

18 References

• GitHub Repository: https://github.com/utkubilir/ExamTimetablePlanner
• JavaFX Documentation: https://openjfx.io/
• JUnit 5 User Guide: https://junit.org/junit5/
• SQLite Documentation: https://www.sqlite.org/