Integrations & platform.

There are two kinds of integration in YESS, and the difference is who holds the keys. A school-managed connection — a Zoom account, an OpenAI key — is something the school owns; you enter its credentials yourself on the integrations hub and switch it on. A platform-managed connection — a payment aggregator, an SMS or WhatsApp provider — is keyed centrally by YESS, never typed into a school dashboard, because those credentials move money or send at a scale that has to be governed, encrypted, and metered for everyone at once.

This is a deliberate design, not a missing feature. A school does not want to hold a payment gateway's secret key, and a regulator does not want it to. So the integrations hub shows you exactly the connections you control, says plainly which ones are platform-managed, and the delivery spine quietly handles the rest.

The plugs you own, keyed by you; the plugs that move money, keyed by the platform — every one of them audited.

The hub at /dashboard/integrations is a grid of provider cards grouped into three categories — the connections a school keys itself:

Open a card and you get a small form, one field per credential. Any field that is a secret, key, or token renders masked — the value is stored but never shown back in the clear. Save and the connection is written to the integration_configs table, keyed uniquely by school and provider, and the change is recorded in the audit log (provider and on/off state only — never the secret itself).

You will notice the hub has no payment category and no SMS or WhatsApp card. That is intentional, and the page says so with a note rather than leaving a confusing gap.

Payment gateways — Stripe, CamPay, CinetPay, NotchPay, PawaPay, and the mobile-money rails — are configured centrally by YESS, with each school's keys held in an encrypted vault, never entered on a school screen. A school never touches a gateway secret; it simply shares a secure payment link from the finance module, and the platform routes the collection. Messaging providers — the email, SMS, WhatsApp, and push channels — are platform-managed the same way: the accounts (and the deliverability, the templates, the regulatory consent) belong to YESS, so one provider outage or one misconfigured key cannot break messaging for a school that never had visibility into it.

What a school does control on the messaging side is its quota — how much of the shared sending pool it is allowed each month — which it reads (but does not key) from the notifications screen. The rest of this handbook is the spine that turns a notification into a delivered message, and the meter that governs it.

Every alert YESS sends — a fee receipt, an absence ping, an exam reminder — is a row inserted into the notifications table with a set ofpending channels. What happens next is the platform's job, and it starts with a gate.

The deliverability gate. A database trigger runs the instant a notification is inserted. It checks each external channel against the platform providers and strips out any channel that has no active, secret-configured, un-paused provider. The in-app channel is never queued for external sending (it is the row itself). If nothing is deliverable — a common case on a school whose region has no messaging provider switched on yet — the notification is marked skipped rather than looping forever. The whole gate is exception-guarded, so it can never block the notification from being created.

The dispatcher. A background worker then picks up the deliverable rows, resolves each recipient's preferences (quiet hours, per-event channel choice, WhatsApp consent, push tokens), chooses the default provider for each channel, and sends. A circuit breaker pauses a provider that fails repeatedly; every attempt — delivered, failed, paused, rate-limited, opted-out, deferred — is written to the dispatch log, which is insert-only and pruned on a schedule so it never bloats.

The one messaging dial a school can read is its quota. Open the notifications screen at /dashboard/notifications and its Quotas tab shows, per channel, the monthly limit and how much of it has been used this period. These figures come from the school_messaging_quotas table; the limits are set by the platform, and the school reads them.

The quota is enforced atomically at send time: the dispatcher acquires a slot before it sends and releases it if the send fails, so two messages firing at once can never push a school past its ceiling. A channel with no limit set is unlimited; a channel at its limit simply stops sending on that channel until the period resets — the meter is a guardrail, not a surprise bill.

Integration is not only outbound. When a parent pays through a mobile-money link, the aggregator calls YESS back to confirm the payment — and YESS listens. The platform runs server-to-server webhook endpoints for each supported gateway (Stripe, CamPay, CinetPay, NotchPay, PawaPay, and the YELE study-room payments), verifies the callback, and records the payment automatically against the right invoice.

These endpoints are platform-managed and invisible to a school — there is nothing to configure, because the gateway keys that authenticate them are held centrally. The bursar simply sees the payment appear in the finance module the moment the parent completes it, with no manual reconciliation.

The school integrations hub, the platform credential model, the delivery spine, the deliverability gate, the quota meter, and inbound payment webhooks are live. The honest gaps below are the parts still being built.

Integrations are the plumbing under several modules — they make the outbound connections those modules rely on.