CSIS Department Lab Timetable System

A centralized digital platform for lab scheduling, room management, and availability tracking for the CSIS department at UL.

Features

For Students (No Login Required)

• View live lab availability
• Search modules and courses
• Search rooms and check availability
• View overall timetable

For Staff/Lecturers (Login Required)

• Request lab bookings
• View departmental schedule
• Manage their sessions
• Request to be set as lecturer for a module
• Request signup with @ul.ie email (requires admin approval)

For Administrators (Login Required)

• Approve, reject, change, or delete class bookings
• Approve user sign-ups
• Manage users and roles
• View audit logs of all changes
• Add students to modules
• Manage booking conflicts
• Full system access

Tech Stack

Backend

• Spring Boot 3.2.0 - Java framework
• MySQL - Database
• JWT - Authentication
• Spring Security - Security framework
• Spring Data JPA - Data persistence
• WebSocket - Real-time updates (optional)

Frontend

• React 18 - UI library
• TypeScript - Type safety
• Tailwind CSS - Styling
• React Query - Server state management
• React Router - Navigation
• Vite - Build tool

Quick Start

Prerequisites

• Java 21
• Node.js 20+
• MySQL 8.0+
• Maven 3.9+

Local Development

1. Database Setup

# Start MySQL (or use Docker)
docker run -d \
  --name timetable_mysql \
  -e MYSQL_ROOT_PASSWORD=rootpassword \
  -e MYSQL_DATABASE=timetable_db \
  -p 3306:3306 \
  mysql:8.0

2. Backend Setup

# Navigate to project root
cd TimetableSystem_Group8

# Update application.properties with your MySQL credentials if needed
# Default: root/rootpassword

# Run the Spring Boot application
mvn spring-boot:run

# Backend will be available at http://localhost:8080

3. Frontend Setup

# Navigate to frontend directory
cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

# Frontend will be available at http://localhost:3000

Docker Setup (Recommended)

# Build and start all services
# Note: Use 'docker compose' (space) for Docker Desktop, or 'docker-compose' (hyphen) for standalone
docker compose up -d
# OR: docker-compose up -d

# View logs
docker compose logs -f
# OR: docker-compose logs -f

# Stop services
docker compose down
# OR: docker-compose down

Services will be available at:

• Frontend: http://localhost:3000
• Backend: http://localhost:8080
• MySQL: localhost:3306

<<<<<<< HEAD

Project Structure

TimetableSystem_Group8/
├── src/
│   └── main/
│       ├── java/ie/ul/csis/timetable/
│       │   ├── model/          # Entity models (User, Lab, Booking, etc.)
│       │   ├── repository/     # Data access layer
│       │   ├── service/        # Business logic
│       │   ├── controller/     # REST API endpoints
│       │   ├── config/         # Configuration classes
│       │   ├── security/       # Security configuration
│       │   └── dto/            # Data transfer objects
│       └── resources/
│           └── application.properties
├── frontend/
│   ├── src/
│   │   ├── components/         # React components
│   │   ├── pages/              # Page components
│   │   ├── contexts/           # React contexts
│   │   ├── services/           # API services
│   │   └── App.tsx
│   └── package.json
├── docker-compose.yml
├── Dockerfile.backend
└── pom.xml

API Endpoints

Authentication

• POST /api/auth/login - User login
• POST /api/auth/register - User registration

Labs

• GET /api/labs - Get all labs
• GET /api/labs/{id} - Get lab by ID
• GET /api/labs/{id}/availability - Get lab availability
• GET /api/labs/available - Find available labs

Bookings

• POST /api/bookings - Create booking request (requires auth)
• GET /api/bookings/my-bookings - Get user's bookings (requires auth)
• GET /api/bookings/pending - Get pending bookings
• POST /api/bookings/{id}/approve - Approve booking (admin only)
• POST /api/bookings/{id}/reject - Reject booking (admin only)

Database Schema

Key Entities

• User - Users (students, staff, admins)
• Lab - Lab rooms with capacity and equipment
• Module - Course modules
• Booking - Lab booking requests and approvals
• AuditLog - System change logs
• Notification - User notifications

Configuration

Backend Configuration (application.properties)

# Database
spring.datasource.url=jdbc:mysql://localhost:3306/timetable_db
spring.datasource.username=root
spring.datasource.password=rootpassword

# JWT
jwt.secret=your-secret-key-change-this-in-production
jwt.expiration=86400000

Frontend Configuration

The frontend is configured to proxy API requests to http://localhost:8080 (see vite.config.ts).

Development Tips

1. First Admin User: You'll need to manually create the first admin user in the database or add a data initialization script.

2. UL Timetable Integration: The system is designed to import from UL's central timetable. You'll need to implement the integration based on UL's API.

3. Email Notifications: Configure email settings in application.properties if you want to enable email notifications (requires SMTP configuration).

4. Testing:

   • Backend: mvn test
   • Frontend: Add testing framework as needed

Next Steps

1. UL Timetable Sync: Implement API integration to sync with UL's central timetable
2. Recurring Bookings: Complete the recurring booking pattern implementation
3. Email Notifications: Set up email service for booking confirmations
4. Real-time Updates: Implement WebSocket for live availability updates
5. Reporting: Add analytics and reporting features
6. Mobile App: Consider React Native for native mobile experience

License

MIT License - See LICENSE file for details

Contributors

Group 8 - CSIS Department Lab Timetable System Hackathon Project

Updating

If any of the files in this repo are updated down the line, such as .gitignore/.gitattributes/.forgejo/workflows/check_lfs.yaml then it is recommended to backport the changes here.

pom.xml (Maven Project Configuration) Location: src/backend/pom.xml The Project Object Model (POM) file is Maven's core configuration file. It defines:

Project metadata: Group ID, artifact ID, version, and name Dependencies: External libraries the project needs (Spring Boot, MySQL driver, Redis, JWT, etc.) Build configuration: How to compile, test, and package the application Plugin configuration: Maven plugins for building and running the application

Key sections:

: Inherits from Spring Boot starter parent for version management : Project-wide settings (Java version 21) : All required libraries with automatic version resolution : Compilation and packaging instructions

Maven automatically downloads all dependencies from central repositories, manages transitive dependencies, and handles the build lifecycle. Running mvn clean package compiles the code and creates an executable JAR file. application.yml (Spring Boot Application Configuration) Location: src/backend/src/main/resources/application.yml This YAML file is the central configuration for the Spring Boot application runtime. It tells Spring Boot how to connect to services and configure application behavior. Key configuration sections:

Database (spring.datasource):

MySQL connection URL, credentials, and driver ?createDatabaseIfNotExist=true automatically creates the database on first run

JPA/Hibernate (spring.jpa):

ddl-auto: update - Automatically creates/updates database tables from Java entity classes show-sql: true - Logs all SQL queries for debugging

Redis (spring.data.redis):

Cache server connection for high-performance data access Used for frequently accessed data like lab availability

Server (server.port):

Application runs on port 8080 (http://localhost:8080)

JWT Security (jwt):

Secret key for signing authentication tokens Token expiration time (24 hours)

Custom Settings (app):

Domain validation for UL email addresses (ul.ie)

Spring Boot reads this file at startup and configures all beans and connections accordingly. Different profiles (dev, prod) can have separate configuration files (application-dev.yml, application-prod.yml). docker-compose.yml (Multi-Container Orchestration) Location: src/backend/docker-compose.yml Docker Compose defines and runs multi-container Docker applications. This file describes the entire application stack and how services connect. Defined services:

mysql:

MySQL 8.0 database server Creates timetable_db database with credentials Port 3306 exposed for connections Persistent volume (mysql_data) so data survives container restarts Health check ensures MySQL is ready before dependent services start

redis:

Redis 7 in-memory cache Port 6379 for high-speed data access Alpine Linux base (smaller image size) Health check verifies Redis connectivity

app:

Your Spring Boot application Built from Dockerfile in current directory Waits for MySQL and Redis to be healthy (depends_on) Environment variables override application.yml for container networking Port 8080 exposed for API access

Networking:

All services connected via timetable-network bridge network Services can reference each other by name (mysql, redis) Isolated from host network for security

Usage: bash# Start all services docker-compose up

Start in background

docker-compose up -d

Stop all services

docker-compose down

Reset everything (including data)

docker-compose down -v Benefits: Ensures identical environments across development, testing, and production. Eliminates "works on my machine" issues. Dockerfile (Application Container Image) Location: src/backend/Dockerfile A Dockerfile contains instructions to build a Docker image of your Spring Boot application. This uses a multi-stage build for efficiency. Stage 1 - Build (AS build):

Base: eclipse-temurin:21-jdk-alpine (Java 21 JDK on lightweight Alpine Linux) Installs Maven build tool Copies pom.xml and source code Runs mvn clean package to compile Java code into executable JAR Result: target/timetable-system-1.0.0.jar

Stage 2 - Runtime:

Base: eclipse-temurin:21-jre-alpine (Java 21 JRE only - smaller image) Copies only the JAR file from build stage Discards build tools (Maven, JDK) to reduce final image size Exposes port 8080 Runs JAR on container startup: java -jar app.jar

Benefits of multi-stage builds:

Security: Production image contains only runtime components Size: Final image ~150MB vs ~500MB with build tools Speed: Smaller images deploy faster

The image created can run identically on any machine with Docker installed, ensuring consistency from development laptops to production servers.

f0e38d4461