Skip to content

Notification system overview

Applies to: Owner, Administrator, Manager (anyone with Notifications.View), SuperAdmin, developers. Last reviewed: 2026-11-18.

This page explains how DriveFlow sends messages to students, instructors, staff and schools: what is sent, through which channel, by which part of the system, and where to look when something does not arrive.

Every statement here comes from the code as it stands; where a feature is unfinished it is said so.

New to DriveFlow notifications?

Start with Notifications at a glance for a one-page summary of who gets which message, when and by which channel.

Detailed pages:

Topic Page
Every event that sends a message (the full matrix) Notification triggers
Email Email notifications
SMS and SMS credits SMS notifications
WhatsApp WhatsApp notifications
Mobile push (Android) Push notifications
The bell in the header and the student portal Messages page In-app notifications
Lesson, driving test, invoice and document reminders Lesson reminders
Every setting, with defaults Notification settings
The wording of each message Notification templates
The Notification Log page Notification log
Problems and fixes Notification troubleshooting
One-document summary DriveFlow notification reference

1. The short version

  • DriveFlow has four delivery channels: email, SMS, WhatsApp and mobile push. There is also an in-app bell in the web header, but that is a live "things needing attention" list, not a stored message.
  • Email works on every plan. It is sent through DriveFlow's own mail server unless the school enters its own SMTP server under Settings > Email.
  • SMS and WhatsApp are sent through providers that DriveFlow (the platform) configures on the server. A school cannot enter its own SMS or WhatsApp account. SMS is paid for with prepaid credits; WhatsApp is a monthly add-on.
  • Push goes to Android phones signed in to the DriveFlow mobile app, through Firebase Cloud Messaging. There is no switch for it in the web settings: it is added automatically when the school's plan includes the Mobile App.
  • The school chooses which messages go out, and by which channel, under Settings > Notifications.
  • Message wording is fixed in the code. A school cannot edit templates.
  • Everything sent through the notification engine, plus invoices, receipts, quotes and payment reminders, is recorded in Settings > System > Notification Log. A few account emails (new user password, portal invite, password reset link, test email) are not recorded there.
  • There is no automatic retry of a failed message. A failure is written to the log with the provider's error text, and the business action (the booking, the payment, and so on) is never undone because of it.

2. Two ways a message is sent

There are two separate code paths. Knowing which one a message uses tells you which settings apply to it.

2.1 The notification engine (NotificationDispatcher)

Used for lesson, payment and reminder events. A handler raises a named event (for example LessonBooked) and the engine decides what to do.

flowchart TD
    A["Business action<br/>(e.g. staff books a lesson)"] --> B["Handler / job<br/>BookLessonHandler, CancelLessonHandler, LessonReminderJob, ...<br/>_notifications.SendAsync(NotificationEvent, NotificationContext)"]
    B --> D1{"NotificationDispatcher<br/>(DriveFlow.Infrastructure/Notifications)<br/>1. Which company? (tenant context)"}
    D1 -- none --> SKIP["Skip"]
    D1 --> D2{"2. Company notification settings, IsActive"}
    D2 -- missing / inactive --> SKIP
    D2 --> D3{"3. Is this event switched on?"}
    D3 -- off --> SKIP
    D3 --> D4{"4. Quiet hours?<br/>(non-urgent events only)"}
    D4 -- inside --> SKIP
    D4 --> D5["5. Channels = company switch AND event tick<br/>6. Remove SMS / WhatsApp if the plan or add-on does not cover them<br/>7. Add Push if the plan includes the Mobile App<br/>8. Find the recipient (student or instructor record)<br/>9. Build the text (NotificationContentFactory)"]
    D5 --> E["EmailNotificationChannel<br/>IEmailService (TenantSmtpEmailService, SMTP)"]
    D5 --> S["SmsNotificationChannel<br/>ISmsService (VodacomSmsService, HTTP)"]
    D5 --> W["WhatsAppNotificationChannel<br/>IWhatsAppService (MetaWhatsAppService, HTTP)"]
    D5 --> P["PushNotificationChannel<br/>IPushSender (FirebasePushSender, FCM)"]
    E --> L["One row per channel in the Notifications table<br/>(Sent or Failed) - Notification Log"]
    S --> L
    W --> L
    P --> L

Note

The engine never throws. If anything in it fails, the error is written to the server log and the booking, cancellation or payment still succeeds.

2.2 Direct emails

Documents and account emails do not go through the engine. Each service builds its own email and calls the email service directly:

flowchart TD
    A["Business action<br/>(e.g. Send Email on an invoice)"] --> B["Service<br/>InvoiceEmailService, InvoiceReminderService, PaymentReceiptEmailService,<br/>QuoteService, SubscriptionInvoiceEmailService, RegistrationEmailService,<br/>UserService, StudentPortalAccessService, PasswordRecoveryService"]
    B --> C["IEmailService (TenantSmtpEmailService)"]
    C --> D["SMTP server"]
    D --> E["Recipient"]
    C --> F["Notifications table row<br/>(most of them; see the trigger matrix for the exceptions)"]

Direct emails are email only

Ticking SMS or WhatsApp for "Invoice Issued" in the settings has no effect, because that message never passes through the engine.

3. Who receives what

Recipient How the address is found
Student The email address and phone number on the student's record. For push: phones registered to that student in the mobile app.
Instructor The email address and phone number on the instructor's record. For push: phones signed in with the user account linked to that instructor.
Walk-in customer The email on the invoice or quote (invoices, receipts, quotes and reminders only).
Staff user The user's sign-in email (account emails only).
School The organisation's email address, and the owner's sign-in email at registration.
DriveFlow platform admin The address in the Platform:AdminEmail server setting (new school registrations only).

A caller can never pass in an address. For engine events the address is always read from the student or instructor record of the current company (NotificationRecipientResolver).

There are no per-person opt-outs. A student or instructor cannot unsubscribe from a type of message; only the school's settings decide. The one exception is on the phone itself: a mobile app user can switch push off for that phone (see Push notifications).

Guardians and emergency contacts are never sent anything.

4. Immediate and scheduled messages

Kind Examples What runs it
Immediate Booking confirmation, cancellation, reschedule, payment received, invoice, quote, account emails Sent inside the request that performed the action. The user waits while it is sent.
Scheduled Lesson reminder, driving test reminder, payment reminder, document expiry reminder Hangfire recurring jobs running inside the API process. See Lesson reminders.

Hangfire is the only scheduler. It stores its jobs in the same SQL Server database and is started by AddHangfireServer() in DriveFlow.Api/Program.cs.

Warning

If the API is not running, no reminder is sent.

5. What gates each channel

Channel School switch Per-message tick Plan / add-on Platform configuration
Email Email under Notification Channels (default on) Email column (default on) None. Included on every plan. EmailSettings section (global SMTP), or the school's own SMTP
SMS SMS (default off) SMS column (default off) Plan must include SMS and, on a paid plan, the school must have SMS credits left VodacomSms section, Enabled must be true
WhatsApp WhatsApp (default off) WhatsApp column (default off) Plan must include WhatsApp and, on a paid plan, the add-on must be paid up MetaWhatsApp section, Enabled must be true
Push None None (follows the message's Enabled switch) Plan must include Mobile App Firebase must be configured on the server

During a free trial, add-on features are available without paying for the add-on (SubscriptionAccessService).

6. Limitations and notes

These are facts about the current code that a school or developer should know before relying on notifications.

  1. No retries. A failed message stays failed. Staff must resend manually where a resend button exists (invoice, receipt, quote, payment reminder, portal invite).
  2. No template editing. All wording is in NotificationContentFactory and the individual email services.
  3. Quiet hours drop most messages rather than delaying them. Only lesson and driving test reminders are held and sent later. A Student Welcome message or an SMS/WhatsApp payment reminder that falls inside quiet hours is skipped for good. See Notification settings.
  4. Times use the server's clock, not the branch time zone. Quiet hours and reminder timing compare against DateTime.Now on the server. The branch time provider is not used by the notification code.
  5. "Daily Instructor Schedule" does nothing. The setting exists and can be switched on, but no code sends that message.
  6. "Lesson Completed" cannot be switched off on its own. It is not listed in the settings; it follows the Email master switch only.
  7. "Invoice Issued" is email only, whatever is ticked for SMS and WhatsApp.
  8. Document expiry reminders do not reach anyone in the current code (see Lesson reminders section 5).
  9. A disabled SMS or WhatsApp provider is logged as "Sent". If the platform has Enabled set to false for the provider, the send is silently skipped but the log row still says Sent. For SMS a credit is still used.
  10. Some expected messages do not exist at all: nothing is sent for a no-show, for an instructor sign-off, for a booked or completed driving test, for a new lesson request (staff see it in the bell only), for lead follow-ups, for an ending trial or subscription, for vehicle licence or service dates, or for sales commissions. The full list is in Notification triggers.