analysis/04-functional-spec/notifications-and-messaging-module.md

Notifications & Messaging

Notifications & Messaging Module – Functional Specification

1. Purpose

The Notifications & Messaging Module enables the platform to:

Send system notifications to users (B2C mobile & web)
Allow providers and admins to send text messages directly to customers
Deliver transactional updates related to bookings, payments, trips, and ratings
Integrate with Firebase Push Notifications and SMS providers
Provide an in-dashboard messaging modal for contacting customers

2. Notification Channels

Push Notifications

Firebase Cloud Messaging

SMS

SMS Provider Integration

Email

SMTP / Email Service

In-App

Notification Center

3. Related Entities

Entity	Description
Notification	A system-generated or manual message sent to a user.
Message	A direct message from provider/admin to a customer.
User	Receiver (customer) or sender (admin/provider).
Booking	Provides context for messages.
Trip	Used in contextual notification templates.

4. Notification Entity Fields

Field	Type	Notes
id	PK	—
user_id	FK	Receiver
title	String	—
body	Text	—
type	Enum	booking_update, payment_update, trip_status, rating_request, general
source	Enum	system / admin / provider
deep_link	String	URL or mobile route
read_at	timestamp, nullable	—
created_at	timestamp	—
updated_at	timestamp	—

5. Message Entity Fields

Field	Type	Notes
id	PK	—
sender_id	FK	—
receiver_id	FK	—
booking_id	FK, nullable	—
subject	String	Subject
body	Text	Message text
created_at	timestamp	—

UI fields: 'Customer Name' (auto-filled), 'Mobile Number', 'Subject', 'Message Text'

6. Business Rules

BR-1. Users must receive booking updates

Triggered automatically upon: Successful payment, Booking confirmation, Booking cancellation, Trip completion, Rating request prompt.

BR-2. Admin/Provider can send manual messages

From UI modal: Must provide subject + body. System stores message and optionally sends SMS, Email, Push notification.

BR-3. Notifications must reflect system states

'Your booking is confirmed' → when booking status = Confirmed
'Your booking is cancelled' → when booking status = Cancelled
'Your trip starts tomorrow' → pre-trip reminder
'Please rate your trip' → rating-request after completion

BR-4. Read receipts only apply inside the app

read_at updates only when user opens notification center or specific notification deep link.

BR-5. Messaging is not a live chat

Per UI, the feature is: One-directional, Manual, Not continuous conversation.

BR-6. Notification templates must support Arabic labels exactly as in UI

'Your rating has been submitted successfully'
'Your booking is confirmed successfully'
'Thank you for choosing MASARUK'

BR-7. Provider/Admin cannot message a user with no booking

UI modal is inside Booking Details → messaging is contextual, not global.

7. Actions & Behaviors

A-1. Send Notification (system-triggered)

Occurs on:

Booking completion
Payment update
Trip reminders
Rating request ('How was your trip?')
Trip cancellation

Push → Email → SMS (fallback)

A-2. Send Manual Message

Opens booking
Clicks 'Send message to customer'
Fills: subject, body
Sends
User receives SMS + push

A-3. Mark Notification as Read

Triggered when user views the item.

A-4. Deep Linking

Notification may lead user to: Trip details, Booking details, Rating modal, Payment receipt.

8. Validation Rules

Field	Rule
subject	required, max 120 chars
body	required
receiver_id	must exist
booking_id	must belong to receiver (if provided)
title (notifications)	required
body (notifications)	required

9. Error Cases

Case	Behavior
User blocking SMS	fallback to push + email
Failed push (Firebase)	retry with exponential backoff
Missing phone number	block SMS channel
Notification deep link invalid	open fallback home page
Provider tries messaging wrong user	deny action

11. Cross-Module Relations

Module	Interaction
Bookings	booking status changes trigger notifications
Payments	payment success/failure → transactional notifications
Ratings	after trip completion → rating request and thank-you messages
Trips	trip reminders and updates
RBAC	controls who can send manual messages and to whom
Reports	may log notification delivery stats (future expansion)

12. Message Catalog (Slice 11)

SSOT: analysis/04-functional-spec/notifications-and-messaging-module.md §13

12.1 Channel Policy

Channel	Status	Notes
In-App	[OFFICIAL]	Wording finalized; ready for implementation
Email	[PROPOSED]	Future Planned — backend integration required
SMS	[PROPOSED]	Future Planned — SMS provider required
WhatsApp	[PROPOSED]	Future Planned — WhatsApp Business API required

12.2 Wording Guardrails

WORD-01: No provider contact info in messages (PRIV-01)
WORD-02: No timeline commitments (use 'estimate' + [PROPOSED])
WORD-03: No 'wallet/withdraw/topup' terms (Slice 5)
WORD-04: Arabic labels must match UI exactly (BR-6)
WORD-05: Amounts in SAR (ر.س) only

12.3 Notification Events

Event	In-App	Email/SMS
Booking Confirmed	[OFFICIAL] §13.3	[PROPOSED]
Cancelled by User (DEC-S10-02)	[OFFICIAL] §13.4	[PROPOSED]
Cancelled by Trip Cascade (DEC-S10-03)	[OFFICIAL] §13.5	[PROPOSED]
Refund to Credit (DEC-S5-01)	[OFFICIAL] §13.6	[PROPOSED]
Admin Gift/Compensation (DEC-S5-02)	[OFFICIAL] §13.7	[PROPOSED]

12.4 Forbidden Content

❌ Provider phone/email/WhatsApp (PRIV-01)
❌ Timeline commitments without [PROPOSED]
❌ 'Wallet/محفظة' — Use 'Credit/رصيدي'
❌ 'Withdraw/سحب' or 'Top-up/شحن'

12.5 Glossary — Key Terms (UI Match)

⚠️ All notification text MUST use these exact terms

English	العربية	❌ Forbidden
My Credit	رصيدي	Wallet/محفظة
Refund	استرداد	إرجاع
Confirmed	مؤكد	محجوز
Cancelled	ملغاه	ملغي
SAR	ر.س	ريال/SR
Masaruk	مسارك	—

13. Trigger Map (Slice 12)

SSOT: notifications-and-messaging-module.md §14

Trigger	Message ID	Entity	Variables	Fallback
TRG-01	MSG-13.3	booking_id	booking_ref, trip_name, departure_date	§13.3 fallbacks
TRG-02	MSG-13.4	booking_id	booking_ref, amount, percentage	§13.4 fallbacks
TRG-03	MSG-13.5	booking_id	trip_name, amount	§13.5 fallbacks
TRG-04	MSG-13.6	credit_txn_id	amount, booking_ref, balance	§13.6 fallbacks
TRG-05	MSG-13.7-A	credit_txn_id	amount, balance	§13.7: amount=critical
TRG-06	MSG-13.7-B	credit_txn_id	amount, balance	§13.7: amount=critical
TRG-07	MSG-13.8	booking_id	trip_name	[PROPOSED] §13.8
TRG-08	MSG-13.9	booking_id	trip_name	[PROPOSED] §13.9

✅ S12.5 Coverage: 8/8 triggers ✅ Message ID ✅ Entity ✅ Variables ✅ Fallback

⚠️ NC-RULE-01: Only events with valid Message ID are rendered. Unknown events = discard.

14. UI Placements (Slice 12)

SSOT: notifications-and-messaging-module.md §15

My Bookings

/bookings

Types: TRG-01, TRG-02, TRG-03

Style: Status badge + row highlight

Booking Details

/bookings/{id}

Types: TRG-01, TRG-02, TRG-03

Style: Top banner (dismissible)

My Credit

/my-credit

Types: TRG-03, TRG-04, TRG-05, TRG-06

Style: Transaction row highlight

Notification Center

/account/notifications

Types: ALL

Style: List with read/unread state

Notifications & Messaging

1. Purpose

2. Notification Channels

Push Notifications

SMS

Email

In-App

3. Related Entities

4. Notification Entity Fields

5. Message Entity Fields

6. Business Rules

BR-1. Users must receive booking updates

BR-2. Admin/Provider can send manual messages

BR-3. Notifications must reflect system states

BR-4. Read receipts only apply inside the app

BR-5. Messaging is not a live chat

BR-6. Notification templates must support Arabic labels exactly as in UI

BR-7. Provider/Admin cannot message a user with no booking

7. Actions & Behaviors

A-1. Send Notification (system-triggered)

A-2. Send Manual Message

A-3. Mark Notification as Read

A-4. Deep Linking

8. Validation Rules

9. Error Cases

10. Related APIs

Payload example

11. Cross-Module Relations

12. Message Catalog (Slice 11)

12.1 Channel Policy

12.2 Wording Guardrails

12.3 Notification Events

12.4 Forbidden Content

12.5 Glossary — Key Terms (UI Match)

13. Trigger Map (Slice 12)

14. UI Placements (Slice 12)

My Bookings

Booking Details

My Credit

Notification Center