Queuesis — CUHK Timetable Planner

A modern course-queueing experience built to fix everything CUSIS didn’t.

🎥 Video Showcase

Queuesis.Showcase.Video.mp4

📸 Interface

🚀 Interactive Features

Feature	Preview
🔍 Instant Search Real-time filtering allows you to find and add courses to your planning list instantly.
🖱️ Drag & Drop Fully interactive interface. Easily move courses around; snap-to-grid ensures valid scheduling.
🤖 Smart Auto-Plan One-click algorithm that generates the optimal schedule based on your course list.

🛠️ Controls & Utilities

Feature	Preview
🔒 Feature Lock Pin courses in place to prevent the auto-planner from moving them during regeneration.
📤 Export & Reset Export to `.ics` / Image, or perform a bulk delete to reset your workspace.

📖 Table of Contents

Overview
Key Features
Technology Stack
Project Structure
Getting Started
Configuration
Data Management
API Documentation
Testing
Deployment
Troubleshooting
Roadmap
Contributing
Team
Acknowledgments
License

🎯 Overview

Queuesis is a CUHK-focused timetable planner that combines intuitive drag-and-drop editing with a powerful deterministic schedule generator. Course data is sourced from CUSIS and can optionally be synced to MongoDB Atlas via Prisma for enhanced performance.

📅 Current Term Support: This version currently supports 2025-2026 Term 2 course data. Support for additional terms will be added in future updates.

Why Queuesis?

Smart Scheduling: Deterministic algorithm with 6 preference modes
Real-time Validation: Instant conflict detection as you build your schedule
Flexible Data: Works with or without a database connection
Modern Stack: Built with Next.js 16, React 19, and TypeScript

✨ Key Features

📅 Intelligent Scheduling

Choose from multiple optimization preferences:

⚡ Short Breaks — Minimize downtime between classes
☕ Long Breaks — Maximize lunch/study gaps (≥60 minutes)
🎯 Consistent Times — Align start times throughout the week
🌅 Start Late — Push classes later in the day
🌆 End Early — Finish your day as early as possible
🗓️ Days Off — Pack sections into fewer days for free weekdays

🛡️ Smart Conflict Detection

Automatic time overlap detection
Visual conflict indicators
Real-time validation when adding courses
Clear error messages with helpful suggestions

🎨 Modern User Experience

Clean, CUHK-themed purple interface
Responsive design for desktop and mobile
Dark mode support
Smooth animations and glass morphism effects
Intuitive drag-and-drop interface

🔍 Advanced Search & Filtering

Search by course code, name, or instructor
Filter by term and department
Browse multiple generated schedules
One-click schedule clearing

🔒 Lock & Constraints

Lock any section (LEC/TUT/LAB) to freeze it on the timetable; locked blocks
- show a small lock icon next to the section label,
- are grey‑tinted with a white border,
- cannot be dragged, swapped, or removed.
Lock All / Unlock All for a course in “My Schedule” (locks both Lecture and its dependent Tutorial/Lab).
Auto‑Generate respects locks as hard constraints:
- The generator automatically includes locked courses even if not selected in chips,
- and only considers the locked section ids for those courses.
- Day‑Off and other preferences still apply to unlocked courses around your locks.

🚀 Getting Started

Choose Your Path

🌐 Use Online

Just want to plan your schedule?

No installation needed!

💻 Run Locally

Want to develop or customize?

Follow our guide below!

🚀 Technology Stack

Frontend

Framework: Next.js 16 (App Router)
UI Library: React 19
Language: TypeScript 5
Styling: Tailwind CSS 4
Theme: next-themes
Icons: Lucide React
Drag & Drop: @dnd-kit
Deployment: Vercel

Backend & Data

Runtime: Node.js (Vercel)
API: Next.js Route Handlers
Database: MongoDB Atlas
ORM: Prisma 6
Data Processing: xlsx
Testing: Jest 30.x
Linting: ESLint 9.x

Architecture Highlights

┌─────────────┐
│   Browser   │
└──────┬──────┘
       │ HTTPS
       ▼
┌─────────────────────────────┐
│  Next.js (Vercel)           │
│  ┌─────────────────────┐    │
│  │  React UI (Client)  │    │
│  └──────────┬──────────┘    │
│             │               │
│  ┌──────────▼──────────┐    │
│  │  API Routes (Server)│    │
│  │  - /api/health      │    │
│  │  - /api/terms       │    │
│  │  - /api/courses     │    │
│  └──────────┬──────────┘    │
└─────────────┼───────────────┘
              │ Prisma
              ▼
     ┌────────────────┐
     │ MongoDB Atlas  │
     │   (Optional)   │
     └────────────────┘
              │
     Fallback: JSON/Mock

📂 Project Structure

cuhk-scheduler/
├── 📄 Core Files
│   ├── README.md
│   ├── LICENSE (AGPL v3)
│   ├── package.json
│   └── tsconfig.json
│
├── 📚 Documentation
│   └── docs/
│       ├── API.md                    # API endpoint documentation
│       └── manual-data-entry.md      # Data management guide
│
├── 🗄️ Database
│   └── prisma/
│       ├── schema.prisma             # MongoDB models
│       └── seed.ts                   # Database seeding script
│
├── 🛠️ Scripts
│   └── scripts/
│       ├── convert-excel.ts          # Excel → JSON converter
│       └── import-json.ts            # JSON → MongoDB importer
│
├── 💾 Data
│   └── data/
│       └── courses-2025-26-T2.json   # Fallback course dataset
│
└── 💻 Source Code
    └── src/
        ├── app/                      # Next.js App Router
        │   ├── page.tsx              # Main timetable page
        │   ├── layout.tsx            # Root layout with theme
        │   ├── globals.css           # Global styles
        │   └── api/                  # API Routes
        │       ├── health/           # Health check endpoint
        │       ├── terms/            # Terms listing
        │       └── courses/          # Course data endpoints
        │
        ├── components/               # React UI Components
        │   ├── TimetableGrid.tsx     # Main timetable display
        │   ├── CourseCard.tsx        # Course selection cards
        │   ├── SearchBar.tsx         # Course search interface
        │   ├── ConflictToast.tsx     # Conflict notifications
        │   └── ThemeToggle.tsx       # Dark mode toggle
        │
        ├── lib/                      # Core Logic
        │   ├── schedule-generator.ts # Algorithm engine
        │   ├── schedule-utils.ts     # Conflict detection
        │   ├── db.ts                 # Prisma client
        │   └── __tests__/            # Unit tests
        │
        ├── data/                     # Static Data
        │   ├── generated-courses.ts  # Generated JSON loader
        │   └── mock-courses.ts       # Development mocks
        │
        └── types/                    # TypeScript Definitions
            └── index.ts              # Shared type definitions

🏁 Getting Started

Prerequisites

Node.js 18 or higher
npm or yarn
MongoDB Atlas account (optional)

Installation

Clone the repository

git clone https://github.com/Aplkalex/Queuesis.git
cd Queuesis

Install dependencies

npm install

Set up environment variables

cp .env.local.example .env.local

Edit .env.local with your configuration (see Configuration below).

Run the development server

npm run dev

Open your browser

Navigate to http://localhost:3000

⚙️ Configuration

Create a .env.local file with the following variables:

# MongoDB Connection (optional)
MONGODB_URI=mongodb+srv://<username>:<password>@cluster.mongodb.net/queuesis

# Fallback Data Settings
ALLOW_FALLBACK_DATA=true

# Custom JSON Data Path (optional)
GENERATED_COURSES_PATH=data/<name>

# UI Feature Flags (safe to expose)
# Show the "Test Mode" toggle/banner in the UI (useful for local dev/QA).
NEXT_PUBLIC_ENABLE_TEST_MODE=false

Environment Variable Details

Variable	Required	Description
`MONGODB_URI`	No	MongoDB Atlas connection string. If not provided, app uses JSON/mock data
`ALLOW_FALLBACK_DATA`	No	Set to `false` to enforce database-only mode (default: `true`)
`GENERATED_COURSES_PATH`	No	Path to custom course JSON file
`NEXT_PUBLIC_ENABLE_TEST_MODE`	No	When `true`, shows the Test Mode toggle and banner in the UI

📊 Data Management

Data Source Hierarchy

The app follows this priority order for retrieving course data:

1️⃣ MongoDB Atlas (if MONGODB_URI configured)
        ↓ (if unavailable)
2️⃣ Generated JSON (from GENERATED_COURSES_PATH)
        ↓ (if unavailable)
3️⃣ Static Mock Data (development fallback)

Working with Course Data

📥 Converting Excel to JSON

npm run convert-excel -- \
  --input "<Your_excel_document>.xlsx" \
  --output data/<name>.json

Options:

--input - Path to CUSIS Excel export
--output - Destination JSON file
--sheet - Specific worksheet name (if needed)

📤 Importing to MongoDB

npm run import-json -- --file data/<name>.json

Prerequisites:

MongoDB Atlas cluster set up
MONGODB_URI configured in .env.local
Network access configured in Atlas

🗂️ Data Model

Course Schema:

{
  courseCode: string        // Unique identifier (e.g., "CSCI1001")
  courseName: string        // Full course name
  department: string        // Department code
  credits: number          // Credit hours
  description?: string     // Course description
  prerequisites?: string   // Prerequisite requirements
  sections: Section[]      // Array of class sections
  term: string            // Academic term
  career: string          // Program level
  lastUpdated: Date       // Last sync timestamp
}

Indexes:

courseCode (unique)
term (indexed for fast filtering)
department (indexed for department queries)

🔌 API Documentation

Endpoints

Endpoint	Method	Description
`/api/health`	GET	Health check
`/api/terms`	GET	List available terms
`/api/courses`	GET	List/filter courses
`/api/courses/[code]`	GET	Get single course details

Query Parameters

/api/courses:

term — Filter by academic term
department — Filter by department code
search — Search course code/name/instructor
testMode — Use mock data (development only)

Example:

GET /api/courses?term=2025-26-T2&department=CSCI&search=data

For full API documentation, see docs/API.md.

🧪 Testing

Running Tests

# Run all tests
npm test

# Watch mode (re-run on file changes)
npm run test:watch

# Generate coverage report
npm run test:coverage

Test Coverage

Our test suite includes:

Category	Coverage	Details
Scheduling Algorithm	Comprehensive	All preference modes, edge cases
Conflict Detection	Comprehensive	Time overlaps, section conflicts
Course Selection	Comprehensive	Adding/removing courses
Component Behavior	Partial	Critical UI components
API Routes	Planned	Endpoint testing

Test Files

src/lib/__tests__/schedule-generator.test.ts - Core algorithm
src/lib/__tests__/course-selection.test.ts - Selection logic
src/lib/__tests__/competitor-parity.test.ts - Feature parity

Adding Tests

When contributing new features:

Add unit tests for core logic in src/lib/__tests__/
Add component tests for UI changes
Ensure all existing tests pass
Aim for >80% code coverage on new code

🚢 Deployment

Note: This project is already deployed on Vercel. The following instructions are for reference or if you wish to deploy your own instance.

Deploy to Vercel (Optional)

Fork this repository
Import your fork into Vercel
Configure environment variables in Vercel dashboard
Deploy!

Environment Variables (Production)

Set these in Vercel → Project → Settings → Environment Variables:

MONGODB_URI — Your MongoDB Atlas connection string
ALLOW_FALLBACK_DATA — Set to false after seeding database
GENERATED_COURSES_PATH — (optional) Custom JSON path

Verification Checklist

After deployment, verify:

/api/health returns healthy status
/api/terms lists available terms
/api/courses?term=2025-26-T2 returns course data
Main page loads without errors

🛠️ Troubleshooting

No Data Returned

Problem: API endpoints return empty arrays

Solutions:

Verify MONGODB_URI is correct and accessible
Check that GENERATED_COURSES_PATH points to an existing JSON file
Ensure ALLOW_FALLBACK_DATA=true during initial setup
Review Vercel logs for connection errors

Excel Conversion Errors

Problem: convert-excel.ts fails or produces invalid JSON

Solutions:

Verify Excel file format matches expected CUSIS export structure
Use --sheet flag to specify correct worksheet name
Check that all required columns are present
See scripts/convert-excel.ts for column mapping details

Prisma/MongoDB Issues on Vercel

Problem: Database connections fail in production

Solutions:

Confirm environment variables are set in correct Vercel environment
Check MongoDB Atlas IP allowlist includes 0.0.0.0/0 for serverless
Verify database user has readWrite permissions
Review Vercel function logs for detailed error messages

Security Concerns

Problem: Connection string exposed or compromised

Actions:

Rotate MongoDB credentials immediately in Atlas
Update MONGODB_URI in Vercel environment variables
Review access logs in MongoDB Atlas
Ensure .env.local is in .gitignore

🗺️ Roadmap

Export Features
- Export timetable as PNG/PDF
- Generate ICS calendar files
- Google Calendar integration
Data Automation
- GitHub Actions for scheduled data updates
- Automated Excel → JSON → MongoDB pipeline
- Term detection and validation
Performance Improvements
- Database-backed text search with indexes
- Server-side pagination for large course lists
- API response caching
User Experience
- Mobile drag-and-drop enhancements
- Keyboard navigation and ARIA improvements
- Interactive onboarding tutorial
Intelligence Features
- ML-based schedule recommendations
- Optimal path planning for degree requirements
User Accounts & Persistence
- Share schedules via unique URLs
- Schedule history and versioning
Advanced Search
- Filter by instructor
- Filter by building/room
- Filter by time preferences
Mobile App
- Native iOS/Android apps
- Push notifications for course changes
- Offline mode support

💡 Community Suggestions

Have an idea or bug report? Either email queuesis@aplkalex.com or open a new GitHub issue at Queuesis Issues so we can tackle it quickly.

🤝 Contributing

We welcome contributions! Here's how to get started:

Quick Start

Fork the repository

Clone your fork

git clone https://github.com/YOUR_USERNAME/cuhk-scheduler.git
cd cuhk-scheduler

Create a feature branch
```
git checkout -b feature/amazing-feature
```
Make your changes and test thoroughly
Commit your changes
```
git commit -m 'Add amazing feature'
```
Push to your branch
```
git push origin feature/amazing-feature
```
Open a Pull Request

Development Guidelines

Follow existing code style and conventions
Write tests for new features
Update documentation as needed
Keep commits atomic and well-described
Ensure all tests pass before submitting PR

Areas We Need Help With

🐛 Bug fixes and issue resolution
📝 Documentation improvements
🎨 UI/UX enhancements
⚡ Performance optimizations
🧪 Test coverage expansion
🌐 Internationalization support

👥 Team

Lead/Maintainer: Aplkalex

Contributors: Open to community contributions! See Contributing section.

🙏 Acknowledgments

Built for CUHK students, by CUHK students
Inspired by university scheduling tools worldwide, particularly UBC Scheduler
Special thanks to all contributors and testers

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

Name		Name	Last commit message	Last commit date
Latest commit History 171 Commits
.playwright-profile		.playwright-profile
data		data
docs		docs
prisma		prisma
public		public
scripts		scripts
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
jest.config.js		jest.config.js
jest.setup.js		jest.setup.js
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json
tsconfig.seed.json		tsconfig.seed.json

License

Aplkalex/Queuesis

Folders and files

Latest commit

History

Repository files navigation

Queuesis — CUHK Timetable Planner

🎥 Video Showcase

📸 Interface

🚀 Interactive Features

🛠️ Controls & Utilities

📖 Table of Contents

🎯 Overview

Why Queuesis?

✨ Key Features

📅 Intelligent Scheduling

🛡️ Smart Conflict Detection

🎨 Modern User Experience

🔍 Advanced Search & Filtering

🔒 Lock & Constraints

🚀 Getting Started

Choose Your Path

🌐 Use Online

💻 Run Locally

🚀 Technology Stack

Frontend

Backend & Data

Architecture Highlights

📂 Project Structure

🏁 Getting Started

Prerequisites

Installation

⚙️ Configuration

Environment Variable Details

📊 Data Management

Data Source Hierarchy

Working with Course Data

🔌 API Documentation

Endpoints

Query Parameters

🧪 Testing

Running Tests

Test Coverage

Test Files

Adding Tests

🚢 Deployment

Deploy to Vercel (Optional)

Environment Variables (Production)

Verification Checklist

🛠️ Troubleshooting

No Data Returned

Excel Conversion Errors

Prisma/MongoDB Issues on Vercel

Security Concerns

🗺️ Roadmap

💡 Community Suggestions

🤝 Contributing

Quick Start

Development Guidelines

Areas We Need Help With

👥 Team

🙏 Acknowledgments

📄 License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Packages