The notifications lifecycle

This page is about the in-app notification feed — the bell / updates list an agent sees inside the broker or sales-man app. A domain event (a lead is verified, a sale is invoiced, an EOI changes state) writes a row in the notifications table, and the app polls for it and marks it read. That is a different thing from the outbound push / SMS / email delivery documented on Notifications (integration): outbound channels push a message out to a person, whereas this feed is a stored, pull-based inbox the app queries. Everything here is read from the current backend.

One notify() call, two destinations

Most notification classes return ['database', OrascomMailNotification::class] from via() (e.g. app/Notifications/Broker/VerifiedLead.php:33-36, app/Notifications/SalesInvoiceStatusApproved.php:32-35). The database channel is what this page covers — it writes the in-app feed row. The OrascomMailNotification channel is the outbound email, sent in the same notify() call but on a separate path (app/Notifications/OrascomMailNotification.php:25-41). So a single event usually produces both a feed row and an email. This page follows only the database half.

What the agent sees

From the sales-man (or broker) app, the agent opens the notifications list — each row is one row from the notifications table, newest first, with a read / unread state:

The data behind one notification

A feed row is App\Models\Notification (app/Models/Notification.php:10), backed by the standard Laravel notifications table (database/migrations/2023_09_20_152852_create_notifications_table.php:22-34):

• id — auto-increment integer (the app marks rows read by this id, not a UUID).
• type — a plain string; Laravel’s database channel stores the notification class name here (e.g. App\Notifications\Broker\VerifiedLead). This is not the business type the app routes on — see the gotcha below.
• notifiable_type / notifiable_id — the polymorphic recipient (Broker, SalesMan, Shopper, or a base User), written by $table->morphs('notifiable').
• data — a JSON blob. Its shape is always Notification::createJsonMessage($title, $body, $redirectData) (app/Models/Notification.php:64-76), i.e. { message: { title, body, redirect_data } }.
• read_at — nullable timestamp. null means unread.
• deleted_at / timestamps — the model uses SoftDeletes.

Two accessors read back out of data: message returns data['message']['body'] (app/Models/Notification.php:39-42) and redirect_data returns data['message']['redirect_data'] (:55-58). The app uses redirect_data.type — a NotificationTypeEnums value — to decide where a tap deep-links (the lead, the invoice, the EOI).

The whole trip, in one diagram

sequenceDiagram
participant EV as Domain event (CRM webhook / in-app)
participant API as Backend (Laravel)
participant CH as database channel
participant DB as notifications table
participant ML as Mail channel (OrascomMail)
actor APP as Agent app (Broker / Sales-Man)
EV->>API: lead / meeting / invoice / EOI status change
API->>API: recipient calls notify(new XNotification)
Note over API,CH: via() returns database plus OrascomMailNotification
API->>CH: database channel
CH->>DB: INSERT row - data JSON, read_at null, notifiable = recipient
API->>ML: send email (separate outbound channel)
APP->>API: GET user/notifications (poll, per_page 10)
API->>DB: where notifiable_id and notifiable_type, order by created_at desc
DB-->>API: one page of rows
API-->>APP: NotificationResource list with is_read
APP->>API: POST user/notifications/read - ids plus is_read
API->>DB: set read_at = now() for those ids
API-->>APP: Notifications updated successfully

In-app notification — event writes a row, app polls it, app marks it read (verified)

Step by step

1. An event fires and a recipient is notified. The most common trigger is a crms-middleware webhook — the CRM pushes a status change and the portal turns it into a feed row: POST brokers/user/notifications (general), POST leads/{leadSourceId}/notifications, POST meetings/{meetingSourceId}/notifications, POST eois/{eoiSourceId}/notifications (routes/api/crms-middleware.php:13-17). The controller resolves the recipient and calls $notifiable->notify(new XNotification(...)) (app/Http/Controllers/Api/CrmsMiddleware/NotificationController.php:23-93). For leads, LeadSubmissionNotification maps the CRM status/decision to the right class — VerifiedLead, NotVerifiedLead, ReservedLead, ContractedLead, RejectedLead (app/Actions/User/Broker/LeadSubmissionNotification.php:16-55). A few events are raised in-app, not from the CRM: a shopper reservation fires SaleStatusDone (app/Http/Controllers/Api/Shopper/UnitSaleController.php:212), a duplicate lead fires DuplicateLead (app/Http/Controllers/Api/SalesMan/LeadController.php:101), and an approved invoice fires SalesInvoiceStatusApproved from an Eloquent observer (app/Observers/SalesInvoiceObserver.php:56).

2. The database channel writes the row. Because via() includes 'database', Laravel’s built-in database channel persists through the recipient’s notifications() morphMany (app/Models/User.php:64-67, enabled by the Notifiable trait at :11,16). It stores the toArray() payload into data and sets read_at = null. toArray() is always built with Notification::createJsonMessage($title, $body, $redirectData) and stamps redirect_data.type with a NotificationTypeEnums value (e.g. app/Notifications/Broker/VerifiedLead.php:62-77, type at :70).

3. The app polls the feed. GET user/notifications is registered per persona (routes/api/broker.php:98, routes/api/sales-man.php:39) behind auth:sanctum + user-provider:<persona>. NotificationController@index resolves the session agent and calls GetNotifications::handle($id, <Persona>::class, $filters) (app/Http/Controllers/Api/Broker/NotificationController.php:14-25, app/Http/Controllers/Api/SalesMan/NotificationController.php:14-25). The action queries by notifiable_id + notifiable_type, optionally whereNull('read_at') when unread is set, orders by created_at desc, and paginates (default 10 per page) (app/Actions/Notification/GetNotifications.php:15-28). Query params are unread (bool) and per_page (int) (app/Http/Requests/Notification/IndexRequest.php:14-20). Each row is serialized by NotificationResource to { id, message, redirect_data, created_at, is_read }, where message is the body, created_at is a unix timestamp, and is_read = (bool) read_at (app/Http/Resources/NotificationResource.php).

4. The app marks rows read. POST user/notifications/read (routes/api/broker.php:99, routes/api/sales-man.php:40) hits NotificationController@update, inherited from NotificationBaseController (app/Http/Controllers/Api/Base/NotificationBaseController.php:12-17). It runs MarkNotificationsAsRead, which does Notification::whereIn('id', $notification_ids)->update(['read_at' => $is_read ? now() : null]) (app/Actions/Notification/MarkNotificationsAsRead.php:10-14). The request body is notification_ids (array) + is_read (bool); MarkAsReadRequest validates that every id exists and belongs to the calling agent — notifiable_type = <caller class> and notifiable_id = <caller id> (app/Http/Requests/Notification/MarkAsReadRequest.php:17-25).

Notification types

redirect_data.type carries an App\Enums\NotificationTypeEnums value (string-backed, app/Enums/NotificationTypeEnums.php:9-15). This is the value the app switches on to deep-link a tap — it is separate from the type column (which holds the class name). Not every enum case is actually emitted into the feed today:

Enum value	Case	Emitted into the feed by	Actually produced?
lead	LEAD	VerifiedLead, NotVerifiedLead, ReservedLead, ContractedLead, RejectedLead, AcceptedMeeting, RejectedMeeting	Yes
sales_invoice	SALES_INVOICE	SalesInvoiceStatusApproved	Yes
eoi	EOI	SuccessEOISubmission, ConfirmedEOIPayment, ExpiredEOI, EOIChequeSubmitted, EOIBankTransferSubmitted	Yes
sale	SALE	(none — no notification sets this value)	No
unit	UNIT	(none — UnitCreationNotification is email-only, its via() returns only OrascomMailNotification)	No

Gotchas

Mark-read ownership is enforced in the FormRequest, not the action

MarkNotificationsAsRead runs a bare Notification::whereIn('id', $ids)->update(...) with no re-scoping to the caller (app/Actions/Notification/MarkNotificationsAsRead.php:12-13). The only thing stopping an agent from flipping someone else’s rows is that MarkAsReadRequest validates each id belongs to the caller (MarkAsReadRequest.php:21-23). The guard lives entirely in validation — anyone re-using the action outside that request (a job, a command, a new controller) would update any id passed in.

The read endpoint is a toggle, not a one-way mark-read

read_at is set to now() when is_read is true and back to null when is_read is false (MarkNotificationsAsRead.php:13). So POST user/notifications/read with is_read = false re-marks a row unread. It is a set-read-state call, not an idempotent mark-read.

Shoppers get feed rows but have no way to read them

SaleStatusDone notifies the shopper on reservation (app/Http/Controllers/Api/Shopper/UnitSaleController.php:212), writing a notifications row against the shopper. But routes/api/shopper.php exposes no user/notifications route — only broker and sales-man have the feed. Those shopper rows are effectively unreachable through the API. The in-app feed is a broker / sales-man surface.

The stored title is never returned; only the body is

createJsonMessage stores both a title and a body, but the message accessor returns only data['message']['body'] (app/Models/Notification.php:39-42), and NotificationResource exposes message (the body) + redirect_data — never the title (app/Http/Resources/NotificationResource.php). If a client needs the title, it is in the DB but not in the API response.

Two different “type” fields — don't confuse them

The type column stores the Laravel notification class name (its databaseType / get_class), while the value the app routes on is redirect_data.type — a NotificationTypeEnums string inside data. The API returns only redirect_data (via the resource), never the class column, so redirect_data.type is the one that matters to the app.

The model's user() / broker() relations don't match the morph columns

Notification declares user() and broker() morphTo relations (app/Models/Notification.php:25-33), but the table’s polymorphic columns are notifiable_type / notifiable_id (from morphs('notifiable')). Those relations would look for user_type / user_id and broker_type / broker_id, which don’t exist — so they resolve nothing. All real reads go through GetNotifications, which queries notifiable_id / notifiable_type directly (app/Actions/Notification/GetNotifications.php:20-21). Treat user() / broker() as dead relations.

A likely bug in the lead-notification switch (KT item)

In LeadSubmissionNotification, the rejected branch uses assignment, not comparison — case $extractedData['decision'] = LeadAdminVerificationDecisionEnums::REJECTED->value: (app/Actions/User/Broker/LeadSubmissionNotification.php:31). That reassigns decision and evaluates truthy every time the branch is reached, so lead statuses that aren’t NEW / RESERVED / CONTRACTED fall through to a RejectedLead notification. Flag it on the KT tracker rather than relying on the current behaviour.

Where to go next

Notifications (integration)The other half — outbound push / SMS / email delivery, the channel this page is deliberately distinct from.

Broker submits a leadThe lead events (verified / reserved / contracted / rejected) that feed most in-app notification rows.

Commissions and sales invoicesWhere the sales_invoice notification comes from — the approved-invoice observer.

Submitting an EOIThe EOI events (submitted / confirmed / expired) behind the eoi notification type.