Se302/README.md

Exam Scheduling System

A desktop application for automated exam scheduling using Constraint Satisfaction Problem (CSP) solving techniques. Built with Java and JavaFX for educational institutions to efficiently generate conflict-free exam schedules.

---

Table of Contents

• Features
• Quick Start
• Installation
• Usage
• Project Structure
• Development
• Testing
• Documentation
• Team
• License

---

Features

Core Functionality

• CSV Data Import: Import students, courses, classrooms, and enrollment data from CSV files
• Intelligent Scheduling: Automated exam scheduling using backtracking CSP solver
• Constraint Validation: Enforces hard constraints:
  • No consecutive exams for any student
  • Maximum 2 exams per student per day
  • Classroom capacity limits respected
• Multiple Optimization Strategies:
  • Minimize days used
  • Balance distribution across exam period
  • Minimize classrooms needed
  • Balance classroom usage per day
• Multi-View Display:
  • Classroom view (which exams in which rooms)
  • Student view (personal exam schedule)
  • Course view (exam details per course)
  • Day view (grid layout by day and time slot)
• Export Capabilities: Export schedules to CSV or Excel (.xlsx) format
• Manual Adjustments: Edit schedules with real-time constraint validation
• Schedule History: Save, load, and compare previous schedules
• Conflict Detection: Detailed reporting when no valid schedule exists

Technical Highlights

• Performance: Generates schedules for 20 courses, 250 students in < 5 seconds
• Scalability: Handles datasets up to 50 courses, 500+ students
• Reliability: 100% constraint satisfaction guarantee
• User-Friendly: Clear error messages, progress indicators, intuitive UI

---

Quick Start

# Clone the repository
git clone https://github.com/sabazadam/se302.git
cd se302

# Build the project
mvn clean install

# Run the application
mvn javafx:run

---

Installation

Prerequisites

• Java Development Kit (JDK) 17 or higher
  • Download: Oracle JDK or OpenJDK
• Maven 3.8+ (for building from source)
  • Download: Apache Maven
• Operating System: Windows 10/11, macOS, or Linux
• Minimum Hardware:
  • 2 GHz dual-core processor
  • 4 GB RAM
  • 100 MB disk space

Installation Steps

Option 1: Run from JAR (Recommended for Users)

1. Download the latest release JAR from Releases
2. Double-click the JAR file or run from command line:

   java -jar exam-scheduler-1.0.0-jar-with-dependencies.jar
   

Option 2: Build from Source (For Developers)

1. Clone the repository:

   git clone https://github.com/sabazadam/se302.git
   cd se302
   

2. Build the project:

   mvn clean package
   

3. Run the application:

   mvn javafx:run
   

   Or run the generated JAR:

   java -jar target/exam-scheduler-1.0.0-jar-with-dependencies.jar
   

---

Usage

1. Import Data

1. Click Import Data in the navigation panel
2. Select your CSV files:
   • Students: List of student IDs (one per line)
   • Courses: List of course codes (one per line)
   • Classrooms: Format ClassroomID;Capacity (e.g., Room_01;40)
   • Enrollments: Student-course enrollment mappings
3. Click Import All and verify success

CSV Format Examples:

students.csv:

Std_ID_001
Std_ID_002
Std_ID_003

classrooms.csv:

Classroom_01;40
Classroom_02;35
Classroom_03;50

2. Configure Exam Period

1. Click Configure in the navigation panel
2. Set Number of Days (e.g., 5 days)
3. Set Time Slots Per Day (e.g., 4 slots)
4. Total available slots = Days × Slots (e.g., 5 × 4 = 20 slots)
5. Choose Optimization Strategy:
   • Minimize Days: Pack exams into fewest days
   • Balance Distribution: Spread exams evenly
   • Minimize Classrooms: Use fewest rooms
   • Balance Classrooms: Even room usage per day
6. Click Save Configuration

3. Generate Schedule

1. Click Generate in the navigation panel
2. Review configuration summary
3. Click Generate Schedule
4. Watch progress bar (cancellation available)
5. View success/failure result

If generation fails, view conflict report for:

• Students with too many courses
• Courses exceeding classroom capacity
• Recommendations to resolve conflicts

4. View Schedule

After successful generation, view schedule in 4 different formats:

• Classroom View: See which exams are in each classroom
• Student View: Search for a student's personal exam schedule
• Course View: See when each course exam is scheduled
• Day View: Visual grid of all exams by day and time slot

5. Export Schedule

1. Click Export in the navigation panel
2. Choose format: CSV or Excel
3. Select which views to export (can export all 4 views)
4. Choose destination folder
5. Click Export

Excel exports create a multi-sheet workbook with formatted tables ready for printing.

---

Project Structure

se302/
├── src/
│   ├── main/
│   │   ├── java/com/se302/examscheduler/
│   │   │   ├── model/              # Domain models (Student, Course, etc.)
│   │   │   ├── dao/                # Data Access Objects
│   │   │   ├── service/            # Business logic layer
│   │   │   ├── algorithm/          # CSP solver implementation
│   │   │   ├── controller/         # JavaFX controllers
│   │   │   ├── util/               # Utility classes
│   │   │   └── Main.java           # Application entry point
│   │   └── resources/
│   │       ├── fxml/               # JavaFX FXML layouts
│   │       ├── css/                # Stylesheets
│   │       ├── images/             # Icons and images
│   │       └── database/           # SQL schema
│   └── test/
│       └── java/com/se302/examscheduler/
│           ├── dao/                # DAO tests
│           ├── service/            # Service tests
│           ├── algorithm/          # Algorithm tests
│           └── integration/        # Integration tests
├── docs/                           # Documentation
│   ├── MEMORY_BANK.md             # Comprehensive project documentation
│   ├── ROADMAP.md                 # Development roadmap
│   ├── TEAM_ASSIGNMENTS.md        # Team roles and responsibilities
│   ├── GIT_WORKFLOW.md            # Git workflow guide
│   └── screenshots/               # Application screenshots
├── .github/
│   └── workflows/
│       └── ci.yml                 # GitHub Actions CI/CD
├── pom.xml                        # Maven configuration
├── .gitignore                     # Git ignore rules
└── README.md                      # This file

---

Development

Prerequisites for Development

• Java JDK 17+
• Maven 3.8+
• IDE: IntelliJ IDEA (recommended) or Eclipse
• Scene Builder (for FXML editing): Download
• Git

Setup Development Environment

1. Clone the repository:

   git clone https://github.com/sabazadam/se302.git
   cd se302
   

2. Import into IDE:

   • IntelliJ IDEA: File → Open → Select pom.xml
   • Eclipse: File → Import → Existing Maven Projects

3. Configure JDK 17:

   • IntelliJ: File → Project Structure → Project SDK → Select JDK 17
   • Eclipse: Right-click project → Properties → Java Build Path → JRE System Library

4. Build the project:

   mvn clean install
   

5. Run from IDE:

   • Main class: com.se302.examscheduler.Main
   • VM options: --module-path /path/to/javafx-sdk/lib --add-modules javafx.controls,javafx.fxml

Git Workflow

We follow a feature branch workflow with main and develop branches:

1. Create feature branch from develop:

   git checkout develop
   git pull origin develop
   git checkout -b feature/your-feature-name
   

2. Make changes and commit:

   git add .
   git commit -m "feat(scope): brief description"
   

3. Push and create Pull Request:

   git push origin feature/your-feature-name
   

4. After PR approval, merge to develop

5. Delete feature branch after merge

See GIT_WORKFLOW.md for detailed guidelines.

Coding Standards

• Java Naming Conventions: camelCase for variables/methods, PascalCase for classes
• JavaDoc: Required for all public methods
• Comments: Explain "why" not "what"
• Max line length: 120 characters
• Indentation: 4 spaces (no tabs)
• Formatting: Follow Java standard code style

---

Testing

Running Tests

# Run all tests
mvn test

# Run specific test class
mvn test -Dtest=StudentDAOTest

# Run with coverage report
mvn clean test jacoco:report

# View coverage report
open target/site/jacoco/index.html

Test Coverage Goals

• Overall: > 70% line coverage
• DAO Layer: > 90%
• Algorithm Layer: > 95%
• Service Layer: > 80%
• Controller Layer: > 70%

Continuous Integration

GitHub Actions automatically runs tests on every push and pull request:

• Compiles code
• Runs all tests
• Generates coverage report
• Uploads to Codecov

See .github/workflows/ci.yml for CI configuration.

---

Documentation

User Documentation

• User Manual (PDF): Comprehensive guide with screenshots (coming in Week 10)
• Installation Guide: See Installation section above
• Troubleshooting Guide: (coming soon)

Developer Documentation

• Memory Bank: MEMORY_BANK.md - Comprehensive project documentation including:
  • Requirements summary
  • Database schema
  • Architecture and design patterns
  • Algorithm design
  • API contracts
  • Testing strategy
• Roadmap: ROADMAP.md - Week-by-week development plan
• Team Assignments: TEAM_ASSIGNMENTS.md - Roles and responsibilities
• Git Workflow: GIT_WORKFLOW.md - Branching strategy and PR process
• JavaDoc: Generate with mvn javadoc:javadoc, view at target/site/apidocs/index.html

API Documentation

Generate JavaDoc:

mvn javadoc:javadoc
open target/site/apidocs/index.html

---

Team

SE302 - Software Engineering | Team 3, Section 1

Name	Student ID	Role
Kerem Bozdag	20200602012	Database & Data Layer Lead
Milena Larissa Ünal	20230602107	Algorithm Specialist
Rabia Tülay Gokdag	20210602029	UI/FXML Specialist
Mehmet Sefa Keskin	20230602047	Controller Layer Lead
Feyza Gereme	20230602028	Testing & QA Lead
Emin Arslan	20230602007	Documentation & Integration Lead

---

Technology Stack

• Language: Java 17
• UI Framework: JavaFX 21
• Database: SQLite 3.44
• Build Tool: Maven 3.8+
• Testing: JUnit 5, Mockito, TestFX
• Libraries:
  • Apache POI (Excel export)
  • Apache Commons CSV (CSV parsing)
  • SQLite JDBC
• CI/CD: GitHub Actions
• Code Coverage: JaCoCo

---

Architecture

The application follows the Model-View-Controller (MVC) architectural pattern:

• Model: Domain objects (Student, Course, Classroom, etc.) and business logic
• View: JavaFX FXML layouts and UI components
• Controller: JavaFX controllers handling user interactions

Key Design Patterns:

• DAO Pattern: Data access abstraction
• Strategy Pattern: Pluggable optimization strategies
• Singleton Pattern: Database connection management
• Observer Pattern: Progress tracking for long-running operations
• Factory Pattern: DAO instantiation

---

Algorithm

The scheduling algorithm uses Backtracking with Constraint Propagation:

1. Variables: Each course is a variable needing assignment
2. Domain: Each course can be assigned to {Classroom, Day, TimeSlot} triple
3. Constraints:
   • No consecutive exams for any student
   • Max 2 exams per student per day
   • Classroom capacity limits
4. Heuristics:
   • Variable ordering: Minimum Remaining Values (MRV)
   • Value ordering: Least Constraining Value
5. Optimization: Strategy-based heuristics affect value ordering

See MEMORY_BANK.md for detailed algorithm documentation.

---

Course Information

• Course: SE302 - Software Engineering
• Section: 1
• Team: 3
• Academic Year: 2025-2026 Fall Semester
• Project Start: November 26, 2025
• Final Delivery: February 4, 2026

---

License

This project is developed as part of SE302 Software Engineering course.

Academic Use Only - Not licensed for commercial use.

Copyright © 2025 Team 3, Section 1. All rights reserved.

---

Frequently Asked Questions

Q: What happens if no valid schedule exists?

A: The system will detect conflicts and provide a detailed report identifying:

• Students with too many courses for the available slots
• Courses with enrollment exceeding maximum classroom capacity
• Specific recommendations to resolve the issue (extend period, add classrooms, reduce enrollments)

Q: Can I run multiple schedules with different configurations?

A: Yes! The system saves schedule history with metadata (date, optimization strategy, configuration). You can generate multiple schedules and compare them.

Q: Can I edit a generated schedule manually?

A: Yes, but all edits are validated against constraints in real-time. If an edit would violate a constraint (e.g., create consecutive exams for a student), the system will reject it with a detailed explanation.

Q: How fast is the scheduling algorithm?

A: For the sample dataset (20 courses, 250 students, 10 classrooms), generation typically completes in < 5 seconds. Larger datasets (50 courses, 500 students) complete in < 10 seconds.

Q: Can I use this on macOS or Linux?

A: Yes! The application is built with Java and JavaFX, which are cross-platform. It works on Windows, macOS, and Linux.

---

Development Progress

Completed

• Requirements analysis and specification
• System design and architecture
• Database schema design
• Project structure and Maven setup
• Git workflow and CI/CD pipeline
• Comprehensive documentation (Memory Bank, Roadmap, Team Assignments)

In Progress (Week 1)

• Database layer implementation
• CSV import functionality
• Domain model classes
• UI wireframes and layouts

Planned

• CSP solver implementation
• Optimization strategies
• JavaFX UI views
• Export functionality
• Testing and quality assurance
• User manual and final documentation

See ROADMAP.md for detailed week-by-week plan.

---

Contact

For questions or issues related to this project:

• Create an issue on GitHub
• Contact team members (see Team section)
• Contact course instructor

---

Last Updated: November 26, 2025

For comprehensive project documentation, see MEMORY_BANK.md.