CITU Course Builder

Plan, Filter, and Optimize Your Class Schedules with Ease!

A modern web application that helps students at Cebu Institute of Technology - University (CIT-U) efficiently create optimal, conflict-free class schedules. It simplifies academic planning by providing smart import/export capabilities, intelligent scheduling algorithms, and a responsive visual interface.

Table of Contents

• Table of Contents
• About The Project
• Key Features
• Built With
• Getting Started
  • Prerequisites
  • Installation
• Usage
• Contributing
• License

About The Project

The CITU Course Builder is a completed, stable web application designed to assist students at Cebu Institute of Technology - University (and compatible institutions) in efficiently creating optimal, conflict-free class schedules. It simplifies academic planning by providing smart import/export capabilities, intelligent scheduling algorithms, and a responsive visual interface. The project has achieved all its goals including intuitive scheduling tools, reliable data persistence, and comprehensive export functionality.

Key Features

• 📚 Smart Data Import:
  • Paste tab-separated course data (e.g., from AIMS).
  • Intelligent parser handles common schedule formats, including multi-line AIMS entries.
• 📊 Dynamic Course Management:
  • View courses in a sortable, filterable table.
  • Group by subject, department, or view all.
  • Manage individual courses or clear all data.
• 🔒 Course Prioritization (Locking):
  • Lock essential course sections.
  • Immediate visual conflict highlighting for overlapping locked courses.
  • Confirmation prompts for conflict-inducing locks.
• ⚙️ Advanced Filtering:
  • Exclude courses by specific days or time ranges.
  • Filter by section type (Online, Face-to-Face, Hybrid).
  • Filter by course status (Open/Closed/All).
• 🛠️ Customizable User Preferences:
  • Set maximum total units.
  • Define maximum allowed break time between classes.
  • Drag-and-drop preferred time of day order (Morning, Afternoon, Evening, Any).
  • Minimize days on campus preference (excluding online classes).
  • All preferences and filters are saved automatically to localStorage.
• 🧠 Intelligent Schedule Generation:
  • Multiple search modes:
    • Recommended (Flexible, Best Fit): Maximizes subjects and units.
    • Full Coverage (All Subjects, Strict): Ensures all subjects fit.
    • Quick (Fast, May Miss Best): Rapidly finds a viable schedule.
  • Generated schedules respect all locked courses, filters, and preferences.
• 🗓️ Clear Timetable Visualization:
  • View locked courses in a weekly timetable (7 AM - 10 PM).
  • Responsive design adapts to various screen sizes.
  • Toggle between full timetable and summary view.
• 📤 Comprehensive Export Options:
  • Course List: Copy to clipboard or download as .txt (tab-separated format for re-import).
  • Timetable View: Export as a PNG image or a PDF document.
  • iCalendar Export: Generate .ics file for easy import to Google Calendar, Outlook, or Apple Calendar.
• 🎨 Modern & Responsive UI/UX:
  • Light and Dark mode themes with instant switching and automatic palette pairing
  • 'Original' and 'Comfort' color palettes with improved text contrast and element visibility
  • Palette persistence between sessions for consistent theming
  • Built with accessibility and mobile-friendliness in mind

Built With

This project leverages a modern frontend stack:

• React - A JavaScript library for building user interfaces.
• Vite - Next Generation Frontend Tooling.
• Material-UI (MUI) - React UI framework for faster and easier web development.
• React Toastify - For notifications.
• React Datepicker - For time selection.
• html-to-image - For capturing HTML to image (PNG export).
• jsPDF - For generating PDFs (Timetable PDF export).
• CSS with CSS Variables - For theming and styling.
• Browser localStorage - For client-side data persistence.

---

Getting Started

To get a local copy up and running, follow these simple steps.

Prerequisites

Ensure you have Node.js and npm (or yarn) installed on your system.

• Node.js (v14+ recommended)
• npm

  npm install npm@latest -g

  or yarn

  npm install --global yarn

Installation

1. Clone the repo:

   git clone https://github.com/MasuRii/CITUCourseBuilder.git

2. Navigate to the project directory:

   cd CITUCourseBuilder/course-scheduler-web

3. Install NPM packages:

   npm install

   or if using yarn:

   yarn install

4. Run the development server:

   npm run dev

   or if using yarn:

   yarn dev

The application will typically be available at http://localhost:12000.

Usage

Once the application is running:

1. Import Data: Navigate to your institution's portal (e.g., AIMS for CIT-U students), copy the table of available courses. Paste this tab-separated data into the "Raw Data Input" text area in the CITU Course Builder and click "Import Data."
2. Manage Courses: View your imported courses in the table. You can sort, group, and delete courses.
3. Set Preferences & Filters: Configure your maximum units, preferred class gap, preferred time of day, and apply filters like day/time exclusions, section types, or course status.
4. Lock Courses: Lock any specific course sections you absolutely need in your schedule. Conflicts with other locked courses will be highlighted.
5. Generate Schedule: Choose a schedule generation mode ("Recommended," "Full Coverage," or "Quick") and click "Generate Best Schedule." The application will attempt to find an optimal, conflict-free schedule based on your settings.
6. View Timetable: Locked courses (either manually locked or from a generated schedule) will appear in the weekly timetable.
7. Export: Use the hamburger menus in the course list and timetable sections to:
   • Export course data as .txt or to clipboard (tab-separated format for re-import)
   • Export timetable view as high-fidelity PNG or PDF files
   • Export timetable as iCalendar (.ics) file for calendar applications
8. Customize Theme: Switch between Light/Dark modes and choose between 'Original'/'Comfort' color palettes. The system remembers your palette choices between sessions.

All your settings, imported courses, and locked courses are automatically saved in your browser's local storage, so you can close the tab and resume later.

Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Please make sure to update tests as appropriate.

License

Distributed under the MIT License. See LICENSE for more information.