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.
- 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.
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 uselocalStorage. These remain on the device until logout or browser storage is cleared. See the Privacy Notice.
Frontend
Document & Media Engines
- jsPDF
- html2canvas
- QRCode
- qr-scanner (camera and image QR decoding)
Backend & Hosting
- Cloudflare Pages Functions (API proxy)
- Wrangler
Testing & Quality Assurance
Monitoring
- Sentry (optional client error tracking)
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.
- Node.js >= 18.x (v20+ recommended)
- NPM >= 9.x (or pnpm / yarn)
-
Clone the repository
git clone https://github.com/zis3c/USAS-Class-Timetable.git cd "USAS Class Timetable"
-
Install dependencies
npm install
-
Start development server
npm run dev
Real API login:
npm run devserves the UI (and demo mode) only. The/api/usasproxy is a Cloudflare Pages Function. For local API login, runnpx wrangler dev --config cloudflare/altcha-replay-guard/wrangler.tomlin one terminal, thennpm run dev:cfin another. -
Run unit tests and type checks
npm run typecheck npm run test:unit
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
| 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. |
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.
If you discover any security-related issues, please refer to our Security Policy for information on how to responsibly disclose vulnerabilities.
This project is licensed under the MIT License. See the LICENSE file for more details.

