Timetable

The Timetable Generator is an automated scheduling engine that builds conflict-free class timetables for one or more grades in a single run. Instead of manually dragging subjects into time slots, staff select the grades (and optionally specific classes), pick a timetable category and evaluation period, and let the engine place every required lesson while respecting teacher availability, classroom availability, and any configured scheduling rules.

Building a school-wide timetable by hand is slow and error-prone — a single teacher double-booking or classroom clash can cascade into dozens of manual fixes. This module automates that process using an iterative constraint-solving algorithm, producing a draft timetable in seconds to minutes that administrators can review, regenerate, or publish. As part of the Academic Aspects / Scheduling suite, its output feeds directly into the timetable views used by teachers, students, and parents elsewhere in the system.

Before running a generation, the following must already be configured:

• Academic Year — an active academic year must exist; the generator always runs within a single academic year.
• Evaluation Period (optional but recommended) — if selected, the generator scopes both its conflict checks and its output strictly to that period, leaving other periods' timetables untouched. If left blank, the generator falls back to scoping by semester instead.
• Periods — each grade must have its daily period/session structure defined (used to determine how many time slots are available per week).
• Teacher Setups — subject-to-teacher-to-classroom assignments per class; without these, the generator has no lessons to place and the run will fail immediately.
• Grade ↔ Subject links — including the number of required sessions per week for each subject, scoped to a timetable category.

Open the Academic Aspects (or Scheduling) menu in the sidebar. Select Timetable Generator. Configure your run and click Start Generation, or click View History to see past generation runs. ---

[!IMPORTANT] Existing Timetable Warning If any of the selected grades/classes already have a timetable for the chosen category and evaluation period, the system warns that starting generation will delete the current timetable for those selections before proceeding. You must explicitly confirm to continue.

1. Configure — choose category, evaluation period, grades, and (optionally) classes.
2. Existing-Timetable Check — the system checks whether a timetable already exists for the exact selection and warns before overwriting it.
3. Confirm & Start — a confirmation dialog explains that this will generate a draft timetable.
4. Generate — the browser calls the generation endpoint directly and waits for the result, while a simulated progress bar animates in the UI.

Review Results:

• Success — shows how many sessions were placed out of the total required, and renders a live preview of the generated schedule per grade.
• Partial success (0 placed) — flagged distinctly, prompting the user to check Teacher Setups and constraints.
• Failure — shows the specific reason plus a list of concrete conflicts detected.

Decide:

From the result screen you can:

• Keep as Draft — leaves the timetable saved but inactive; it can be published later from the History page.
• Publish & Activate — makes the generated timetable the live/active one for that scope, deactivating whatever was active before it.
• Regenerate — re-runs the whole generation process from scratch with the same configuration.
• Retry (on failure) — returns to the configuration screen to adjust settings before trying again.

The generation endpoint supports two modes:

• Synchronous — runs the algorithm immediately within the request and returns the final result directly.
• Asynchronous (default) — creates a preliminary log entry with status pending, dispatches a background job to do the actual work, and immediately responds with queued. Progress can then be polled via the log ID.

Either way, the endpoint first checks whether a generation is already running for the same academic year and evaluation period and rejects the request if so, preventing overlapping runs from corrupting each other's data.

The generator (an "iterative swap" solver) works in distinct phases:

1. Build Time Slots

For each selected grade, it reads the grade's configured Periods and expands them into a flat list of slots — one slot per session, per day.

2. Build Lessons

For each grade → class → subject combination, it creates one lesson entry per required weekly session, each carrying its teacher/classroom assignment(s) pulled from Teacher Setups.

3. Build Constraints

Two kinds of rules are loaded:

• Hard restrictions — e.g., "Subject X cannot be scheduled in Period 3 on Monday".
• Soft restrictions — per class or per grade, these define a subject's maximum sessions per day and/or whether its sessions must be back-to-back.

4. Load Existing Assignments

To avoid clashing with schedules that already exist for grades/classes not included in the current run, the engine loads all currently-active timetable details.

5. Pre-Solve Validation

Before attempting to solve, the engine checks:

• That at least one lesson was generated.
• That each class has enough weekly time slots to fit all its required lessons.
• That no teacher is assigned more total periods across all their classes than the number of periods in a week.

6. Solve (Iterative Swap Algorithm)

Lessons are placed randomly into slots as a starting point. The engine repeatedly picks two lessons within the same class and swaps their time slots if doing so reduces the total conflict score.

Once solved, the engine:

• Deletes the previous timetable for the exact same grades/classes/category/evaluation-period scope.
• Creates a new Timetable record marked as a draft unless publish was explicitly requested.
• Creates the individual timetable rows for every successfully placed lesson.

Every generation run initially produces a draft timetable:

• Draft — saved but not the live/active schedule. Visible from the History page, and can be published later.
• Published — the active schedule that teachers/students/parents see.

Each generation run is tracked via a log record with:

• Status: pending, running, success, or failed
• Progress: 0–100
• Total lessons / placed lessons: live counts as the solver works
• Error message: populated on failure

Access to this screen is governed by the surrounding route/menu permissions configured for your system.