This project is a backend system for generating optimized university timetables. It handles scheduling constraints, conflict detection, and automatic timetable generation.
The goal of this project was to build a complex scheduling system that simulates real-world university constraints such as instructor availability, room capacity, and time slot conflicts.
- Java 21+
- Spring Boot
- Spring Data JPA (Hibernate)
- Spring Security
- JWT Authentication
- MySQL Database
- Maven
- Lombok
- MapStruct
- Swagger / OpenAPI
The project follows a clean layered architecture:
Controller → Service → Repository → Entity
Includes a scheduling engine responsible for generating optimized timetables based on constraints.
- Register / Login
- JWT-based authentication
- Role-based access (Admin / Instructor)
- Courses management
- Departments management
- Instructors management
- Rooms management
- Sections management
- Semesters management
- Create and manage time slots
- Define working days and hours
-
Generate schedule automatically
-
Assign:
- Instructor
- Room
- Time slot
-
Respect constraints:
- Instructor availability
- Room capacity
- Section conflicts
-
Detect scheduling conflicts
-
Return violations:
- Hard constraints
- Soft constraints
-
Export schedule as:
- Excel
- Schedule generation runs as a background job
- Track job status (RUNNING / COMPLETED)
- View structured weekly timetable
- Grouped by days and time slots
This diagram represents the relational database design including courses, instructors, rooms, schedules, constraints, and timetable entries.
All endpoints are prefixed with:
/api
- POST /schedules/generate/{semesterId}
- GET /schedules/jobs/{jobId}
- GET /schedules/{id}/conflicts
- GET /schedules/{id}/pdf
- GET /schedules/{id}/excel
- GET /weekly-schedules/{id}
- GET /instructor/schedule/my
- /courses
- /instructors
- /rooms
- /sections
- /semesters
- /timeslots
- POST /auth/register
- POST /auth/login
- Complex scheduling algorithm
- Constraint-based system design
- Conflict detection engine
- Async processing with job tracking
- Real-world academic system simulation
- Clean architecture and modular design
-
Clone the repository
-
Configure application.properties
spring.datasource.url=jdbc:mysql://localhost:3306/timetable_db
spring.datasource.username=your_user
spring.datasource.password=your_password
spring.jpa.hibernate.ddl-auto=update
auth.jwt.secret=YOUR_SECRET
auth.jwt.expiration=3600000- Run the project
mvn spring-boot:run- Open Swagger
http://localhost:8080/swagger-ui/index.html
This project helped me:
- Design complex scheduling systems
- Work with constraint-based logic
- Build scalable backend architecture
- Handle asynchronous processing
- Model real-world academic systems
Mahmoud Backend Developer (Spring Boot)