Skip to content

README.md

Latest commit

 

History

History
187 lines (137 loc) · 7.23 KB

README.md

File metadata and controls

187 lines (137 loc) · 7.23 KB
Raw

📅 School Schedule Generator

School Schedule Generator Interface Screenshot

⚡ An intelligent, conflict-free school timetable generator & interactive scheduling platform.

Deploy to GitHub Pages pnpm monorepo React 18 Vite 5 Mantine UI v7 TypeScript 5 MIT License

🌐 Live Demo: https://o2sa.github.io/school-schedule-generator/

📖 About The Project

Manually creating academic schedules that satisfy complex real-world constraints—teacher availability, class periods, maximum daily workloads, and subject quotas—is a tedious and error-prone puzzle.

School Schedule Generator automates academic scheduling using an intelligent constraint-satisfaction engine with forward checking, minimum remaining values (MRV), and least-constraining value (LCV) heuristics.

The platform is designed to be local-first and client-driven: it can run completely inside the browser using Web Workers and IndexedDB (no database setup required), while also supporting an optional full-stack Express & MongoDB backend mode.

✨ Key Features

  • ⚡ Background Solver Engine: Timetables are generated inside a dedicated Web Worker using deterministic constraint backtracking, keeping the UI responsive at 60 FPS even during intensive calculations.
  • 💾 Local-First & Offline Ready: All data (teachers, classes, subjects, constraints, and generated schedules) is saved locally in IndexedDB via Dexie.js. No server installation needed.
  • 🌍 Full Bilingual Localization (English & Arabic RTL):
    • Automatic system language detection (navigator.language) with Arabic priority.
    • Native RTL/LTR layout transitions powered by Mantine's DirectionProvider.
    • Modern Arabic typography with Cairo and Tajawal Google fonts.
    • Interactive language switcher in the navigation bar.
  • 🌓 Adaptive System Dark / Light Theme:
    • Automatically matches system color scheme (prefers-color-scheme).
    • Refined high-contrast dark mode styling for timetable grids and teacher availability matrices.
    • Instant theme toggle in the header.
  • 📅 Interactive Timetable Editor & Multi-View:
    • Responsive multi-view tabs: Class Timetable, Teacher Timetable, and All Classes Master View.
    • Interactive drag/swap of lecture slots with real-time constraint validation.
  • ⚙️ Customizable Academic Calendar:
    • Configurable working days per week (5, 6, or 7 days).
    • Flexible lecture periods per day (e.g. 6 to 8 periods).
    • Fine-grained teacher availability slot matrix and weekly period capacity enforcement.
  • 🚀 Automated GitHub Pages CI/CD:
    • Automated deployment workflow via GitHub Actions (.github/workflows/deploy.yml).
    • SPA 404 fallback routing for seamless page refreshes on GitHub Pages.

🏗️ Architecture & Monorepo Structure

school-schedule-generator/
├── packages/
│   └── school-timetabling-engine/  # Standalone solver package (CJS, ESM, d.ts)
├── client/                         # React 18 + Vite + Mantine UI v7 frontend
│   ├── src/
│   │   ├── api/                    # Data context (Local IndexedDB or Server API)
│   │   ├── components/             # Reusable UI components & modals
│   │   ├── i18n/                   # Bilingual translations & RTL provider
│   │   ├── layouts/                # Responsive navigation & header shell
│   │   ├── pages/                  # Dashboard, Teachers, Classes, Generator, etc.
│   │   └── theme/                  # Mantine theme & dark mode tokens
│   └── tests/                      # Vitest + Testing Library test suite
├── server/                         # Optional Node.js + Express REST API
│   ├── controllers/                # Route controllers
│   ├── models/                     # Mongoose models (Teacher, Class, Subject)
│   └── populate.js                 # Sample database seeder
└── .github/workflows/deploy.yml    # GitHub Actions deployment to GitHub Pages

🚀 Getting Started

Prerequisites

  • Node.js (version 18 or later, Node 20 LTS recommended)
  • pnpm (version 9 or later)

Quick Start (Client / In-Browser Mode)

  1. Clone the repository:

    git clone https://github.com/O2sa/school-schedule-generator.git
cd school-schedule-generator

  2. Install dependencies:

    pnpm install

  3. Start the client development server:

    pnpm --filter client dev

  4. Open your browser: Navigate to http://localhost:5173 to use the application with local storage and Web Worker solving.

Optional: Running Full-Stack with Server & MongoDB

If you wish to use the centralized MongoDB backend:

  1. Ensure MongoDB is running locally (default mongodb://localhost:27017/school-scheduler).
  2. Start the server: 
    pnpm --filter server dev
  3. Run all services concurrently: 
    pnpm dev:all

🧪 Testing & Verification

Run the full monorepo test suite (engine + client):

pnpm test

Run test suite for a specific package:

pnpm --filter client test
pnpm --filter school-timetabling-engine test

📦 Building for Production

Compile all packages and generate optimized static assets for deployment:

pnpm build

The production bundle will be generated in client/dist/, complete with index.html and 404.html ready for static hosting.

🚢 GitHub Pages Deployment

The repository includes a GitHub Actions workflow in .github/workflows/deploy.yml that automatically builds and publishes the website to GitHub Pages on every push to development or main.

To enable it:

  1. Navigate to Settings > Pages in your GitHub repository.
  2. Under Build and deployment > Source, select GitHub Actions.
  3. Push to your repository to trigger the automated deployment.

🤝 Contributing

Contributions and ideas to enhance the constraint algorithm or UI are welcome!

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

📄 License

Distributed under the MIT License. See LICENSE for more information.