Domain Model Proposal

A proposal, not a decision. Every entity and relationship below is open to challenge; the open decisions are listed at the end.

Version 0.1, 5 September 2026. A starting proposal for how the product models a school and everything that must be timetabled. It is shaped after the XHSTT standard so that any solver can be plugged in and so that a school can be exported as a benchmark instance, and it is extended where Israeli primary schools need more than the standard offers.

Overview

The model separates four concerns that timetabling products usually tangle together: what the school is (organisation and people), what must happen each week (curriculum and the events it generates), what the rules are (constraints, each traceable to a requirement ID), and what the solver produced (a timetable version with its assignments and its score). Application logic works on the first three and produces the fourth; no frontend concept appears anywhere in the model.

Summary

• The unit the solver places is an Event: a lesson or activity with a duration, one or more student groups, one or more staff slots, an optional subject and an optional room requirement. A class lesson, a grade-wide trip, a choir across six classes, a staff meeting with no class at all, and a teacher's individual hour are all events.
• StudentGroup, not Class, is the atomic audience. A whole class is one kind of group. A half class, an ability group drawn from three classes, or a choir cohort are other kinds. This one decision supports Israeli hakbatsot now and per-student scheduling later.
• Staff carry a contract, an hour basket and availability. A staff slot on an event has a role (lead, co-teacher, assistant, soldier), which is how co-teaching (R-03, R-12) is expressed without special cases.
• Constraints are typed rules with a weight and a hard/soft flag, each pointing at the requirement ID it implements. Vegman's list becomes rows in a constraint table, not code.
• Timetable is a versioned solution: assignments of events to time slots, rooms and resolved staff, plus a score made of violations that each name the constraint they break. Pinning and diffing between versions are first-class because Israeli schools re-cut the timetable several times a year.

Bottom line

Adopt this model as the domain layer now, implement it as plain data classes with no framework dependency, and write two adapters first: an importer from the Tik-Tak export, and an exporter to XHSTT. That gives a scored benchmark of Mevo Hagalil's real timetable before a single solver line is written. The open decisions at the end (rooms, students, hour placement) do not block that.

Detailed explanation

The diagram

Boxes are entities. Lines are relationships with cardinality: 1 one, * many, 0..1 optional. Read from the top: organisation feeds curriculum, curriculum generates events, constraints govern events, and a timetable assigns them.

classDiagram
direction TB

class School {
  id
  name
  sector
  weekStructure : TimeGrid
}
class Grade {
  id
  level : 1..12
  name
}
class Class {
  id
  name
  homeroom : Staff
}
class StudentGroup {
  id
  kind : class | half | level | cross | cohort
  drawnFrom : Class[]
}
class Student {
  id
  name
}
class Staff {
  id
  name
  role : teacher | assistant | soldier
  contract : OfekHadash | OzLaTmura
  frontalHours
  individualHours
  stayingHours
  subjects : Subject[]
}
class Availability {
  slot : TimeSlot
  state : unavailable | preferNot
  reason
}
class Subject {
  id
  name
  isCore
  roomType : RoomType
}
class CurriculumLine {
  grade : Grade
  subject : Subject
  weeklyPeriods
  pattern : 2+2+1
  coTeaching : rule
}
class Event {
  id
  subject : Subject 0..1
  duration : periods
  kind : lesson | activity | meeting | individual | staying
  fixedAt : TimeSlot 0..1
  pinned
}
class StaffSlot {
  role : lead | co | assistant | soldier
  assigned : Staff 0..1
}
class EventGroup {
  id
  kind : sameCourse | linked
}
class TimeGrid {
  days
  periodsPerDay
  clockTimes
}
class TimeSlot {
  day
  period
  isLongDay
}
class RoomType {
  id
  name
}
class Room {
  id
  name
  type : RoomType
  capacity
}
class Constraint {
  id
  type : XHSTT-style
  hard
  weight
  params
  implements : RequirementId
}
class Timetable {
  id
  version
  status : draft | published
  basedOn : Timetable 0..1
}
class Assignment {
  event : Event
  slots : TimeSlot[]
  room : Room 0..1
  staff : Staff[]
}
class Violation {
  constraint : Constraint
  cost
  explanation
}

School "1" --> "*" Grade
School "1" --> "1" TimeGrid
TimeGrid "1" --> "*" TimeSlot
Grade "1" --> "*" Class
Class "1" --> "1" Staff : homeroom
Class "1" --> "*" StudentGroup : drawn from
StudentGroup "*" --> "*" Student : optional
Staff "1" --> "*" Availability
Staff "*" --> "*" Subject : teaches
Grade "1" --> "*" CurriculumLine
CurriculumLine "*" --> "1" Subject
CurriculumLine "1" --> "*" Event : generates per class
Event "*" --> "*" StudentGroup : attendees
Event "1" --> "*" StaffSlot
StaffSlot "*" --> "0..1" Staff
Event "*" --> "0..1" RoomType : requires
Event "*" --> "0..1" EventGroup
Room "*" --> "1" RoomType
Constraint "*" --> "*" Event : governs
Constraint "*" --> "*" Staff : governs
Timetable "1" --> "*" Assignment
Assignment "1" --> "1" Event
Assignment "*" --> "*" TimeSlot
Assignment "*" --> "0..1" Room
Timetable "1" --> "*" Violation
Violation "*" --> "1" Constraint

Entity catalogue

How Vegman's rules map onto the model

Boundaries and layers

The domain model is one package with no dependencies. Around it:

• Constraint catalogue: the list of constraint types the product understands, each with a scorer that can evaluate any Timetable without a solver. This is what makes the achieved Mevo Hagalil timetable scorable on day one.
• Solver adapters: CP-SAT first, Timefold or MIP later. Each translates Problem to solver variables and back. Nothing else knows which solver ran.
• Importers and exporters: Tik-Tak (the pilot's current tool), XHSTT (benchmarks), later Mashov, SmartSchool and Ministry registries.
• Back-office application: CRUD over School, Staff, Subject, CurriculumLine, Constraint, through an API.
• Timetable application: view, pin, repair, publish; talks only to the API.

Open decisions

• Rooms: model them but leave assignment off for Mevo Hagalil unless Q-13 says otherwise.
• Students: keep the entity, do not populate it for the pilot.
• Non-frontal hours: whether individual and staying hours are placed events or only counted depends on Q-03. The model supports both; the constraint catalogue differs.
• Group formation: whether the solver may form ability groups itself (the 2024 XHSTT extension) or receives them as input. Input for the pilot.
• Identity: teachers with the same first name (S-03) need stable IDs and display names; the Tik-Tak import must map short names to full names.