Notifications & alerts.

Every other module produces events; notifications carries them. A grade is posted, an invoice falls overdue, a club meeting is scheduled, a safeguarding flag is raised — each one becomes a notification, routed to exactly the people who should know, on exactly the channels they have chosen, and no further.

Three forces decide the path of every alert. The event has a category. The person has preferences. The school has quotas — and a configured provider per paid channel. The dispatcher resolves all of them for every recipient before it sends a single message. The rest of this handbook is those forces, one chapter at a time.

The in-app inbox is the one channel that always delivers — it costs nothing and never runs out of quota. Parents and students read theirs at /portal/notifications, teachers at /teacher/notifications, and school staff at /dashboard/notifications. Each inbox shows messages newest-first, lets the reader filter by All, Unread, or a single category, and hides any category with no messages so the filter row stays scannable. (The teacher and staff views group by day — Today, Yesterday, then dated.)

The inbox is real-time. A new notification arrives over a live database subscription and surfaces as a toast the instant it is created — no refresh, no polling. The subscription is mounted once, in the notifications bell that rides the top bar, so every surface stays current without re-subscribing. Readers mark one notification read or mark all read (clicking one also carries them to whatever it points at); deleting a message from the inbox is a staff action on the admin surface.

Beyond the in-app inbox, YESS reaches families on four external channels: push (to the mobile app), email, SMS, and WhatsApp — five channels in all. Every notification carries a category, and the category paired with each recipient's preferences decides which channels actually fire. The family-facing preference grid covers thirteen categories — academic, financial, communication, attendance, transport, admissions, LMS, social, incident, discipline, health, newsletter, and system — while the platform routes a few more event types behind the scenes (magic links, welcome, plan changes, and the like).

When an event occurs, the in-app copy is delivered immediately and the external channels are queued. There is one more gate before a paid channel can send: the school must have a configured provider for that channel (an email, SMS, WhatsApp, or push provider that is active and credentialed). If no provider is configured, the external copy is simply skipped and the in-app copy still lands — so a school with no SMS provider quietly falls back to in-app rather than failing.

A family controls exactly how the school reaches them at /portal/notifications/preferences. The page has two halves. The first is delivery settings that apply to everything: quiet hours (a window during which non-critical messages are held), a digest mode (off, a daily summary, or a weekly one), the language a message should arrive in (auto, English, French, or Arabic), and a read-receipts toggle.

The second half is the routing grid: for each of the thirteen categories, a master on/off switch and — when it is on — five channel toggles for in-app, push, email, SMS, and WhatsApp. Changes save the moment they are made. WhatsApp is special: a family must enter and confirm a phone number in international format before any WhatsApp message can be sent, and revoking consent clears the number instantly — a deliberate compliance gate, not an oversight.

External channels cost money, so each school has a monthly quota per paid channel — email, SMS, WhatsApp, and push — seeded at signup (the starting allowances are generous: 100,000 email, 500,000 push, and 5,000 each for SMS and WhatsApp). The admin reads usage against limit on the Quotas tab of /dashboard/notifications; the bar warns past 80% and turns destructive at the limit. When a channel's monthly limit is reached, the dispatcher stops sending on it — the in-app copy still lands, so the message is never lost, only the paid channel pauses.

The same hub carries a Dispatcher view for the people who run delivery: queue-health tiles (pending, dispatched, partial, failed, skipped) and 24-hour volume, the oldest items still waiting, and recent failures. Delivery drains automatically — an edge function runs on a cron schedule — but a Send queue now button flushes it on demand. Every channel attempt is written to an immutable dispatch log with its own status (delivered, rate-limited, opted-out, no-provider, quiet-hours-deferred, or failed), so “did the parent get the SMS?” is answerable from the record rather than guessed.

Some news goes to the whole school at once — a closure, an event, a policy change. The Send notification tab on /dashboard/notifications composes a broadcast: a title, a body, the channels to use, and an audience picked by role. It can go out immediately with Send now or be scheduled for later. A broadcast fans out into individual notifications, so each recipient still receives it on their own enabled channels and in their own language, and the same quota, provider, and dispatch rules apply.

Broadcast history is kept with per-message counts — total recipients, how many were sent, how many failed — so a head can confirm a closure notice actually reached the school rather than hoping it did.

Notifications is the downstream channel for nearly every other module — it carries the events they produce.