Skip to content

About

The timetable portal for USAS students to manage, view, and export their class schedules.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

88 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

USAS Class Timetable

CI React TypeScript Vite Tailwind PWA License

USAS Logo

Try it live | Video tutorial on YouTube

USAS Class Timetable is a modern, client-side academic schedule portal designed for Universiti Sultan Azlan Shah (USAS) students. Built on React 18, TypeScript, and Vite with custom glassmorphism styling, it enables students to fetch, view, and export their class timetables directly into standard calendar feeds (.ICS), official A4 printable PDF documents, and high-resolution device lockscreen wallpapers.

Important

Unofficial project. USAS Class Timetable is an independent student project by STEM USAS. It is not affiliated with, endorsed by, or operated by Universiti Sultan Azlan Shah (USAS) and is not the official USAS portal. Login credentials are sent straight to the official USAS UMC API through a stateless proxy; this project does not store them.

Note

Student login requests pass through a stateless Cloudflare Pages Function before reaching the official USAS UMC API. The app does not keep a project database, but the browser stores the session for the current tab and a timetable cache on the device. See the Privacy Notice for data flow and storage details.

Core Features & Capabilities

USAS Class Timetable feature overview

  • University API Integration: Connects to official USAS UMC portal endpoints through the Cloudflare Pages Function proxy.
  • Document & Wallpaper Exports:
    • Print-Ready A4 PDF & PNG: High-resolution landscape documents formatted with student matric identity, course codes, locations, and timestamps.
    • Device Lockscreen Wallpapers: Tailored presets for Phone (9:20, default), Small Phone (9:16), Tablet (4:3), Desktop (16:9), and Square (1:1), with three layouts (Grid, Minimal, Liquid Glass), vertical clock offset adjustment, an optional custom background image with adjustable blur, and 5 color themes.
  • Live Schedule Tracking:
    • Live Next Class Card: Real-time widget highlighting the current ongoing lecture or countdown timer to the next session, with distinct day-status messages for days that have no sessions scheduled ("No classes on ...") versus days whose sessions have all finished ("Today's Classes Completed").
    • Clash Detection: Automated detection and warning flags for overlapping course hours.
    • Attendance Meter: Visual percentage tracker monitoring course attendance thresholds against the 80% bar risk limit.
    • GPA Target Calculator: Interactive tool for simulating semester GPA and cumulative CGPA goals.
    • Lecturer Directory Lookup: Tap a lecturer to load their official e-mail, position and extension from the USAS staff directory.
  • Calendar Sync & Social Sharing:
    • Universal .ICS Export: One-click calendar sync compatible with Google Calendar, Apple iCal, and Microsoft Outlook.
    • WhatsApp & QR Share: Share timetable text or QR codes; tap a QR for a fullscreen view to show a friend, and scan or upload a QR to compare schedules or submit attendance. Share QRs are always rendered dark-on-light so they scan reliably on any device.
  • Multi-Language & Theme Support:
    • 4 Supported Languages: English (Default), Bahasa Melayu, Simplified Chinese (简体中文), and Tamil (தமிழ்).
    • 5 Color Themes: Dark Theme (Default), Light Theme, OLED Pure Black, Islamic Emerald Green, and Warm Amber.
  • Landing Experience & PWA:
    • Interactive Landing Page: Hero area, 3D tilt timetable mockup and a bento feature grid, with an embedded video tutorial walkthrough player (custom play/pause, seek, mute and fullscreen controls).
    • Installable PWA: Add to home screen from the in-app install prompt, with a standalone offline service worker.

Secure by Design

Because the portal processes student academic schedules, security and privacy are implemented at every layer:

  • Stateless API Proxy: Requests pass through a Cloudflare Pages Function to https://mobile.usas.edu.my. The app code does not write credentials or sessions to a project database or function logs.
  • Stateless API Proxy & Anti-Bot: Login and API requests pass through a Cloudflare Pages Function that enforces an endpoint allowlist and request-size limits. Login is protected by a self-hosted ALTCHA proof-of-work challenge (no third party, works on iOS/Safari).
  • Content Security Policy (CSP): Restricts script, frame, and connection sources to reduce injection and framing risks.
  • Browser Storage: The session is kept in sessionStorage; the timetable cache and preferences use localStorage. These remain on the device until logout or browser storage is cleared. See the Privacy Notice.

Tech Stack

Frontend

Document & Media Engines

Backend & Hosting

Testing & Quality Assurance

Monitoring

  • Sentry (optional client error tracking)

Getting Started

Detailed Setup Guide: For comprehensive environment configuration, proxy setups, and production deployments, see our Installation Guide.

Follow these quick steps to get a local development copy running.

Prerequisites

  • Node.js >= 18.x (v20+ recommended)
  • NPM >= 9.x (or pnpm / yarn)

Installation

  1. Clone the repository

    git clone https://github.com/zis3c/USAS-Class-Timetable.git
    cd "USAS Class Timetable"
  2. Install dependencies

    npm install
  3. Start development server

    npm run dev

    Real API login: npm run dev serves the UI (and demo mode) only. The /api/usas proxy is a Cloudflare Pages Function. For local API login, run npx wrangler dev --config cloudflare/altcha-replay-guard/wrangler.toml in one terminal, then npm run dev:cf in another.

  4. Run unit tests and type checks

    npm run typecheck
    npm run test:unit

Project Structure

USAS Class Timetable/
├── .github/
│   └── workflows/
│       ├── ci.yml             # GitHub Actions CI workflow (lint, typecheck, unit, e2e)
│       ├── deploy.yml         # Cloudflare Pages deployment workflow
│       └── api-schema-check.yml # Scheduled USAS API schema monitor
├── docs/                      # Installation, architecture, API reference & policies
├── public/
│   ├── 404.html               # Branded standalone 404 error page
│   ├── 500.html               # Branded standalone 500 error page
│   ├── 502.html               # Branded standalone 502 error page
│   ├── 503.html               # Branded standalone 503 error page
│   ├── 504.html               # Branded standalone 504 error page
│   ├── _headers               # Cloudflare Pages security & cache headers
│   ├── error.css              # Glassmorphic error pages stylesheet
│   ├── error-page.js          # Error page hydration script
│   ├── sw.js                  # PWA offline service worker
│   ├── videos/                # Landing page tutorial media (usas-timetable-guide.mp4)
│   ├── usas-logo-dark.png     # Dark theme logo
│   ├── usas-logo-light.png    # Light theme logo
│   └── usas-logo.png          # Dark theme compatibility asset
├── functions/
│   └── api/usas/
│       └── _middleware.ts     # Cloudflare Pages Function proxy to the USAS API (endpoint allowlist)
├── src/
│   ├── app/
│   │   ├── main.tsx           # Application entrypoint
│   │   ├── App.tsx            # Main shell, routing & SEO metadata
│   │   ├── providers/         # Auth, Language & Theme state providers
│   │   └── shell/             # Navbar, ToolsDrawer, ErrorBoundary
│   ├── features/
│   │   ├── auth/              # Login form, LoginPage
│   │   ├── export/            # PdfExportModal, PDF & wallpaper engines
│   │   ├── landing/           # LandingPage (hero, 3D tilt, bento features), video tutorial player
│   │   ├── planning/          # ExamScheduleModal, GpaCalculatorModal
│   │   ├── sharing/           # Schedule comparison & sharing (CompareScheduleModal)
│   │   └── timetable/         # TimetableGrid, LiveNextClass, AttendanceMeter
│   ├── shared/
│   │   ├── i18n/              # Multi-language dictionaries (en, ms, zh, ta)
│   │   ├── lib/               # Storage, caching, time parsing, audio chimes
│   │   └── types/             # TypeScript data contracts & interfaces
│   └── styles/
│       └── index.css          # Tailwind base & custom scrollbar styles
├── tests/                     # Vitest unit test suites & Playwright e2e specs
├── index.html                 # Root HTML shell with CSP & SEO metadata
├── vite.config.ts             # Vite build & plugin configurations
└── package.json               # Dependencies and build scripts

Documentation

Document Description
Installation Guide Local setup, environment variables, deployment & monitoring.
Architecture How the SPA, proxy, auth and data layers fit together.
API Reference Reverse-engineered USAS UMC endpoints & schemas.
Changelog Release history.
Contributing How to contribute.
Code of Conduct Community expectations.
Security Policy How to report vulnerabilities.
Privacy Notice Data flow, browser storage, and third-party services.

Contributing

We welcome contributions from the community! Please read our Contributing Guidelines to get started. By participating in this project, you agree to abide by our Code of Conduct.

Security

If you discover any security-related issues, please refer to our Security Policy for information on how to responsibly disclose vulnerabilities.

License

This project is licensed under the MIT License. See the LICENSE file for more details.

About

The timetable portal for USAS students to manage, view, and export their class schedules.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages