30. Notifications

Pixally CRM

View test-cases View chunks Edit

☑️ Notifications

Notifications

Functional Requirement Document

BA & Ideation: Deval Chauhan

Reviewed By: Keval Gajjar

Updated Date:10 December 2025
Status:

Version: 1.0

Overview

The Notifications module delivers personalized, role-based alerts to users across Pixally CRM. It consists of three sub-modules: Notification Center (viewing interface), Company Notifications (organization-wide defaults), and Personal Notifications (individual preferences).

1. Notification Center

Purpose: Centralized hub for viewing and interacting with all notifications via the bell icon.

Feature

Description

Bell Icon &Badge

Visible on all screens (top-right); badge shows unread count (max "99+")

Tabs

"All" (default) and "Unread" with count badge

Mark as Read

Click the notification or the "Mark all as read" link

Pagination

"Load More" button; notifications retained indefinitely

Categories

Projects & Events, Messaging, News & Updates, System

Inline CTAs

Pay Now, Decline, Reply, Download, Send Reminder, Update Payment Method

Deep Linking

Click notification → navigate to relevant module/record

Multi-Agency

Contractors see unified notifications across all agencies; auto-context switch on click

Access: All authenticated users | Notifications ordered by: Date received (newest first)

2. Company Notifications

Purpose: Organization-wide notification defaults configured by Agency Owner/Admin.

Setting Category

Notification Types

Channels

Payment Reminders

Upcoming (7 days), Due date, Overdue +2 days, Overdue +5 days

None, SMS, Email

Contractor Reminders

2 days before event, 7 days before event

None, SMS, Email

Snapshot

PDF with project details sent 1 day before event

Off / On

Internal Team

Event reminder (1 week), Lead response alert, Task due, Task completed

None, In-App, Email

Key Rules:

Access: Agency Owner and Admin only
Override Behavior: Sets defaults; does NOT lock personal customization
Multi-Admin: Last save wins (no locking)
Lead Response Alert: Configurable threshold (3, 5, 7, 10, 14 days)
Subscription Gating: Contractor features require Contractor Portal add-on

3. Personal Notifications

Purpose: Individual notification preferences by user role.

Role-Based Notification Categories

Role

Categories Available

Normal Subscriber (Owner, Admin, PM, Staff)

Finance & Invoicing (6), Projects & Events (14), Client & Contractor Activity (6), Post-Production (6), News (1)

Editor

Assignments & Tasks (5), Feedback & Collaboration (4), Payments (1)

Contractor

Project Assignment (6), Deliverables & Tasks (4), Communication (3), Payments (5), Forms & Contracts (5), Security (4)

Client

❌ No settings access — receives all notifications automatically

Gawd Portal

User Activity (2), Payments & Billing (4), Account Status (3), Security (2)

Channel Options

Option

Behavior

None

Notification disabled

In-App

Appears in Notification Center

Email

Sent to registered email

Multi-select allowed: Users can enable both In-App AND Email simultaneously.

Default & Override Logic

Priority: Personal Setting > Company Setting > System Default

New Users: All notifications ON (In-App + Email) by default
Customization: Personal changes override company defaults
Company Changes: Only affect users who haven't customized that setting

User Access Matrix

Role

Notification Center

Personal Settings

Company Settings

Agency Owner

✅

Admin

✅

Project Manager

✅

❌

Staff

✅

❌

Editor

✅

❌

Contractor

✅

❌

Client

✅

❌

Gawd Portal

✅

❌

Key Business Rules

Rule

Description

Default ON

All notifications enabled (In-App + Email) for new users across all roles

Lifetime Retention

Notifications stored indefinitely; newest first

Auto-Save

All setting changes auto-save without explicit save button

Subscription Gating

Post-Production, Contractor Portal features gated by subscription

Multi-Agency Contractors

Unified notification view; click switches agency context automatically

Client Notifications

Non-configurable; follow company payment reminder settings

Deleted Entities

Clicking notification shows "This record no longer exists" error

Additional Notifications (from Client MOM)

Notification

Target Role

Trigger

W9 Annual Reminder

Contractor

Every January

$600 Payment Threshold

Contractor

Cumulative payments exceed IRS threshold

IC Agreement Reminder

Contractor

Weekly if unsigned

Lead Conflict Warning

Normal Subscriber

New lead conflicts with existing booking

Unassigned Contractor Alert

Normal Subscriber

Project booked without contractor

Weekly Summary - Overdue Jobs

Normal Subscriber

Digest of jobs needing assignment

Account Suspended Warning

All Users

Agency payment failure

Dependencies

Type

Key Dependencies

Internal Modules

Projects, Finance, Contracts, Post-Production, Leads, Tasks, User Management, Subscription

External Services

Email (SendGrid/SES), SMS (Twilio), PDF Generation

Infrastructure

Database, Background Job Processor, WebSocket/Real-time Service

☑️ 1. Notification Center

FRD: Notification Center

Product: Pixally CRM | Version: 1.0 | Date: December 11, 2025 | Related FRDs: Company Notifications, Personal Notifications

1. Module Overview

1.1 Module Name

Notification Center

1.2 Purpose

The Notification Center serves as the centralized hub for viewing and interacting with all notifications within Pixally CRM. Accessible via the bell icon positioned in the top-right corner of the application header, it provides users with a unified interface to view, filter, and act upon personalized alerts about important activities occurring throughout the platform. The module supports real-time notification delivery, deep linking to source modules, inline action buttons, and multi-agency notification aggregation for contractors.

1.3 Business Goals

Provide a single, always-accessible location for users to view all their notifications from any screen within the application.
Keep users informed of important activities in real-time through immediate notification delivery and dynamic badge updates on the bell icon.
Enable users to quickly navigate to relevant modules and specific records through deep linking when clicking on notifications.
Allow users to take immediate actions such as signing contracts, processing payments, replying to messages, and downloading files directly from the notification panel without navigating away.
Support efficient notification management through filtering capabilities using All and Unread tabs, mark-as-read functionality, and Load More pagination.
Provide contractors working with multiple agencies a unified view of all notifications with seamless context switching when clicking cross-agency notifications.

2. User Roles & Permissions

2.1 Roles with Access to Notification Center

Role

Access Notification Center

View All Notifications

View Unread Only

Mark as Read

Perform Inline Actions

Navigate via Deep Link

Agency Owner

Yes

Admin

Yes

Project Manager

Yes

Normal User (Staff)

Yes

Editor

Yes

Contractor

Yes

Client

Yes

Gawd Portal User

Yes

2.2 Notification Visibility Scope by Role

Role

Notification Scope

Agency Owner

Receives notifications for all projects and activities across the entire company

Admin

Receives notifications for all projects and activities across the entire company

Project Manager

Receives notifications only for projects they are directly associated with

Normal User (Staff)

Receives notifications only for projects they are directly associated with

Editor

Receives notifications only for post-production boards and tasks they are assigned to

Contractor

Receives notifications for assigned tasks and projects across ALL agencies they work with in a unified view

Client

Receives notifications only for their own project-related activities

Gawd Portal User

Receives platform-wide administrative notifications related to subscriptions, billing, and security

2.3 Permission Details

All authenticated users can access the Notification Center by clicking the bell icon visible on all screens.
Users can only view notifications targeted to them based on their role and project associations.
Deep link navigation is subject to the user's existing permissions in the target module.
Inline action execution is subject to the user's permissions for the specific action being performed.
Contractors can view and interact with notifications from all agencies they are associated with without manual context switching.

3. User Flow

3.1 The user logs into Pixally CRM and lands on any screen within the application.

3.2 The system displays the bell icon in the top-right corner of the header navigation bar on all screens.

3.3 The system displays a numeric badge on the bell icon showing the count of unread notifications, or hides the badge if the count is zero.

3.4 The user clicks on the bell icon to open the Notification Center.

3.5 The system opens the Notification Center as a dropdown panel overlay with a subtle background gradient effect applied to the underlying page.

3.6 The system displays the panel header containing the title "Notifications", a "Mark all as read" link with checkmark icon, and a settings gear icon.

3.7 The system displays two segment tabs below the header labeled "All" and "Unread", with the "All" tab selected by default.

3.8 The system displays the "Unread" tab with a badge showing the count of unread notifications.

3.9 The system loads and displays the notification list below the tabs, sorted by creation timestamp with the newest notifications appearing first.

3.10 The system displays each notification item with a category icon, title message, relative timestamp, context information showing the related project name, and a read/unread visual indicator.

3.11 The user scrolls through the notification list to view older notifications.

3.12 The user clicks on the "Unread" tab to filter the list.

3.13 The system immediately updates the notification list to display only unread notifications.

3.14 The user clicks on the "All" tab to return to the full list.

3.15 The system immediately updates the notification list to display all notifications regardless of read status.

3.16 The user clicks on a notification item that does not have inline action buttons.

3.17 The system marks the clicked notification as read and updates the unread count badge on the bell icon.

3.18 The system closes the Notification Center panel and navigates the user to the relevant module and specific record via deep linking.

3.19 The user returns to a screen and opens the Notification Center again.

3.20 The user identifies a notification with inline action buttons such as "Pay Now" and "Decline".

3.21 The user clicks on the "Pay Now" button within the notification.

3.22 The system opens the payment flow modal or navigates to the payment page without marking the notification as read.

3.23 The user completes the payment action.

3.24 The system updates the notification state to reflect the completed action and removes or disables the action buttons.

3.25 The user clicks on "Mark all as read" link in the panel header.

3.26 The system marks all notifications as read, updates the bell icon badge to show zero or hides it, and updates the Unread tab badge to zero.

3.27 The user scrolls to the bottom of the notification list and sees the "Load More" button.

3.28 The user clicks on "Load More" to fetch additional notifications.

3.29 The system displays a loading indicator while fetching the next batch of notifications.

3.30 The system appends the newly loaded notifications to the bottom of the existing list and maintains the user's scroll position.

3.31 The system hides the "Load More" button when all notifications have been loaded.

3.32 The user clicks outside the Notification Center panel.

3.33 The system closes the Notification Center panel.

3.34 A contractor user who works with multiple agencies opens the Notification Center.

3.35 The system displays notifications from all associated agencies in a unified list, with each notification showing the agency brand identifier.

3.36 The contractor clicks on a notification from a different agency than the currently active one.

3.37 The system automatically switches the contractor's active agency context to the notification's agency.

3.38 The system navigates the contractor to the deep link target within the newly switched agency context.

3.39 The system displays a brief toast notification indicating "Switched to [Agency Name]".

4. Functional Logic

4.1 Bell Icon and Badge Behavior

The bell icon shall be rendered in the top-right corner of the application header and shall remain visible on all authenticated screens regardless of the module the user is viewing.
The bell icon shall display a numeric badge positioned at its top-right corner that shows the total count of unread notifications for the logged-in user.
When the unread notification count is between 1 and 99, the badge shall display the exact numeric count.
When the unread notification count exceeds 99, the badge shall display "99+" to maintain visual consistency and prevent layout overflow issues.
When the unread notification count is zero, the system shall hide the badge completely and display only the bell icon without any numeric indicator.
The badge count shall update in real-time or near real-time whenever a new notification is received or when notifications are marked as read.
Clicking the bell icon shall toggle the Notification Center panel between open and closed states.
The bell icon shall display a hover state with visual feedback to indicate interactivity when the user moves the cursor over it.
The bell icon shall display an active or selected state with distinct styling when the Notification Center panel is currently open.

4.2 Notification Panel Layout and Display

The Notification Center shall open as a dropdown panel overlay anchored to the bell icon and positioned below or adjacent to it.
The panel shall have a fixed width of approximately 380-420 pixels and a maximum height with internal vertical scrolling enabled for the notification list.
When the panel opens, a subtle background overlay with gradient effect shall be applied to the underlying page content to draw visual focus to the notification panel.
The panel header shall display the title "Notifications" aligned to the left side of the header area.
The panel header shall display a "Mark all as read" action link with a checkmark icon aligned to the right side of the header.
The panel header shall display a settings gear icon next to the "Mark all as read" link that navigates users to the Notification Settings page when clicked.
Clicking anywhere outside the panel boundaries shall close the Notification Center panel.
Clicking the bell icon while the panel is open shall close the panel.
The panel shall automatically close when the user navigates away from the current page via a deep link click.

4.3 Tab Filtering Functionality

The Notification Center shall display two segment tabs labeled "All" and "Unread" positioned below the panel header.
The "All" tab shall be selected by default when the Notification Center panel opens.
When the "All" tab is selected, the system shall display all notifications regardless of their read or unread status, sorted by creation timestamp with newest first.
The "Unread" tab shall display a badge showing the current count of unread notifications.
When the "Unread" tab is selected, the system shall filter and display only notifications where the read status is false, sorted by creation timestamp with newest first.
Switching between tabs shall immediately update the displayed notification list without requiring a full page reload.
When the user marks all notifications as read while viewing the Unread tab, the system shall update the list to display an empty state message.
Tab switching shall reset the scroll position to the top of the notification list.

4.4 Notification Item Structure and Display

Each notification item in the list shall display a category-specific icon on the left side that visually represents the notification type such as a document icon for questionnaires, a dollar icon for payments, or a calendar icon for events.
Each notification item shall display a read/unread indicator that visually distinguishes unread notifications through bold text styling, a colored dot, or background highlighting.
Each notification item shall display the primary title or message text describing the event that triggered the notification, formatted with the actor's name in bold.
Each notification item shall display a relative timestamp indicating how long ago the notification was created using formats such as "Just now", "X minutes ago", "X hours ago", "Yesterday", "X days ago", or the date in "MMM DD" format for older notifications.
Each notification item shall display context information in a secondary muted text style showing the related project or event name such as "Jadon & Monika Wedding".
For notifications related to agencies in a multi-agency contractor scenario, each notification shall display the agency brand identifier to help contractors distinguish the source.
Long notification titles or context information that exceeds the available display width shall be truncated with an ellipsis, and the full text shall be displayed in a tooltip on hover.

4.5 Notification Categories and Types

4.5.1 Projects and Events Category

When a client completes and submits a questionnaire, the system shall trigger the "Questionnaire was filled out" notification and deliver it to the Agency Owner, Admin, and Project Manager associated with that project via their configured notification channels.
When a prospective client submits a lead form, the system shall trigger the "Lead form was submitted" notification and deliver it to the Agency Owner and Admin, as well as the designated lead handler if one is assigned.
When a client opens and views a sent proposal, the system shall trigger the "Proposal was viewed" notification and deliver it to the Agency Owner, Admin, and the user who sent the proposal.
When a client completes full payment on an invoice, the system shall trigger the "Invoice was paid" notification and deliver it to the Agency Owner, Admin, and Project Manager associated with that project.
When a booking proposal reaches its expiration date without being signed, the system shall trigger the "Booking proposal expires" notification and deliver it to the Agency Owner, Admin, and Project Manager as a warning indicator.
When a client signs a contract, the system shall trigger the "Contract was signed" notification and deliver it to the Agency Owner, Admin, and Project Manager associated with that project.
When a user uploads a file to a project, the system shall trigger the "File uploaded" notification and deliver it to all team members associated with that project.
When an event date is 5 days away, the system shall trigger the "Upcoming event reminder" notification and deliver it to the Agency Owner, Admin, Project Manager, and assigned contractors for that event.
When a new email is received in the Pixally email system for a project, the system shall trigger the "New email received" notification and deliver it to the project owner and associated team members.
When a task passes its due date without being completed, the system shall trigger the "Overdue tasks" notification and deliver it to the task assignee and the user who created the task.
When a task deadline is approaching based on configured reminder settings, the system shall trigger the "Task reminders" notification and deliver it to the task assignee.
When there is activity in the referral program such as a new referral or conversion, the system shall trigger the "Referral program updates" notification and deliver it to the Agency Owner and Admin.
When a project or event is canceled, the system shall trigger the "Project/Event canceled" notification and deliver it to all team members, assigned contractors, and the client associated with that project.

4.5.2 Messaging Category

When a client or user sends a message through the project messaging system, the system shall trigger the "Message received" notification and deliver it to the intended recipient of the message.
When a user is mentioned using the @ symbol in a conversation or comment, the system shall trigger the "Mentioned you" notification and deliver it specifically to the mentioned user.
When an email is received in the system with full content, the system shall trigger the "Email received" notification with a preview snippet and deliver it to the project owner and associated team members, displaying "Reply" and "Read More" action buttons.

4.5.3 News and Updates Category

When Pixally releases new features, improvements, or version updates, the system shall trigger the "Product updates" notification and deliver it to all active users across the platform with a "Learn More" action button.

4.5.4 System Category

When a new user account is created and the user logs in for the first time, the system shall trigger the "Welcome" notification and deliver it to that specific user as an onboarding message.
When a user's saved payment method is approaching its expiration date, the system shall trigger the "Payment method expiring soon" notification and deliver it to that specific user with an "Update Payment Method" action button.
When a subscription payment fails, the system shall trigger the "Payment failed" notification and deliver it to the Agency Owner and Admin with an "Update Payment Method" action button and a warning about potential account suspension.
When an account is at risk of suspension due to payment issues, the system shall trigger the "Account suspension warning" notification and deliver it to the Agency Owner and all Admin users with urgency indicator styling.

4.6 Notification Actions and Call-to-Action Buttons

Notifications of type "Payment request received" shall display two inline action buttons: "Pay Now" styled as a primary button and "Decline" styled as a secondary outlined button.
When the user clicks "Pay Now", the system shall open the payment flow modal or navigate to the payment page without automatically marking the notification as read.
When the user clicks "Decline" on a payment request notification, the system shall display a confirmation dialog asking the user to confirm the decline action before processing.
Notifications of type "Payment request overdue" shall display a "Send Reminder" action button that sends a reminder notification to the client when clicked.
Notifications of type "File uploaded" shall display the file name, file size in human-readable format, and a "Download" action button that initiates a direct browser download of the file when clicked.
Notifications of type "Message received" or "Email received" shall display "Reply" and "Read More" action buttons where Reply opens a compose modal and Read More navigates to the full message view.
Notifications of type "Product updates" shall display a "Learn More" action button that navigates to the feature announcement page when clicked.
Notifications of type "Payment method expiring" or "Payment failed" shall display an "Update Payment Method" action button styled as a primary button that navigates to the payment settings page when clicked.
Action buttons shall display a loading indicator while the associated action is being processed.
Action buttons shall be disabled or hidden when the associated action is no longer valid, such as when a payment has already been completed.
Clicking an action button shall not automatically mark the notification as read; only clicking the notification body or navigating via deep link shall mark it as read.

4.7 Deep Linking Navigation

When the user clicks on a notification item outside of any action buttons, the system shall navigate the user to the relevant module and specific record referenced in the notification.
Clicking a "Questionnaire was filled out" notification shall navigate to the Project detail page with the Questionnaire tab or modal open.
Clicking a "Lead form submitted" notification shall navigate to the Leads module with the specific lead record open.
Clicking a "Proposal was viewed" notification shall navigate to the Project detail page with the Proposal tab open.
Clicking an "Invoice was paid" or "Payment received" notification shall navigate to the Finance module with the specific invoice or payment detail open.
Clicking a "Contract was signed" notification shall navigate to the Project detail page with the Contract tab open.
Clicking a "File uploaded" notification shall navigate to the Project detail page with the Files tab open.
Clicking a "Message received" or "Email received" notification shall navigate to the Project detail page with the Messages or Email tab open.
Clicking a "Task reminder" or "Overdue task" notification shall navigate to the Tasks module with the specific task open.
Clicking a "Post-production" related notification shall navigate to the Post-Production module with the specific job detail open.
Clicking a "Subscription" or "Billing" related notification shall navigate to the Settings page with the Subscription section open.
Clicking a "Security alert" notification shall navigate to the Settings page with the Security section open.
If the entity referenced in a notification has been deleted, the system shall not navigate and shall instead display an inline error message stating "This record no longer exists".
If the user does not have permission to access the target entity, the system shall display an inline error message stating "You don't have permission to view this item".
The Notification Center panel shall close automatically when the user successfully navigates to a deep link target.

4.8 Mark as Read Functionality

When the user clicks on a notification item, the system shall immediately mark that notification as read by updating its read status in the database.
When a notification is marked as read, the system shall decrement the unread count badge on the bell icon by one.
When a notification is marked as read, the system shall update the Unread tab badge count accordingly.
When a notification is marked as read, the system shall update the visual styling of that notification item from unread to read appearance.
When a notification is marked as read while the user is viewing the Unread tab, the system shall remove that notification from the visible list.
When the user clicks "Mark all as read" in the panel header, the system shall mark all notifications as read, not just the currently visible ones.
After marking all as read, the system shall update the bell icon badge to zero or hide it completely.
After marking all as read, the system shall update the Unread tab badge to zero.
After marking all as read while viewing the Unread tab, the system shall display the empty state message "All caught up! No unread notifications."
Read status changes shall be persisted immediately to the database and shall sync across all devices and sessions for the same user.
Read status shall persist across page refreshes and re-logins.

4.9 Pagination and Load More

When the Notification Center opens, the system shall fetch and display the most recent batch of approximately 50 notifications.
A loading indicator shall be displayed in the panel while the initial notifications are being fetched.
If the user has no notifications, the system shall display an empty state message: "No notifications yet. When you receive notifications, they'll appear here."
When the user scrolls to the bottom of the loaded notification list and more notifications exist, the system shall display a "Load More" button or link.
When the user clicks "Load More", the system shall display an inline loading indicator and fetch the next batch of approximately 50 notifications.
Newly loaded notifications shall be appended to the bottom of the existing list without replacing or reordering the currently displayed notifications.
The user's scroll position shall be maintained after loading more notifications so they can continue from where they were.
When all notifications have been loaded and no more exist, the system shall hide the "Load More" button.
If the Load More operation fails due to a network error, the system shall display an error message "Unable to load more notifications. Please try again." with a retry option.

4.10 Multi-Agency Contractor Notifications

Contractors who are associated with multiple agencies shall see notifications from all their associated agencies in a single unified Notification Center without requiring manual agency switching.
Notifications from all agencies shall be combined into a single list and sorted by creation timestamp with the newest first, regardless of which agency generated the notification.
Each notification in a multi-agency contractor's view shall display the agency brand identifier, which may include the agency logo icon or agency name, to help the contractor identify which agency the notification originated from.
The unread notification count displayed on the bell icon badge shall reflect the total unread count across all associated agencies.
When a contractor clicks on a notification from an agency other than their currently active agency context, the system shall automatically switch the contractor's active agency context to match the notification's source agency.
After the agency context switch, the system shall navigate the contractor to the deep link target within the newly active agency's context.
The system shall display a brief toast notification indicating "Switched to [Agency Name]" to inform the contractor of the context change.
Similar notifications from multiple agencies shall not be aggregated; each notification shall be displayed as a separate item with its respective agency identifier.

4.11 Notification Retention and Storage

Notifications shall be retained indefinitely with no automatic deletion based on age, ensuring users can access their complete notification history.
Notifications shall always be ordered by creation timestamp with the newest notifications appearing first in the list.
The order shall remain consistent across the All and Unread tabs.
Pagination through Load More shall maintain consistent ordering so that users see notifications in a predictable sequence.
Notifications that reference entities that have been deleted shall remain in the notification list but shall display an error message when clicked.
Notifications for deactivated user accounts shall be archived rather than permanently deleted.
Users cannot manually delete individual notifications from the Notification Center; they can only mark them as read.

4.12 Page Refresh Updates and Synchronization

When the user refreshes the page or navigates to the Notification Center, the system shall fetch and display the latest notifications, with any new notifications appearing at the top of the list.
The bell icon badge count shall update upon page load to reflect the current unread notification count.
If a user marks a notification as read on one device, the read status shall sync to the server and be reflected on other devices upon their next page refresh.
The system shall retrieve notification updates from the server on each page load to ensure notifications are current.

4.12 Real-Time Updates and Synchronization

When a new notification is generated for the user while they have the Notification Center panel open, the system shall prepend the new notification to the top of the list with a highlight animation.
The bell icon badge count shall increment in real-time when new notifications arrive.
If a user marks a notification as read on one device, the read status shall sync to other devices where the user is logged in.
If the real-time notification service is unavailable, the system shall fall back to polling-based updates to ensure notifications are eventually displayed.

5. Field Details & Validations

Field Name

Field Type

Validation Rules

notification_id

UUID

System-generated unique identifier; primary key; read-only

user_id

UUID

Required; must reference an existing user in the users table; foreign key

agency_id

UUID

Required; must reference an existing agency in the agencies table; used for multi-agency contractor filtering

6. Success Message Handling

Operation

Success Message

Trigger Condition

Post-Success Action

Mark all as read

"All notifications marked as read"

User clicks "Mark all as read" link and the operation completes successfully

Update bell icon badge to zero or hide it; update Unread tab badge to zero; refresh notification list styling to show all as read

Mark single notification as read

No visible message (silent operation)

User clicks on a notification item

Update notification styling to read state; decrement bell icon badge by one; decrement Unread tab badge by one

Navigate via deep link

No visible message (silent operation)

User clicks notification and navigation succeeds

Close Notification Center panel; navigate to target module and record

Download file from notification

"Download started"

User clicks Download button on a file notification

Initiate browser file download

Pay Now action initiated

"Redirecting to payment..."

User clicks Pay Now button

Open payment flow modal or navigate to payment page

Reply action initiated

No visible message

User clicks Reply button

Open compose or reply modal

Send Reminder action

"Reminder sent successfully"

User clicks Send Reminder button and the operation completes

Update notification state to indicate reminder was sent

Decline payment request

"Payment request declined"

User confirms decline action in the confirmation dialog

Update notification to reflect declined state; remove or disable action buttons

Load more notifications

No visible message (silent operation)

User clicks Load More and fetch completes successfully

Append new notifications to list; hide Load More if no more exist

Agency context switch

"Switched to [Agency Name]" (toast notification)

Contractor clicks cross-agency notification

Switch active agency context; navigate to deep link target

7. Error Message Handling

Error Scenario

Error Message

Trigger Condition

User Action Required

System Response

Referenced entity deleted

"This record no longer exists"

User clicks notification for an entity that has been deleted

None; informational only

Display error inline within notification panel; do not navigate

Permission denied for entity

"You don't have permission to view this item"

User clicks notification but lacks access permission to the target entity

Contact administrator for access

Display error inline within notification panel; do not navigate

Failed to load notifications

"Unable to load notifications. Please try again."

API request to fetch notifications fails due to server error

Click retry button or refresh page

Display error message with retry button in panel

Failed to mark as read

"Unable to update notification. Please try again."

API request to mark notification as read fails

Try the action again

Display error toast; revert notification UI to previous state

Failed to load more notifications

"Unable to load more notifications. Please try again."

API request for pagination fails

Click Load More again

Display error inline below the list; keep existing notifications visible

Network connectivity lost

"You appear to be offline. Please check your connection."

System detects no network connectivity

Restore network connection

Display offline indicator; disable interactive actions

CTA action failed

"Unable to complete action. Please try again."

API call for an inline action such as Send Reminder fails

Try the action again

Display error toast; keep action button enabled for retry

File download failed

"Unable to download file. Please try again."

File download request fails

Try download again

Display error toast

Invalid deep link

"This page is no longer available"

Deep link route does not exist or is malformed

None; informational only

Display error inline; do not navigate

Agency context switch failed

"Unable to switch agency. Please try again."

Agency context switch operation fails for contractor

Try clicking notification again

Display error toast; remain in current agency context

Session expired

"Your session has expired. Please log in again."

Authentication token has expired during an action

Redirect to login page

Real-time connection lost

"Live updates paused. Notifications may be delayed."

WebSocket connection to real-time service is lost

None; automatic reconnection attempted

Fall back to polling; display warning indicator; attempt reconnection

8. Edge Cases

Edge Case Scenario

Description

Expected System Behavior

No notifications exist

New user with no activity has zero notifications

Display empty state illustration with message: "No notifications yet. When you receive notifications, they'll appear here."

All notifications read on Unread tab

User marks all as read while viewing Unread tab

Display empty state with message: "All caught up! No unread notifications."

Extremely high notification volume

User receives more than 100 notifications in a short time period

Paginate display with Load More; badge displays "99+" when unread count exceeds 99

Rapid new notifications

Multiple notifications arrive while panel is open

Prepend each new notification to the list with highlight animation; increment badge in real-time

Duplicate notification triggers

Same event triggers notification multiple times within a short window

System deduplicates identical notifications within a 5-minute window; only one notification displayed

Concurrent read status updates

User marks notification as read on mobile while desktop panel is open

Sync read status across devices; desktop UI updates accordingly on next sync

Notification content overflow

Title or context text exceeds display width

Truncate with ellipsis; display full text in tooltip on hover

File name overflow

Uploaded file has a very long file name

Truncate middle portion of filename with ellipsis; preserve file extension

Multiple CTAs exceed space

Notification has more than two action buttons

Display first two CTAs inline; show additional actions in overflow menu

CTA action no longer valid

User clicks Pay Now but payment was already completed

Hide or disable the CTA button; if clicked, display message "This action is no longer available"

Deep link to archived entity

Notification links to a project that has been archived

Navigate to archived view with notice: "This item has been archived"

Contractor removed from agency

Contractor has notification from agency they were removed from

Notification remains visible; deep link displays access denied error

New notification while panel open

New notification arrives while user is viewing panel

Prepend notification to list with highlight; increment badge without disrupting user's view

Timezone differences

User in different timezone than event

Display all timestamps converted to user's local timezone

Notification during maintenance

System maintenance window is active

Queue notifications on server; deliver and display after maintenance completes

Very old notifications

User scrolls to access notifications from months ago

Continue displaying with proper date format "MMM DD, YYYY" for previous year

Read status sync failure

Network fails after locally marking notification as read

Retry sync on reconnection; show warning if sync fails persistently

Browser notifications blocked

User has blocked browser notification permissions

Rely solely on in-app Notification Center; no error displayed

Scroll position after tab switch

User scrolls down in All tab then switches to Unread

Reset scroll position to top when switching tabs

Rapid successive clicks

User clicks same notification multiple times quickly

Debounce click events; prevent multiple navigation attempts

Zero-state badge

Unread count reaches exactly zero

Hide badge completely rather than displaying "0"

9. Acceptance Criteria

9.1 Bell Icon and Badge

The bell icon must be visible in the top-right header area on all authenticated screens throughout the application.
The badge must display the correct unread notification count between 1 and 99.
The badge must display "99+" when the unread count exceeds 99.
The badge must be hidden when the unread count is zero.
The badge must update in real-time when new notifications arrive.
The badge must decrement immediately when notifications are marked as read.
Clicking the bell icon must toggle the notification panel open and closed.

9.2 Notification Panel

The panel must open as a dropdown overlay when the bell icon is clicked.
The panel header must display "Notifications" title, "Mark all as read" link, and settings gear icon.
Clicking outside the panel must close it.
Clicking the bell icon while the panel is open must close it.
A subtle background overlay must appear when the panel is open.

9.3 Tab Filtering

"All" and "Unread" tabs must be displayed below the header.
"All" tab must be selected by default when the panel opens.
"Unread" tab must display a badge with the unread count.
Switching to "Unread" tab must filter the list to show only unread notifications.
Switching to "All" tab must show all notifications regardless of read status.
Tab switching must be immediate without page reload.
Empty state messages must display correctly for each tab scenario.

9.4 Notification Display

Notifications must be sorted by timestamp with newest first.
Each notification must display the correct category icon.
Notification title and message must display correctly formatted with actor name in bold.
Timestamps must display in relative format appropriate to the age of the notification.
Context information showing project name must display correctly.
Unread notifications must be visually distinct from read notifications.
Long content must be truncated with ellipsis.

9.5 Call-to-Action Buttons

Inline CTAs must display for applicable notification types.
"Pay Now" CTA must open the payment flow when clicked.
"Decline" CTA must show confirmation dialog and process decline when confirmed.
"Download" CTA must initiate file download when clicked.
"Reply" CTA must open compose modal when clicked.
"Read More" CTA must navigate to full content when clicked.
"Send Reminder" CTA must send reminder and show success message when clicked.
"Update Payment Method" must navigate to payment settings when clicked.
CTAs must show loading state during processing.
CTAs must be disabled or hidden when the action is no longer valid.

9.6 Deep Linking

Clicking a notification must navigate to the correct module and specific record.
Navigation must close the notification panel.
Clicking a notification must mark it as read automatically.
Notifications for deleted entities must show "record no longer exists" error.
Notifications for inaccessible entities must show permission denied error.
All notification types must have correctly configured deep link targets.

9.7 Mark as Read

Clicking a notification must mark that individual notification as read.
"Mark all as read" must mark all notifications as read.
Bell icon badge must update immediately after marking as read.
Unread tab badge must update accordingly.
Read status must persist across page refresh.
Read status must sync across multiple devices.

9.8 Pagination

Initial load must display approximately 50 notifications.
"Load More" button must appear at the bottom of the list when more notifications exist.
Clicking "Load More" must fetch and append additional notifications.
Loading indicator must display during the fetch operation.
"Load More" must be hidden when all notifications have been loaded.
Scroll position must be maintained after loading more notifications.

9.9 Multi-Agency Contractor

Contractors must see notifications from all associated agencies in a unified view.
Agency identifier must be visible on each notification.
Clicking a cross-agency notification must automatically switch the agency context.
Navigation must work correctly after context switch.
Unread count must reflect total across all agencies.

9.10 Performance and Reliability

Notification panel must open within 500 milliseconds.
Initial notifications must load within 2 seconds.
Real-time updates must work without requiring page refresh.
Error states must display appropriate messages with retry options.
Retry functionality must work correctly for all failed operations.

10. Manual Test Cases

The complete manual test cases for the Notification Center module are provided in a separate Excel file.

Test Case Document: TestCases-Notification-Center.xlsx

11. Dependencies

Dependency Type

Dependency Name

Description

Impact if Unavailable

Internal Module

User Management

Provides user authentication, role information, and permission data

Cannot determine notification visibility or user permissions; module will not function

Internal Module

Projects

Provides project entity data and associations for deep linking

Project-related notification deep links will fail; navigation will show error

Internal Module

Finance & Invoicing

Provides invoice and payment entity data for deep linking

Finance notification deep links will fail; payment CTAs will not function

Internal Module

Contracts

Provides contract entity data for deep linking

Contract notification deep links will fail

Internal Module

Lead Management

Provides lead entity data for deep linking

Lead notification deep links will fail

Internal Module

Tasks

Provides task entity data for deep linking

Task notification deep links will fail

Internal Module

Messaging/Email

Provides message and email entity data for deep linking

Message notification deep links will fail; Reply CTA will not function

Internal Module

Post-Production

Provides job and workflow entity data for deep linking

Post-production notification deep links will fail

Internal Module

Files/Documents

Provides file storage and download URLs

Download CTA will fail; file notifications will show errors

Internal Service

Notification Service

Backend service that processes, stores, and delivers notifications

No notifications will be generated or displayed; complete module failure

Internal Service

Real-Time Service

WebSocket-based service for live notification delivery

Fall back to polling; notifications will be delayed; badge updates will lag

External Service

CDN

Content delivery network for static assets including icons

Notification category icons may not display

Infrastructure

Database

Primary data store for notification records

Complete module failure; no notifications can be read or written

Infrastructure

Cache (Redis)

Caches unread counts and frequently accessed notification data

Slower count calculations; increased database load

API

Notification API

REST API endpoints for notification CRUD operations

Module will not function; all operations will fail

API

Entity APIs

REST API endpoints for validating entity existence

Deep link validation will fail; navigation may encounter errors

12. References

Figma:https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=13441-278861&t=b6Vb2HmYBAZOvvUn-0

☑️ 2. Company Notifications

FRD: Company Notifications

Product: Pixally CRM | Version: 1.0 | Date: December 11, 2025 | Related FRDs: Notification Center, Personal Notifications

1. Module Overview

1.1 Module Name

Company Notifications

1.2 Purpose

The Company Notifications module enables Agency Owners and Admins to configure organization-wide notification settings that establish default behaviors for all users within their agency. This centralized control mechanism allows leadership to define consistent communication standards for client-facing payment reminders, contractor job reminders, project snapshots, and internal team alerts. Company Notification settings serve as baseline defaults that can be overridden by individual users through their Personal Notification settings.

1.3 Business Goals

Provide Agency Owners and Admins with centralized control to configure company-wide notification defaults from a single administrative interface.
Ensure all clients receive standardized payment reminder communications according to the company's defined schedule and policies.
Enable systematic reminder schedules for contractors regarding upcoming jobs to maintain operational readiness and reduce no-shows.
Establish default notification behaviors for internal team members to ensure consistent awareness of important business events such as lead follow-ups and task completions.
Allow business owners to configure notification timing that aligns with their specific business processes and client communication preferences.
Gate advanced notification features based on subscription tiers to drive plan upgrades and monetization.

2. User Roles & Permissions

2.1 Roles with Access to Company Notifications

Role

View Company Notifications Tab

Modify Company Settings

Configure Payment Reminders

Configure Contractor Reminders

Configure Snapshot

Configure Internal Reminders

Agency Owner

Yes

Admin

Yes

Project Manager

Normal User (Staff)

Editor

Contractor

Client

Gawd Portal User

2.2 Permission Details

Only Agency Owner and Admin roles can view the "Company Notifications" tab in the Notification Settings page.
Users with any other role will see only the "Personal Notifications" tab when accessing Settings > Notifications.
The Company Notifications tab is completely hidden for unauthorized users rather than being displayed as disabled.
Both Agency Owner and Admin have identical permissions within Company Notifications with no hierarchy between them.
Multiple Admins and Agency Owners can access and edit Company Notifications simultaneously using a last-write-wins approach for concurrent edits.
If a non-authorized user attempts to access the Company Notifications URL directly, they shall be redirected to Personal Notifications with an error message.

3. User Flow

3.1 The Agency Owner or Admin logs into Pixally CRM and navigates to the Settings area from the main navigation menu.

3.2 The system displays the Settings page with various configuration options in the sidebar.

3.3 The user clicks on "Notifications" in the settings sidebar.

3.4 The system loads the Notification Settings page and displays two tabs: "Personal Notifications" and "Company Notifications".

3.5 The user clicks on the "Company Notifications" tab.

3.6 The system displays the Company Notifications settings panel with all configurable sections: Payment Reminders, Contractor Reminders, Snapshot, and Internal Team Reminders.

3.7 The user locates the Payment Reminders section showing four reminder types: Upcoming, Due date, Overdue (+2 days), and Overdue (+5 days).

3.8 The user clicks on the SMS toggle for the "Upcoming" payment reminder to enable SMS delivery.

3.9 The system immediately saves the setting and displays a brief success indicator confirming the change.

3.10 The user clicks on the Email toggle for the same reminder to enable both SMS and Email delivery simultaneously.

3.11 The system saves the multi-channel selection and confirms the update.

3.12 The user scrolls to the Contractor Reminders section showing two reminder types: 2 days before and 7 days before event.

3.13 The user enables SMS and Email for the 7-day contractor reminder.

3.14 The system saves the contractor reminder settings.

3.15 The user locates the Snapshot section with a toggle for "Send automatically one day before events".

3.16 The user enables the Snapshot toggle.

3.17 The system saves the setting and displays confirmation that snapshots will be sent automatically before events.

3.18 The user scrolls to the Internal Team Reminders section.

3.19 The user locates the lead response alert setting with a dropdown for configuring the number of days.

3.20 The user changes the dropdown value from 7 days to 5 days.

3.21 The system saves the updated lead response threshold.

3.22 The user enables In-App and Email for the task due date reminder.

3.23 The system saves the internal reminder settings.

3.24 The user navigates away from the Company Notifications page.

3.25 Another Admin logs in and navigates to Company Notifications.

3.26 The system displays the same settings configured by the first admin, reflecting the shared company-wide configuration.

4. Functional Logic

4.1 Access and Visibility Rules

The Notification Settings page shall display two tabs when accessed by an Agency Owner or Admin: "Personal Notifications" and "Company Notifications".
The "Company Notifications" tab shall be completely hidden and not rendered for users with Project Manager, Staff, Editor, Contractor, Client, or Gawd Portal roles.
Users without Agency Owner or Admin roles shall see only the "Personal Notifications" content without any tab interface when accessing Settings > Notifications.
Tab visibility shall be determined by the user's role at the time of page load, and a role change requires a page refresh to update the visible tabs.
If a user without proper authorization attempts to access the Company Notifications URL directly through browser manipulation, the system shall redirect them to the Personal Notifications page and display an error message stating "You don't have permission to access company notification settings".
The Company Notifications settings shall be accessible at the navigation path: Settings > Notifications > Company Notifications tab.

4.2 Company Settings Override Behavior

Company Notification settings shall establish the default notification preferences that apply to all users within the organization.
When a new user is created or joins the agency, their personal notification settings shall be initialized with the current company default values.
Company settings shall not lock or prevent users from customizing their own preferences in Personal Notifications; users can always override company defaults.
When determining which setting to apply for a specific notification, the system shall use the following priority hierarchy: Personal Notification setting takes highest priority if the user has customized it, Company Notification setting applies if the user has not customized that specific preference, and System Default applies if no company setting exists.
When an Admin or Agency Owner updates a Company Notification setting, the change shall apply immediately to all users who have not customized that specific setting in their Personal Notifications.
Company setting updates shall not retroactively change or overwrite existing personal customizations that users have already made.
For notification types not configured at the company level during initial setup, system defaults shall apply with all notifications enabled via In-App and Email channels.

4.3 Multi-Admin Concurrent Editing

Multiple Admins or Agency Owners can access and view the Company Notifications settings page simultaneously without any locking mechanism.
The system shall use a "last write wins" approach when multiple administrators save conflicting changes to the same setting.
When Admin A saves a setting while Admin B is viewing the same page, Admin A's change shall be persisted immediately to the database.
Admin B's view shall not automatically update in real-time; Admin B must refresh the page to see changes made by Admin A.
If Admin B makes a subsequent change without refreshing, Admin B's change shall overwrite Admin A's previous change.
The system shall not display any conflict notification or warning when concurrent edits occur.

4.4 Payment Reminders Configuration

4.4.1 Payment Reminder Types and Timing

The system shall provide four configurable payment reminder types that are sent to clients regarding their invoice payments.
The "Upcoming" payment reminder shall be triggered and delivered 7 days prior to the invoice due date to give clients advance notice.
The "Due date" payment reminder shall be triggered and delivered on the exact payment due date as a same-day reminder.
The "Overdue (+2 days)" payment reminder shall be triggered and delivered 2 days after the invoice due date has passed as a first overdue notice.
The "Overdue (+5 days)" payment reminder shall be triggered and delivered 5 days after the invoice due date has passed as a second overdue escalation notice.

4.4.2 Payment Reminder Trigger Logic and Recipients

When an invoice is created with a due date, the system shall schedule the applicable payment reminders based on the company's enabled reminder types and channels.
The Upcoming payment reminder shall be triggered when the system date reaches 7 days before the invoice due date, and shall be delivered to the primary client contact associated with the invoice.
The Due date payment reminder shall be triggered when the system date matches the invoice due date, and shall be delivered to the primary client contact associated with the invoice.
The Overdue (+2 days) payment reminder shall be triggered when the system date reaches 2 days past the invoice due date and the invoice remains unpaid, and shall be delivered to the primary client contact.
The Overdue (+5 days) payment reminder shall be triggered when the system date reaches 5 days past the invoice due date and the invoice remains unpaid, and shall be delivered to the primary client contact.
If the client completes payment before a scheduled reminder is due to be sent, the system shall cancel that reminder and not deliver it.
If a payment attempt fails, separate payment failure notifications shall be triggered independently from these reminder schedules.

4.4.3 Payment Reminder Channel Options

Each payment reminder type shall have three channel options displayed as toggle buttons: None, SMS, and Email.
The SMS and Email channels shall function as independent toggles that can be enabled simultaneously, allowing multi-channel delivery.
When both SMS and Email are enabled for a reminder type, the client shall receive the reminder through both channels when triggered.
Selecting "None" shall disable the reminder entirely, preventing delivery through any channel.
The default setting for all payment reminder types shall be SMS and Email both enabled.
SMS delivery requires that the client has a valid phone number on file; if no phone number exists, only email shall be sent.

4.5 Contractor Reminders Configuration

4.5.1 Contractor Reminder Types and Timing

The system shall provide two configurable contractor reminder types that are sent to contractors regarding their upcoming assigned jobs.
The "Upcoming Job Reminder (7 days before)" shall be triggered and delivered 7 days prior to the event date to give contractors advance notice.
The "Upcoming Job Reminder (2 days before)" shall be triggered and delivered 2 days prior to the event date as a final confirmation reminder.

4.5.2 Contractor Reminder Trigger Logic and Recipients

When a contractor is assigned to a project with an event date, the system shall schedule the applicable contractor reminders based on the company's enabled reminder types and channels.
The 7-day contractor reminder shall be triggered when the system date reaches 7 days before the assigned event date, and shall be delivered to the contractor assigned to that specific event.
The 2-day contractor reminder shall be triggered when the system date reaches 2 days before the assigned event date, and shall be delivered to the contractor assigned to that specific event.
If multiple contractors are assigned to the same event, each contractor shall receive their own individual reminder.
If a contractor is removed from a project before the scheduled reminder date, the system shall cancel the pending reminders for that contractor.
Contractor reminders shall include essential event details in the notification content: event date, time, location, project name, and assigned role.
The 2-day reminder may include a request for the contractor to confirm their attendance, and SMS responses can be tracked for confirmation status.

4.5.3 Contractor Reminder Channel Options

Each contractor reminder type shall have three channel options: None, SMS, and Email.
SMS and Email can be enabled simultaneously for multi-channel delivery to contractors.
Selecting "None" shall disable that specific reminder timing entirely.
The default setting for contractor reminders shall be SMS and Email both enabled.
SMS confirmations from contractors shall be tracked and displayed on the contractor dashboard and project detail page.

4.6 Snapshot Configuration

4.6.1 Snapshot Purpose and Content

The Snapshot feature shall generate and send a comprehensive PDF document to contractors containing all vital project information before their assigned events.
The Snapshot PDF shall include: event date and time, event location and venue address, client contact information, project owner contact information, event timeline and schedule, contractor's assigned role, special instructions or notes, names of other assigned team members, and emergency contact information.
The Snapshot is designed for contractors who may not have reliable internet access at event locations, providing them with offline-accessible information.

4.6.2 Snapshot Trigger Logic and Recipients

When the Snapshot setting is enabled and the system date reaches 1 day before an event date, the system shall trigger snapshot generation for all contractors assigned to that event.
The generated Snapshot PDF shall be delivered via email to each assigned contractor's registered email address.
One unique Snapshot shall be generated per contractor per event, personalized with that contractor's specific role and relevant information.
If a contractor is assigned to multiple events on the same day, they shall receive multiple separate Snapshot PDFs, one for each event.
If a contractor is removed from the project before the Snapshot delivery date, the system shall not generate or send a Snapshot to that contractor.
If Snapshot generation fails due to a technical error, the failure shall be logged and administrators can manually trigger Snapshot generation.

4.6.3 Snapshot Settings

The Snapshot section shall display a single toggle setting labeled "Send automatically one day before events".
The toggle shall have two states: Off (disabled) and On (enabled).
The timing of 1 day before the event is fixed and not configurable in the current version.
Snapshot delivery uses email only since it involves a PDF attachment; SMS is not applicable.
The default setting for Snapshot shall be Off (disabled).

4.7 Internal Team Reminders Configuration

4.7.1 Internal Reminder Types

The system shall provide four configurable internal team reminder types that are sent to agency staff members.
The "Event reminder (1 week before)" shall notify the primary user about upcoming event dates on their assigned projects.
The "Lead response alert" shall notify the primary user when a new lead has not been responded to within a configurable number of days.
The "Task due date reminder" shall notify the task assignee when their assigned task reaches its due date.
The "Task completed notification" shall notify the user who created a task when that task is marked as completed by the assignee.

4.7.2 Internal Reminder Trigger Logic and Recipients

The Event reminder (1 week before) shall be triggered when the system date reaches 7 days before a project's event date, and shall be delivered to the primary user designated on that project.
The Lead response alert shall be triggered when a lead's age exceeds the configured threshold (default 7 days) without any response activity, and shall be delivered to the Agency Owner, Admin, or designated lead handler.
A lead shall be considered "responded to" when any of the following actions occur: an email is sent to the lead from within Pixally, a phone call is logged against the lead, the lead status is changed to "Contacted" or a subsequent status, or a proposal is sent to the lead.
Simply viewing the lead record shall not count as a response for the purposes of the lead response alert.
The Lead response alert shall trigger only once per lead; it shall not repeat for the same lead.
The Task due date reminder shall be triggered when the system date matches a task's due date and the task is not yet completed, and shall be delivered to the user assigned to that task.
The Task completed notification shall be triggered when a task's status is changed to completed, and shall be delivered to the user who originally created that task.

4.7.3 Lead Response Alert Days Configuration

The Lead response alert shall include a dropdown selector allowing administrators to configure the number of days threshold.
The dropdown shall offer the following options: 3 days, 5 days, 7 days, 10 days, and 14 days.
The default value for the lead response days shall be 7 days.
When the dropdown value is changed, the system shall immediately save the new threshold and apply it to all future lead response calculations.

4.7.4 Internal Reminder Channel Options

Each internal reminder type shall have three channel options: None, In-App, and Email.
In-App and Email can be enabled simultaneously for multi-channel delivery to staff members.
Selecting "None" shall disable that specific internal reminder entirely.
The default setting for all internal reminders shall be In-App and Email both enabled.
SMS is not available for internal team reminders; only In-App and Email channels are offered.

4.8 Subscription-Based Feature Restrictions

Certain Company Notification features shall be gated based on the agency's current subscription tier.
Payment Reminders shall be available to all subscribers on the base plan with no additional subscription required.
Contractor Reminders shall require the Contractor Portal add-on subscription; without this subscription, the Contractor Reminders section shall be hidden or displayed as disabled with an upgrade prompt.
Snapshot configuration shall require the Contractor Portal add-on subscription; without this subscription, the Snapshot section shall be hidden or displayed as disabled.
Internal Team Reminders shall be available to all subscribers on the base plan.
The SMS delivery channel shall require the SMS add-on subscription; without this subscription, the SMS toggle shall be disabled with a tooltip indicating "SMS notifications require an active SMS add-on subscription".
Features requiring a higher subscription tier shall display a lock icon and "Upgrade" link that navigates to the subscription settings page.
Subscription status shall be validated at page load, and if a subscription lapses mid-session, existing saved settings shall remain but shall not be enforced until the subscription is renewed.

4.9 Settings Auto-Save Behavior

All Company Notification setting changes shall be automatically saved immediately upon user interaction with any toggle, dropdown, or control.
No explicit "Save" button shall be required or displayed for saving Company Notification settings.
When a setting is successfully saved, a brief visual indicator such as a checkmark animation or success toast shall appear to confirm the save.
If a save operation fails due to a network error or server issue, the UI shall revert to the previous setting state and display an error message "Unable to save setting. Please try again."
Company Notification settings shall be stored at the agency level, associated with the agency_id rather than individual user IDs.
All Admins and Agency Owners access and modify the same shared settings record for their agency.

5. Field Details & Validations

Field Name

Field Type

Validation Rules

setting_id

UUID

System-generated unique identifier; primary key

agency_id

UUID

Required; must reference an existing agency; foreign key; one settings record per agency

created_at

DateTime

System-generated timestamp when settings record was created

updated_at

DateTime

System-updated timestamp on any setting modification

updated_by

UUID

Required on update; must reference a valid user ID; tracks last modifier

payment_reminder_upcoming_sms

Boolean

Default: true; enables SMS for upcoming payment reminder

payment_reminder_upcoming_email

Boolean

Default: true; enables Email for upcoming payment reminder

payment_reminder_due_sms

Boolean

Default: true; enables SMS for due date payment reminder

payment_reminder_due_email

Boolean

Default: true; enables Email for due date payment reminder

payment_reminder_overdue_2_sms

Boolean

Default: true; enables SMS for +2 days overdue reminder

payment_reminder_overdue_2_email

Boolean

Default: true; enables Email for +2 days overdue reminder

payment_reminder_overdue_5_sms

Boolean

Default: true; enables SMS for +5 days overdue reminder

payment_reminder_overdue_5_email

Boolean

Default: true; enables Email for +5 days overdue reminder

contractor_reminder_2day_sms

Boolean

Default: true; enables SMS for 2-day contractor reminder

contractor_reminder_2day_email

Boolean

Default: true; enables Email for 2-day contractor reminder

contractor_reminder_7day_sms

Boolean

Default: true; enables SMS for 7-day contractor reminder

contractor_reminder_7day_email

Boolean

Default: true; enables Email for 7-day contractor reminder

snapshot_enabled

Boolean

Default: false; enables automatic snapshot delivery

snapshot_days_before

Integer

Default: 1; fixed value in current version; days before event to send snapshot

event_reminder_week_before_inapp

Boolean

Default: true; enables In-App for weekly event reminder

event_reminder_week_before_email

Boolean

Default: true; enables Email for weekly event reminder

lead_response_alert_inapp

Boolean

Default: true; enables In-App for lead response alert

lead_response_alert_email

Boolean

Default: true; enables Email for lead response alert

lead_response_alert_days

Integer

Default: 7; allowed values: 3, 5, 7, 10, 14; days threshold for lead response

task_due_reminder_inapp

Boolean

Default: true; enables In-App for task due reminder

task_due_reminder_email

Boolean

Default: true; enables Email for task due reminder

task_completed_notification_inapp

Boolean

Default: true; enables In-App for task completed notification

task_completed_notification_email

Boolean

Default: true; enables Email for task completed notification

6. Success Message Handling

Operation

Success Message

Trigger Condition

Post-Success Action

Enable payment reminder SMS

"Payment reminder settings updated"

User enables SMS toggle for any payment reminder type

Save setting to database; display brief checkmark indicator

Enable payment reminder Email

"Payment reminder settings updated"

User enables Email toggle for any payment reminder type

Save setting to database; display brief checkmark indicator

Disable payment reminder channel

"Payment reminder settings updated"

User disables SMS or Email for a payment reminder

Save setting to database; update toggle visual state

Select None for payment reminder

"Payment reminder settings updated"

User selects None, disabling all channels for a reminder

Save setting; deselect both SMS and Email toggles

Enable contractor reminder

"Contractor reminder settings updated"

User enables SMS or Email for contractor reminder

Save setting to database; update UI state

Disable contractor reminder

"Contractor reminder settings updated"

User selects None for a contractor reminder

Save setting; disable that reminder timing

Enable snapshot

"Snapshot will be sent automatically before events"

User toggles Snapshot to On

Save setting; display confirmation message

Disable snapshot

"Snapshot has been disabled"

User toggles Snapshot to Off

Save setting; update toggle visual state

Update lead response days

"Lead response alert updated to [X] days"

User changes dropdown selection

Save new threshold; apply to future calculations

Enable internal reminder In-App

"Reminder settings updated"

User enables In-App for any internal reminder

Save setting to database

Enable internal reminder Email

"Reminder settings updated"

User enables Email for any internal reminder

Save setting to database

Disable internal reminder

"Reminder settings updated"

User disables an internal reminder channel

Save setting; update toggle state

Any setting auto-saved

Brief checkmark animation (no text)

Any toggle or dropdown change saved successfully

Visual feedback without modal interruption

7. Error Message Handling

Error Scenario

Error Message

Trigger Condition

User Action Required

System Response

Unauthorized access attempt

"You don't have permission to access company notification settings"

Non-admin user attempts to access Company Notifications via direct URL

None; automatic redirect

Redirect user to Personal Notifications page

Failed to load settings

"Unable to load company notification settings. Please try again."

API request to fetch company settings fails

Refresh page or click retry button

Display error message with retry button

Failed to save setting

"Unable to save setting. Please try again."

API request to save a setting change fails

Try making the change again

Revert toggle/dropdown to previous state; display error toast

SMS subscription required

"SMS notifications require an active SMS add-on subscription"

User attempts to enable SMS without SMS subscription

Upgrade subscription to add SMS

Disable SMS toggle; display tooltip with upgrade link

Contractor Portal subscription required

"Contractor reminders require the Contractor Portal subscription"

User without Contractor Portal tries to access contractor settings

Upgrade subscription

Hide or disable contractor reminder section; show upgrade prompt

Network connectivity lost

"You appear to be offline. Changes cannot be saved."

System detects no network connectivity

Restore network connection

Disable all toggles and dropdowns; show offline indicator

Invalid dropdown selection

"Invalid selection. Please choose from available options."

Corrupted or tampered dropdown value submitted

Select a valid option from dropdown

Reject save; revert dropdown to previous valid value

Session expired

"Your session has expired. Please log in again."

Authentication token expired during interaction

Redirect to login page

Agency record not found

"Company settings could not be found. Please contact support."

Agency record is missing or database error

Contact support

Display error; prevent any setting changes

Lead response days out of range

"Please select a valid number of days (3, 5, 7, 10, or 14)"

Invalid day value submitted outside allowed options

Select valid option

Reject save; maintain previous value

8. Edge Cases

Edge Case Scenario

Description

Expected System Behavior

New agency first access

Agency created but no company notification settings exist yet

System creates default settings record with all reminders enabled and default values applied

First admin configures settings

Admin accesses Company Notifications for the first time

Load default settings; all reminders enabled with SMS/Email or In-App/Email defaults

All payment reminders disabled

Admin selects None for all four payment reminder types

System allows this configuration; clients receive no payment reminders at all

SMS integration not configured

Agency enables SMS reminders but hasn't set up SMS integration

Display warning: "SMS delivery requires SMS integration setup. Email will be used as fallback."

Two admins edit simultaneously

Admin A and Admin B save different values for the same setting within seconds

Last save wins; no merge or conflict resolution; Admin A's change may be overwritten

Admin role downgraded

User with Admin role is downgraded to Project Manager while viewing Company Notifications

On next navigation or save attempt, redirect to Personal Notifications with access denied message

User upgraded to Admin

Project Manager is promoted to Admin role

Company Notifications tab appears after page refresh

Subscription downgraded

Agency downgrades from plan that included Contractor Portal

Contractor Reminders and Snapshot sections become hidden or disabled; saved settings preserved but not enforced

Subscription upgraded

Agency upgrades to plan including Contractor Portal

Contractor Reminders and Snapshot sections become visible with default values or previously saved values

No upcoming events exist

Agency has no projects with future event dates

Settings save successfully; reminders will trigger when events are created

No contractors assigned

Agency has no contractors but configures contractor reminders

Settings save successfully; reminders will trigger when contractors are assigned to events

Lead exactly at threshold

Lead age is exactly 7 days (matching configured threshold)

Lead response alert triggers on the threshold day

Lead responded then status reverted

Lead status changed back after being marked as responded

Alert may not re-trigger depending on response log; system checks response history

Same-day event and snapshot

Event is scheduled for today but snapshot wasn't sent

Snapshot timing missed; manual snapshot sending may be available to admins

Contractor assigned to multiple same-day events

Contractor has three events scheduled on the same day

Contractor receives three separate Snapshot PDFs and individual reminders for each event

Agency timezone differs from system

Agency configured in PST but server runs in UTC

Reminder timing calculations use agency's configured timezone

Admin who updated settings is deleted

Admin user who last updated settings is later deactivated

Settings remain intact; updated_by field references deactivated user

Page refresh during dropdown selection

Admin refreshes page while dropdown is open and unsaved

Unsaved dropdown selection lost; page reloads with last saved state

Browser back button after changes

Admin uses browser back button after making setting changes

Changes already auto-saved; navigation proceeds normally

Very long agency name in snapshot

Agency name affects PDF snapshot layout

Agency name truncated or wrapped appropriately in generated PDF

9. Acceptance Criteria

9.1 Access and Visibility

The "Company Notifications" tab must be visible only to users with Agency Owner or Admin roles.
Users with Project Manager, Staff, Editor, Contractor, Client roles must not see the Company Notifications tab.
Direct URL access by unauthorized users must redirect to Personal Notifications with an error message.
The tab must appear immediately for authorized users without additional loading delay.

9.2 Payment Reminders

All four payment reminder types must be displayed with their timing descriptions: Upcoming (7 days before), Due date, Overdue (+2 days), Overdue (+5 days).
Each reminder must display None, SMS, and Email channel options.
SMS and Email must be selectable simultaneously for multi-channel delivery.
Selecting "None" must deselect both SMS and Email for that reminder.
All changes must auto-save without requiring a save button.
Visual confirmation must appear after each successful save.

9.3 Contractor Reminders

Both contractor reminder types must be displayed: 2 days before event and 7 days before event.
None, SMS, and Email options must be available for each reminder.
Multiple channels must be selectable simultaneously.
Settings must be gated based on Contractor Portal subscription.
Changes must auto-save successfully.

9.4 Snapshot

Snapshot toggle must be displayed with description "Send automatically one day before events".
Toggle must switch between On and Off states.
Setting must be gated based on Contractor Portal subscription.
Description must clearly explain snapshot contents and timing.
Change must auto-save with confirmation.

9.5 Internal Team Reminders

All four internal reminder settings must be displayed with descriptions.
None, In-App, and Email options must be available for each reminder.
Lead response days dropdown must contain options: 3, 5, 7, 10, 14 days.
Default dropdown value must be 7 days.
All changes must auto-save successfully.

9.6 Override Behavior

Company settings must establish defaults for new users joining the agency.
Existing users' personal customizations must not be overwritten by company setting changes.
Users who have not customized a setting must receive the company default.
Personal Notification settings must be able to override company defaults.

9.7 Multi-Admin Behavior

All Admins and Agency Owners must see the same settings values.
Changes by one admin must be visible to other admins after page refresh.
Last save must win for concurrent edits without data corruption.
No locking mechanism or conflict warnings must be implemented.

9.8 Subscription Gating

Features requiring higher subscription tiers must be properly gated.
Gated features must show upgrade prompts or be hidden.
SMS toggle must be disabled without SMS add-on subscription.
Contractor features must be hidden without Contractor Portal subscription.

9.9 Error Handling

Failed saves must show error message and revert UI to previous state.
Network offline must disable editing and show warning message.
Unauthorized access attempts must redirect appropriately with error message.

10. Manual Test Cases

The complete manual test cases for the Company Notifications module are provided in a separate Excel file.

Test Case Document: TestCases-Company-Notifications.xlsx

11. Dependencies

Dependency Type

Dependency Name

Description

Impact if Unavailable

Internal Module

User Management

Provides user authentication and role verification for access control

Cannot verify if user has Admin/Owner role; access control will fail

Internal Module

Subscription Management

Provides subscription tier information for feature gating

Cannot properly gate Contractor Portal or SMS features; all features may display

Internal Module

Agency/Company Settings

Provides agency entity for settings association

Cannot save or load company notification settings

Internal Module

Notification Service

Backend service that schedules and delivers reminder notifications

Settings save but reminders will not be triggered or delivered

Internal Module

Invoice/Payment Module

Provides invoice due date data for payment reminder scheduling

Payment reminders have no data to trigger from; reminders will not schedule

Internal Module

Projects Module

Provides event date data for contractor and snapshot scheduling

Contractor reminders and snapshots have no event data; will not trigger

Internal Module

Contractor Management

Provides contractor assignment data for reminder targeting

Contractor reminders have no recipient information; cannot deliver

Internal Module

Lead Management

Provides lead data and response tracking for lead alerts

Lead response alerts cannot check lead status; will not trigger

Internal Module

Tasks Module

Provides task assignment and due date data for task reminders

Task reminders have no task data; will not trigger

External Service

SMS Service (Twilio)

Delivers SMS notifications to clients and contractors

SMS channel delivery fails; email used as fallback if available

External Service

Email Service (SendGrid/SES)

Delivers email notifications and snapshot PDFs

Email channel delivery fails; notifications not sent

External Service

PDF Generation Service

Generates Snapshot PDF documents for contractors

Snapshot generation fails; contractors do not receive pre-event PDFs

Infrastructure

Database

Stores company notification settings

Complete module failure; cannot load or save any settings

Infrastructure

Background Job Processor

Schedules and executes reminder deliveries at configured times

Reminders do not trigger at scheduled times; all timing-based notifications fail

API

Company Settings API

REST endpoints for settings CRUD operations

Cannot load or save company notification settings

12. References

Figma:

https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=33524-68507&t=b6Vb2HmYBAZOvvUn-0

☑️ 3. Personal Notifications

FRD: Personal Notifications

Product: Pixally CRM | Version: 1.0 | Date: December 11, 2025 | Related FRDs: Notification Center, Company Notifications

1. Module Overview

1.1 Module Name

Personal Notifications

1.2 Purpose

The Personal Notifications module enables individual users to customize their notification preferences based on their specific role and responsibilities within Pixally CRM. Each user role has access to a curated set of notification types relevant to their functions, and users can configure which notifications they wish to receive and through which delivery channels. Personal Notification settings allow users to override company-wide defaults established by Agency Owners and Admins, providing personalization while maintaining organizational consistency as a baseline.

1.3 Business Goals

Allow individual users to tailor their notification experience according to their personal preferences and work style.
Reduce alert fatigue by enabling users to disable notifications they find irrelevant to their daily responsibilities.
Present only notification types that are relevant to each user's role, eliminating confusion and reducing settings clutter.
Support flexible multi-channel delivery with options for None, In-App, and Email that can be combined simultaneously.
Ensure initial user engagement by defaulting all notifications to enabled status for new users.
Maintain company alignment by inheriting company defaults as the baseline while allowing individual customization.

2. User Roles & Permissions

2.1 Roles with Access to Personal Notifications

Role

Access Personal Notification Settings

Configure Own Preferences

Notification Categories Visible

Agency Owner

Yes

Finance, Projects, Client Activity, Post-Production, News

Admin

Yes

Finance, Projects, Client Activity, Post-Production, News

Project Manager

Yes

Finance, Projects, Client Activity, Post-Production, News

Normal User (Staff)

Yes

Finance, Projects, Client Activity, Post-Production, News

Editor

Yes

Assignments, Feedback, Payments

Contractor

Yes

Projects, Tasks, Communication, Payments, Forms, Security

Client

N/A — Clients receive all notifications automatically

Gawd Portal User

Yes

User Activity, Billing, Account Status, Security

2.2 Permission Details

All users except Clients can access their Personal Notification settings via Settings > Notifications.
Users can only modify their own notification preferences; they cannot view or modify other users' settings.
Each role sees only the notification types that are relevant to their specific function within the platform.
Clients receive all applicable notifications automatically without any ability to configure preferences.
Post-Production notifications are only visible to users whose agency has the Post-Production add-on subscription.
Contractor-related notifications are only visible to agencies with the Contractor Portal subscription.

3. User Flow

3.1 The user logs into Pixally CRM and navigates to the Settings area from the main navigation menu.

3.2 The system displays the Settings page with various configuration options in the sidebar.

3.3 The user clicks on "Notifications" in the settings sidebar.

3.4 The system loads the Notification Settings page.

3.5 For Agency Owner or Admin users, the system displays two tabs: "Personal Notifications" (selected by default) and "Company Notifications".

3.6 For all other roles (Project Manager, Staff, Editor, Contractor), the system displays only the Personal Notifications content without any tab interface.

3.7 The system displays the user's notification settings organized into role-specific categories with expandable or scrollable sections.

3.8 Each category displays a header with an icon and the category name.

3.9 The user scrolls through the categories to view all available notification types for their role.

3.10 Each notification type displays its name, a brief description, and three channel options: None, In-App, and Email.

3.11 The user locates a notification type they wish to configure, such as "Invoice fully paid".

3.12 The user clicks on the In-App option to enable in-app notifications for this type.

3.13 The system immediately saves the preference and displays a brief visual confirmation.

3.14 The user clicks on the Email option to also enable email notifications for the same type.

3.15 The system saves the multi-channel selection, allowing both In-App and Email to be active simultaneously.

3.16 The user locates a notification type they wish to disable completely.

3.17 The user clicks on None for that notification type.

3.18 The system saves the preference, deselects both In-App and Email, and displays confirmation that the user will no longer receive this notification.

3.19 The user navigates away from the Personal Notifications page.

3.20 The system has auto-saved all changes without requiring an explicit save action.

3.21 The user returns to Personal Notifications later and sees all their previously configured preferences persisted correctly.

4. Functional Logic

4.1 Default Settings and Initialization

When a new user account is created, all notification types applicable to that user's role shall be initialized with default settings.
The default delivery channel settings shall be both In-App and Email enabled for all notification types.
If the user's agency has Company Notification settings configured, the new user's personal settings shall inherit those company defaults instead of system defaults.
For notification types not configured at the company level, system defaults shall apply with all channels enabled.
When a new notification type is added to the platform, it shall default to enabled (In-App and Email) for all applicable users.
When a user's role changes, new notification types applicable to the new role shall appear with default enabled settings, and notification types no longer applicable shall be hidden but their preferences shall be preserved in the database.

4.2 Delivery Channel Options

Each notification type shall display three channel options: None, In-App, and Email.
The In-App channel shall cause notifications to appear in the Notification Center accessible via the bell icon.
The Email channel shall cause notifications to be sent to the user's registered email address.
In-App and Email channels shall function as independent options that can be enabled simultaneously for multi-channel delivery.
Selecting None shall disable the notification entirely, preventing delivery through any channel.
When the user selects None, both In-App and Email shall be visually deselected.
SMS is not available as a delivery channel in Personal Notifications; it is only configurable at the Company Notifications level for specific reminder types.

4.3 Normal Subscriber Notifications (Agency Owner, Admin, Project Manager, Staff)

4.3.1 Finance & Invoicing Category

When a client completes full payment on an invoice, the system shall trigger the "Invoice fully paid" notification and deliver it to the Agency Owner, Admin, and Project Manager associated with that project via their personally configured channels.
When a client makes a partial payment on an invoice, the system shall trigger the "Invoice payment made" notification and deliver it to the Agency Owner, Admin, and Project Manager associated with that project.
When an invoice due date passes without full payment, the system shall trigger the "Invoice is overdue" notification and deliver it to the Agency Owner, Admin, and Project Manager associated with that project.
When a client's payment attempt fails due to declined card or insufficient funds, the system shall trigger the "Invoice payment failed" notification and deliver it to the Agency Owner, Admin, and Project Manager associated with that project.
When any payment is successfully received and processed, the system shall trigger the "Payment received" notification and deliver it to the Agency Owner, Admin, and Project Manager associated with that project.
When a contractor submits a payment request for completed work, the system shall trigger the "Payment request received from contractor" notification and deliver it to the Agency Owner and Admin of the agency.

4.3.2 Projects and Events Category

When a client completes and submits a questionnaire, the system shall trigger the "Questionnaire is filled out" notification and deliver it to the Agency Owner, Admin, and Project Manager associated with that project.
When a prospective client submits a lead form on the website, the system shall trigger the "Lead form submitted" notification and deliver it to the Agency Owner, Admin, and designated lead handler.
When a client opens and views a sent proposal, the system shall trigger the "Client views a proposal" notification and deliver it to the user who sent the proposal, as well as the Agency Owner.
When a client signs a booking proposal, the system shall trigger the "Booking proposal signed" notification and deliver it to the Agency Owner, Admin, and Project Manager associated with that project.
When a booking proposal reaches its expiration date without being signed, the system shall trigger the "Booking proposal expires" notification and deliver it to the Agency Owner, Admin, and Project Manager as a warning.
When a client signs a contract, the system shall trigger the "Contract is signed" notification and deliver it to the Agency Owner, Admin, and Project Manager associated with that project.
When a user uploads a file to a project, the system shall trigger the "File uploaded" notification and deliver it to all team members associated with that project.
When a client uploads a document to their project portal, the system shall trigger the "Client uploads a document" notification and deliver it to the Agency Owner, Admin, and Project Manager associated with that project.
When the system date reaches 5 days before a scheduled event, the system shall trigger the "Upcoming event reminder" notification and deliver it to the Agency Owner, Admin, Project Manager, and assigned staff for that event.
When a new email is received in the Pixally email system for a project, the system shall trigger the "New email received" notification and deliver it to the project owner and team members associated with that project.
When a task passes its due date without being marked complete, the system shall trigger the "Overdue tasks" notification and deliver it to the task assignee and the user who created the task.
When a task deadline is approaching based on configured reminder timing, the system shall trigger the "Task reminders" notification and deliver it to the task assignee.
When there is activity in the referral program such as a new referral submission or conversion, the system shall trigger the "Referral program updates" notification and deliver it to the Agency Owner and Admin.
When a project or event is canceled, the system shall trigger the "Project/Event canceled" notification and deliver it to all team members, assigned contractors, and the client associated with that project.

4.3.3 Client & Contractor Activity Category

When a client submits any form or questionnaire, the system shall trigger the "Client submitted a form or questionnaire" notification and deliver it to the project owner and team members.
When a client signs any contract document, the system shall trigger the "Client signed a contract" notification and deliver it to the project owner and team members.
When a client uploads files to their project portal, the system shall trigger the "Client uploaded files" notification and deliver it to the project owner and team members.
When a client sends a message or replies to a conversation, the system shall trigger the "Client sent a message or replied" notification and deliver it to the recipient of the message.
When a contractor or team member marks a task as completed, the system shall trigger the "Contractor/Team Member marked task as completed" notification and deliver it to the user who created the task and the project owner.
When a contractor uploads deliverables to a project, the system shall trigger the "Contractor adds deliverables" notification and deliver it to the project owner and Agency Owner.

4.3.4 Post-Production Category (Subscription Required)

When a project's post-production status changes in the workflow, the system shall trigger the "Project moves to a new status" notification and deliver it to all team members attached to that post-production job.
When edited files are delivered to the client, the system shall trigger the "Job was delivered to the client" notification and deliver it to the project owner and Agency Owner.
When a post-production job passes its deadline without completion, the system shall trigger the "Job is overdue" notification and deliver it to the assigned editor and project owner.
When a user is mentioned using @ in a post-production comment or note, the system shall trigger the "Editor mentioned you" notification and deliver it specifically to the mentioned user.
When a client or team member leaves feedback on a file, the system shall trigger the "Feedback on a file" notification and deliver it to the assigned editor and project owner.
When a new message is posted on a post-production job, the system shall trigger the "New message on job" notification and deliver it to all users attached to that job.

4.3.5 Pixally News and Updates Category

When Pixally releases new features, product improvements, or platform updates, the system shall trigger the "Product updates" notification and deliver it to all active users across the platform.

4.4 Editor Role Notifications

4.4.1 Assignments & Tasks Category

When an editor is assigned to a new post-production editing task, the system shall trigger the "Assigned to a new editing task" notification and deliver it to the assigned editor.
When an editor is removed from a task they were previously assigned to, the system shall trigger the "Removed from a task" notification and deliver it to the removed editor.
When a task assigned to an editor is approaching its due date, the system shall trigger the "Task due soon" notification and deliver it to the assigned editor.
When a task assigned to an editor passes its due date without completion, the system shall trigger the "Task is overdue" notification and deliver it to the assigned editor.
When a job status changes to "Edit Complete" and the editor is the Lead Editor, the system shall trigger the "Job moved to Edit Complete" notification and deliver it only to the Lead Editor assigned to that job.

4.4.2 Feedback & Collaboration Category

When a new message is posted on a post-production job the editor is attached to, the system shall trigger the "New message on job" notification and deliver it to the attached editor.
When an item the editor is working on moves to "Revision Needed" status, the system shall trigger the "Item moved to Revision Needed" notification and deliver it to the editor attached to that item.
When someone mentions the editor using @ in a comment or internal note, the system shall trigger the "Mentioned in comment" notification and deliver it to the mentioned editor.
When a teammate replies to the editor's comment or question, the system shall trigger the "Reply to your comment" notification and deliver it to the original commenter.

4.4.3 Payments Category

When a job the editor worked on is marked as paid, the system shall trigger the "Job marked as paid" notification and deliver it to the editor who completed that job.

4.5 Contractor Role Notifications

4.5.1 Project Assignment & Updates Category

When a contractor is assigned to a new project, the system shall trigger the "Assigned to a new project" notification and deliver it to the assigned contractor.
When a contractor is removed from a project they were assigned to, the system shall trigger the "Removed from a project" notification and deliver it to the removed contractor.
When project details such as date, time, location, or services are updated after contractor assignment, the system shall trigger the "Project details updated" notification and deliver it to all contractors assigned to that project.
When the event date or time is changed for a project, the system shall trigger the "Event date/time changed" notification and deliver it to all contractors assigned to that project.
When a project the contractor is assigned to is canceled, the system shall trigger the "Project canceled" notification and deliver it to all contractors who were assigned to that project.
When the system date reaches 6 days before and 1 day before an assigned event, the system shall trigger the "Upcoming assignment reminder" notification and deliver it to the contractor assigned to that event.

4.5.2 Deliverables & Tasks Category

When a new task is assigned to a contractor, the system shall trigger the "New task assigned" notification and deliver it to the assigned contractor.
When a task deadline is 3 days away, the system shall trigger the "Task deadline approaching" notification and deliver it to the contractor assigned to that task.
When a task assigned to the contractor passes its due date, the system shall trigger the "Task marked as overdue" notification and deliver it to the assigned contractor.
When another collaborator completes a task on a shared project, the system shall trigger the "Task completed by collaborator" notification and deliver it to other contractors on that project.

4.5.3 Communication & Feedback Category

When a client or project owner sends a message to the contractor, the system shall trigger the "New message from client or owner" notification and deliver it to the contractor.
When someone mentions the contractor using @ in a project comment, the system shall trigger the "Mentioned in project comment" notification and deliver it to the mentioned contractor.
When a client or agency provides feedback on the contractor's delivered work, the system shall trigger the "Feedback submitted on delivered work" notification and deliver it to the contractor who completed that work.

4.5.4 Payments Category

When a contractor submits a payment request and it is successfully recorded, the system shall trigger the "Payment request submitted successfully" notification and deliver it to the contractor who submitted the request.
When the agency approves the contractor's payment request, the system shall trigger the "Payment approved" notification and deliver it to the contractor.
When payment is processed and sent to the contractor, the system shall trigger the "Payment sent" notification and deliver it to the contractor.
When a payment to the contractor fails due to banking issues, the system shall trigger the "Payment failed" notification and deliver it to the contractor.
When a payment to the contractor is delayed from the expected date, the system shall trigger the "Payment delayed" notification and deliver it to the contractor.

4.5.5 Forms, Contracts, and Docs Category

When an agency sends a contract to the contractor for signing, the system shall trigger the "Contract sent" notification and deliver it to the contractor.
When the contractor successfully signs a contract, the system shall trigger the "Contract signed successfully" notification and deliver it to the contractor as confirmation.
When a contractor has an unsigned IC agreement and one week has passed since sending, the system shall trigger the "Contract still unsigned reminder" notification and deliver it to the contractor weekly until signed.
When a questionnaire such as pre-shoot information form is assigned to the contractor, the system shall trigger the "Questionnaire assigned" notification and deliver it to the contractor.
When a questionnaire assigned to the contractor is approaching its due date, the system shall trigger the "Questionnaire due soon" notification and deliver it to the contractor.

4.5.6 Security & Account Integrity Category

When a new contractor account is created, the system shall trigger the "Account created" notification and deliver it to the new contractor as a welcome message.
When the contractor logs in from a new or unrecognized device, the system shall trigger the "Login from new device" notification and deliver it to the contractor as a security alert.
When a password reset is requested for the contractor's account, the system shall trigger the "Password reset requested" notification and deliver it to the contractor.
When an admin updates the contractor's profile information, the system shall trigger the "Profile updated by admin" notification and deliver it to the contractor.

4.5.7 Additional Contractor Notifications (from MOM)

Every January, the system shall trigger the "W9 Annual Reminder" notification and deliver it via email to all active contractors, reminding them to update their W9 if personal details have changed.
When a contractor's cumulative payments exceed $600 in a calendar year, the system shall trigger the "$600 Payment Threshold Alert" notification and deliver it to the contractor informing them of IRS reporting requirements.
When a contractor's IC agreement remains unsigned after initial sending, the system shall trigger the "IC Agreement Signing Reminder" notification weekly until the agreement is signed.
When auto-calculated hours or coverage changes affect the contractor's pay rate, the system shall trigger the "Pay Rate Change Alert" notification as an in-app popup to the contractor.
When a contractor changes their booking window and it conflicts with already scheduled jobs, the system shall trigger the "Booking Window Change Warning" notification as an in-app popup to warn the contractor.

4.6 Client Role Notifications (Non-Configurable)

Clients do not have access to Personal Notification settings and cannot configure their preferences.
Clients receive all applicable notifications automatically based on project activity and company settings.
The delivery channels for client notifications are determined by the system and company configuration, not by client preference.
When a proposal is sent to the client, the system shall trigger the "Proposal received" notification and deliver it via Email and In-App to the client.
When a contract is ready for the client to sign, the system shall trigger the "Contract ready for signing" notification and deliver it via Email and In-App to the client.
When an invoice is generated for the client, the system shall trigger the "Invoice generated" notification and deliver it via Email and In-App to the client.
Payment reminders for upcoming, due, and overdue payments shall be triggered according to the Company Notification settings and delivered to the client via the channels configured by the agency.
When the client's payment is successfully processed, the system shall trigger the "Payment confirmation" notification and deliver it via Email and In-App to the client.
When the client's payment attempt fails, the system shall trigger the "Payment failed" notification and deliver it via Email and In-App to the client.
When a questionnaire is assigned to the client, the system shall trigger the "Questionnaire assigned" notification and deliver it via Email and In-App to the client.
When event details such as date, time, or location are updated, the system shall trigger the "Event details updated" notification and deliver it via Email and In-App to the client.
When an event is canceled, the system shall trigger the "Event canceled" notification and deliver it via Email and In-App to the client.
When files or deliverables are made available to the client, the system shall trigger the "File available" notification and deliver it via Email and In-App to the client.
When the agency sends a message to the client, the system shall trigger the "Message received" notification and deliver it via Email and In-App to the client.
When the payment schedule is modified after contract signing, the system shall trigger the "Payment schedule updated" notification and deliver it via Email to the client.

4.7 Gawd Portal User Notifications

4.7.1 New User Activity Category

When a new user signs up for a free trial on the Pixally platform, the system shall trigger the "Free trial user signed up" notification and deliver it to Gawd Portal administrators.
When a free trial user converts to a paid subscription, the system shall trigger the "Free trial user converted" notification and deliver it to Gawd Portal administrators.

4.7.2 Payments & Billing Category

When a subscription payment is successfully processed, the system shall trigger the "Subscription payment successful" notification and deliver it to Gawd Portal administrators.
When a subscription payment fails, the system shall trigger the "Subscription payment failed" notification and deliver it to Gawd Portal administrators.
When a user's saved credit card is approaching its expiration date, the system shall trigger the "Credit card expiring soon" notification and deliver it to Gawd Portal administrators.
When a new subscription receipt is generated, the system shall trigger the "Subscription receipt available" notification and deliver it to Gawd Portal administrators.

4.7.3 Account Status & Plan Changes Category

When an agency account is frozen due to non-payment, the system shall trigger the "Account frozen" notification and deliver it to Gawd Portal administrators.
When a user cancels their subscription, the system shall trigger the "Subscription canceled" notification and deliver it to Gawd Portal administrators.
When a subscription plan is changed or renewed, the system shall trigger the "Subscription plan changed" notification and deliver it to Gawd Portal administrators.

4.7.4 Security & Account Integrity Category

When suspicious login activity is detected on any account, the system shall trigger the "Suspicious login activity" notification and deliver it to Gawd Portal administrators.
When any project is deleted from the platform, the system shall trigger the "Project deleted" notification and deliver it to Gawd Portal administrators.

4.8 Additional Notifications from Client MOM

4.8.1 Normal Subscriber Additional Notifications

When a new lead's date conflicts with an existing booking or lead, the system shall trigger the "Lead conflict warning" notification as an in-app popup and email to the Agency Owner and Admin.
When a project is booked but contractor spots remain unfilled, the system shall trigger the "Unassigned contractor alert" notification and deliver it to the Agency Owner and Admin.
Weekly, the system shall generate a "Weekly summary - Overdue jobs needing assignment" digest notification containing all jobs that need lead shooter or second shooter assignment, and deliver it via email to the Agency Owner.
Weekly, the system shall generate a "Weekly summary - Unassigned second shooters" digest notification containing upcoming jobs without a second shooter assigned, and deliver it via email to the Agency Owner.
When a job needs a second shooter assigned, the system shall trigger a "Second shooter reminder to Lead Shooter" notification and deliver it to the Lead Shooter assigned to that job.
When contractors have pending invitations that haven't been accepted, the system shall trigger the "Pending contractor invitation reminder" notification and deliver it to the Agency Owner and Admin.

4.8.2 All Roles Additional Notification

When the agency owner's payment fails and the account is suspended, the system shall trigger the "Account suspended warning" notification as an in-app popup to all users of that agency, informing them of the access restriction.

4.9 Relationship with Company Notifications

When determining which notification setting to apply, the system shall use the following priority hierarchy: Personal Notification settings take highest priority if the user has explicitly customized them, Company Notification settings apply if the user has not customized that specific preference, and System Defaults apply if neither personal nor company settings exist.
A user is considered to have "customized" a setting when they have explicitly interacted with and changed that setting from its inherited default.
Company Notification setting changes shall apply immediately to users who have not customized that specific personal notification setting.
Company Notification setting changes shall not overwrite or modify existing personal customizations that users have already made.
When a new user joins an agency, their personal notification settings shall be initialized with the current company default values for all applicable notification types.
The Personal Notification settings UI shall display the effective setting for each notification type without indicating whether it came from personal customization or company default.

4.10 Subscription-Based Feature Restrictions

Notification categories requiring specific subscription add-ons shall be completely hidden from users whose agency does not have the required subscription.
Post-Production category notifications shall only be visible to users in agencies with the Post-Production add-on subscription.
Referral Program notification shall only be visible to users in agencies with the Referral feature enabled.
Contractor-related notifications within Normal Subscriber settings shall only be visible to agencies with the Contractor Portal add-on subscription.
When a subscription lapses, the affected notification categories shall become hidden from the Personal Notification settings UI.
User preferences for subscription-gated notifications shall be preserved in the database even when the subscription lapses, and shall be restored when the subscription is renewed.
When a subscription is added, the previously hidden notification categories shall appear with either the preserved preferences or default enabled settings.

4.11 Settings Auto-Save Behavior

All Personal Notification preference changes shall be automatically saved immediately when the user interacts with any channel toggle.
No explicit "Save" button shall be required or displayed for saving Personal Notification settings.
When a setting is successfully saved, a brief visual indicator such as a checkmark animation or subtle confirmation shall appear.
If a save operation fails due to network or server issues, the UI shall revert the toggle to its previous state and display an error message.
The is_customized flag shall be set to true for a notification setting when the user first explicitly changes it from its default or inherited value.

5. Field Details & Validations

Field Name

Field Type

Validation Rules

setting_id

UUID

System-generated unique identifier; primary key

user_id

UUID

Required; must reference an existing user; foreign key; indexed for queries

agency_id

UUID

Required; must reference an existing agency; foreign key

notification_type

String

Required; maximum 100 characters; must match a predefined notification type identifier

in_app_enabled

Boolean

Required; default: true; determines if notification appears in Notification Center

email_enabled

Boolean

Required; default: true; determines if notification is sent via email

is_customized

Boolean

Required; default: false; set to true when user explicitly changes the setting

created_at

DateTime

System-generated timestamp when setting record was created

updated_at

DateTime

System-updated timestamp when setting was last modified

6. Success Message Handling

Operation

Success Message

Trigger Condition

Post-Success Action

Enable In-App channel