NTU Planner Core

The open-source timetable engine and NTU data parsers behind Orbit. This repository contains reusable TypeScript logic for normalizing course data, detecting teaching-week-aware clashes, comparing indexes, laying out calendar events, optimizing index selections, and reading supported NTU schedule sources.

The final maintained snapshot is v0.1.1. See CHANGELOG.md for its compatibility notes.

This is deliberately not the deployed Orbit application. It does not contain the React interface, browser database, sharing/export features, HTTP API routes, deployment configuration, production URL, private repository history, or personal PDF samples.

Included modules

• src/domain/types.ts — the data contracts required by the published core.
• src/domain/schedule.ts — teaching-week parsing, conflict detection, calendar layout, index comparisons, and plan summaries.
• src/domain/optimizer.ts — deterministic, time-budgeted index selection across ranked schedule priorities.
• src/import/pdf.ts — browser-side parsing for supported text-based NTU class-schedule and registered-timetable PDFs.
• src/import/readStream.ts — a compatibility helper for PDF.js streams.
• src/import/reconcile.ts — reconciliation of registered selections with normalized module data.
• src/ntu/records.ts — parsing and bounded fetching for public NTU class-schedule and vacancy pages.

Tests use inline fixtures and mocked fetch responses. They do not contact NTU.

Requirements

• Node.js 24
• npm

Install and check

npm ci
npm run typecheck
npm test

The package is marked private to prevent accidental npm publication. Consumers should currently treat these modules as reference source rather than a versioned package API.

Data and privacy boundary

PDF parsing runs in the browser through PDF.js. The parser works from the file bytes supplied by its caller and does not upload or retain them. The NTU record helpers contact fixed public NTU endpoints when their fetch functions are called; callers remain responsible for applying appropriate caching, rate limits, error handling, and upstream terms.

No student names, original PDFs, filenames from personal samples, screenshots, analytics, credentials, deployment identifiers, or production service configuration are included here.

Limitations

• Scanned PDFs that require OCR are not supported.
• NTU HTML formats can change, so consumers should keep the parser tests current.
• The optimizer searches within a caller-supplied time budget and may return the best result found before that deadline.
• This repository does not provide a web UI or HTTP server.

Disclaimer

This is an independent project and is not affiliated with, endorsed by, or operated by Nanyang Technological University. Use the upstream services responsibly and comply with their applicable terms.

License

MIT