CourseKit

Timetable engine for academic scheduling with recurring events, conflict detection, and a React frontend

CourseKit is an open-source timetable engine for academic scheduling. It handles recurring events, conflict detection, availability management, and StarPlan ingestion. It ships as three packages that work together.

Packages

Package	Description
`@hfu.digital/coursekit-nestjs`	Backend NestJS module with pluggable storage, constraint pipeline, and domain events
`@hfu.digital/coursekit-react`	Frontend library with headless hooks and pre-styled schedule components
`@hfu.digital/coursekit-starplan`	Framework-agnostic StarPlan ingestion: iCal parsing, RRULE normalization, content-hash change detection, room/instructor extraction

Key Features

Recurring Events — RFC 5545 RRULE support with exceptions (cancel, modify, add occurrences)
Conflict Detection — Pluggable constraint pipeline: overlaps, capacity violations, availability breaches
Availability Management — Hard/soft availability rules for instructors and rooms with free-slot search
Pluggable Storage — Bring your own database via abstract storage classes (Prisma adapters included)
Domain Events — Event-driven architecture via @nestjs/event-emitter
Academic Periods — Semester, holiday, exam, and break period modeling with hierarchy
StarPlan Integration — First-class HFU StarPlan ingestion with stable content hashing and change detection
Headless-First Frontend — Hooks for full control, plus optional TimetableGrid and EventCard components
Dry-Run Conflict Checks — Preview conflicts before committing schedule changes
Structural Typing — Backend never imports @prisma/client — adapters handle ORM specifics

Versioning

CalVer (yyyy.mm.version). Pin exact versions in package.json; range operators (^, ~) do not behave like semver across month boundaries. See the docs root for details.