About this project

This is a scheduling and substitute/adjustment system designed around the daily workflow of academic affairs section chiefs in Taiwan K-12 schools. It is MIT-licensed, self-hosted per school, pure web, with a Traditional Chinese interface using Taiwan education terminology. Its functional coverage is quite complete. The basic data section includes semesters and period tables (multi-system templates), teachers/classes/subjects/venues, Excel import, a setup wizard, copying when starting a new semester, and assignment of classes and period tables for mixed systems. Subject allocation and manual scheduling support traveling class groups, co-teaching, consecutive periods, real-time hourly statistics, drag-and-drop weekly timetables, single-cell conflict checking, multi-draft version management, and publishing. Automatic scheduling uses the Google OR-Tools CP-SAT engine, solving with weighted H1-H10 hard constraints and S1-S8 soft constraints, runs in the background, and provides real-time progress; when no solution exists, it locates conflicts in academic-affairs language and supports partial scheduling. The substitute/adjustment process includes leave registration and expansion of affected periods, substitute recommendations, adjustment validation, assignment taking effect immediately, in-site and Email notifications and confirmations, a today dashboard and A4 announcement printing, and monthly hourly statistics export to Excel. Reports can output class, teacher, and venue timetables as Excel, PDF (with embedded Chinese fonts), or PNG, and provide a whole-school master table and batch zip. On the operations side, there are daily automatic backups, manual backup/download/upload restore, audit logs, and RBAC role permissions. The tech stack is Vue 3 + TypeScript + Vite + Pinia + Naive UI for the frontend, Python 3.12 + FastAPI + SQLAlchemy 2 + Pydantic v2 for the backend, PostgreSQL 16 for the database, Redis and RQ for background scheduling and export/backup jobs, and Caddy as the reverse proxy, with the whole system deployed as six containers via Docker Compose. Official images are provided for both amd64 and arm64. The minimum requirement is 2 cores / 4GB RAM / 10GB disk, and 4 cores / 8GB is recommended for automatic scheduling. Installation provides one-click scripts (Windows PowerShell and bash versions for Linux/macOS/NAS), and you can also pull the official image or build from source. The project is intentionally designed to be downloaded first and then run rather than executed directly via a pipeline, so users can inspect the contents first. The system includes a demo data feature that can quickly generate complete data for a fictional junior high school when no semester has yet been created, making it easy to experience scheduling, substitute/adjustment, export, and backup workflows. Documentation includes an academic affairs section chief operations manual (an 11-chapter illustrated web page), deployment manual, architecture design, development task cards, changelog, and contribution guide, and provides an offline-readable HTML version. The project status is v1.2.4, the six major milestones M0-M5 are complete, and there are unit, integration, and end-to-end tests.