Office hours & appointments.

Before we open a single screen, a word about names — because YESS has three features that all use the phrase "office hours," and only one of them is this module. Read this once and you will never open the wrong screen.

This module — teacher office hours. A teacher publishes bookable one-on-one (or small-group) slots; a student books one. It lives at /dashboard/office-hours for the teacher and /portal/office-hours for the student, and is built on two tables — office_hours_slots and office_hours_bookings.

Parent-teacher conferences are a separate module with their own tables and their own booking engine — that is report-card night, documented in its own handbook. Student-government office hours at /portal/student-government/office-hours are a weekly drop-in availability grid for student officers — no booking, no slots, just "when and where you can find your reps." Neither shares a table with this module.

One teacher, one slot, one student, one atomic booking — the smallest honest unit of a teacher's time.

Follow one slot through its whole life and the rest of the book is detail.

Tuesday, 16:00. A maths teacher at Greenwood opens /dashboard/office-hours, fills the composer — Thursday 15:00–15:20, capacity 1, topic "Quadratics catch-up," host on YESS Live — and clicks Publish. A slot row is written in status open. The moment it lands, every student the teacher teaches gets a notification: "New office-hours slot — tap to book," deep-linked to their portal.

16:04. A student opens /portal/office-hours, sees the slot under "Open this week," types her own question in the topic box, and books. The booking is written through a database function that locks the slot first — so even if a classmate taps at the same second, only one of them gets the seat. Capacity was 1, so the slot flips to full. The teacher gets a notification: "New booking — Quadratics catch-up."

Thursday, 14:30. If the school has enabled the reminder job, both teacher and student get a thirty-minute nudge.

Thursday, 14:58. The teacher clicks Start live session. Because this is a YESS Live slot and it is inside the time window, YESS creates a private live-session room, stamps it onto the booking, and sends the student an urgent "Office hours starting — tap to join." The student joins at /portal/live-classes; the teacher lands in the same room via /dashboard/virtual-classes. Twenty minutes later the quadratics make sense.

The teacher's surface is /dashboard/office-hours (the same page is re-exported at /teacher/office-hours so it renders inside teacher chrome). It resolves the teacher's own staff record, lists their upcoming and recent slots, and carries a KPI strip — upcoming, open, bookings, full. The composer is the heart of it.

The student's surface is /portal/office-hours. It shows three bands: "Open this week" (open, future slots the student hasn't already booked), "My upcoming bookings," and a short history. Booking takes one tap plus an optional topic — but underneath, it is the most carefully engineered action in the module.

A booking is never a plain insert. It runs through a database function that locks the slot row first, then checks — in that locked window — that the slot still exists, is still open, isn't in the past, and has a free seat. Only then does it write the booking and, if the slot has just filled, flip it to full. Two students tapping the last seat in the same instant cannot both win: one gets the booking, the other gets a clean "slot full" message.

Each student can hold at most one booking per slot — a unique constraint on the pair guarantees it, and re-booking a slot the student previously cancelled simply reuses the same row. The student may cancel at any time; cancelling reopens the slot (full → open) so the seat is immediately available to someone else. A teacher can also cancel a whole slot, which auto-cancels every booking on it and notifies each affected student.

A YESS Live slot has one more move. Near session time, the teacher's slot row grows a Start live session button — but only when two things are true: the slot was published with "Host on YESS Live" on, and the clock is inside the window (from ten minutes before the start to fifteen minutes after the end). Outside that window the button reports "too early" or "the slot window has passed" rather than opening an empty room.

Clicking it runs a database function that creates a private live-session room, marks it not-recorded (office hours are private by design), and stamps the new session id onto every booking on the slot. It is idempotent — click it twice and you re-enter the same room, you don't create a second. The same call sends every booked student an urgent "Office hours starting — tap to join" notification deep-linked to /portal/live-classes, while the teacher is redirected into the room at /dashboard/virtual-classes.

From there, the session is an ordinary YESS Live room — the same LiveKit surface documented in the Live & virtual classes handbook, with the same join tokens. The office-hours booking itself does not record attendance; it hands off to the live-classes room and that is where the two people actually meet. In-person slots skip this chapter entirely.

Office hours only work if the right person is nudged at the right moment. The module fires notification fan-outs automatically, plus an optional reminder.

On publish — every student the teacher teaches is told a new slot is open, deep-linked to their portal. On booking — the teacher is told who booked and what topic they attached. On slot cancellation — every currently-booked student is told the slot is off, and their bookings are auto-cancelled in the same step. And on session start, as chapter four described, booked students get the urgent "tap to join" ping.

A further signal — the thirty-minute reminder to both sides, plus the auto-complete that closes a slot after its end time — runs on a scheduled job that is opt-in and off by default. On a stock install no reminders fire and slots are not auto-completed; a school turns the job on when it wants those behaviours. The reminder is idempotent — it stamps a "reminder sent" marker so a slot is never nudged twice.

A booking is a small, private thing, and the row-level rules treat it that way. Slots are readable by anyone in the school — a slot is public availability. Bookings are not: a booking is visible only to the student who made it, the teacher who owns the slot, a linked active parent of that student, and an administrator with the right oversight permission. A classmate browsing open slots never sees who else has booked.

All of these surfaces sit under the LMS permission set — the same permission that opens courses and assignments gates the office-hours screens, and every write is stamped into the audit trail under the LMS module. There is no separate "office hours" role to grant.

The module is small and sharp — it does the hard part (atomic booking) well, and leaves some softer edges for later. These are the honest gaps, listed so you can plan around them.

Office hours sit at the join of the live classroom, the notification spine, and the LMS. Here is what plugs into what.