Notification System

Complete guide to notification items, badges, actions, and templates

5 Tables Badges Actions Templates

📋 Overview

The Notification System provides a flexible, multi-channel notification framework with customizable badges, actions, and templates. Notifications can be displayed with visual indicators and include action buttons for user interaction.

Rich Notifications - Support for badges, actions, and custom content
Badge Configurations - Visual indicators with customizable styles
Action Buttons - Primary and secondary actions with navigation
Templates - Reusable notification templates for different channels
Read Tracking - Track which users have read which notifications

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                            NOTIFICATION SYSTEM                               │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐                │
│  │ notif_items  │────▶│  bdg_items   │     │action_items  │                │
│  │              │     │ (Badges)     │     │ (Buttons)    │                │
│  │ - notif_id   │     │              │     │              │                │
│  │ - bdg_id FK  │     │ - bdg_id     │     │ - act_id     │                │
│  │ - pri_id FK  │────▶│ - type       │     │ - type       │                │
│  │ - sec_id FK  │     │ - text       │     │ - nav_type   │                │
│  │ - inst_id FK │     │ - icon       │     │ - base_url   │                │
│  └──────────────┘     │ - bg_color   │     │ - params     │                │
│         │             └──────────────┘     └──────────────┘                │
│         │                                                                   │
│         ▼                                                                    │
│  ┌──────────────┐                                                           │
│  │notif_reads   │◀─── app_users.user_id                                    │
│  │(Read Tracking│                                                           │
│  │ per user)    │                                                           │
│  │              │                                                           │
│  │ - notif_id   │                                                           │
│  │ - user_id    │                                                           │
│  │ - read_at    │                                                           │
│  └──────────────┘                                                           │
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                    notification_templates                              │    │
│  │                    (Multi-channel Templates)                          │    │
│  │                                                                       │    │
│  │  - template_key    (Unique identifier)                               │    │
│  │  - placeholders    (e.g., {username}, {amount})                      │    │
│  │  - content         (Template body with {placeholders})               │    │
│  │  - channel_type    (push, email, sms, in_app)                        │    │
│  │  - is_active       (Enable/disable)                                  │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                                                                              │
│  NOTIFICATION FLOW:                                                          │
│  ┌─────────────────────────────────────────────────────────────────────┐     │
│  │ 1. Create notification with notif_id                                 │     │
│  │ 2. Configure badge (optional) - visual indicator                     │     │
│  │ 3. Configure actions (optional) - primary/secondary buttons           │     │
│  │ 4. Set visibility status & availability                              │     │
│  │ 5. Track reads per user via notif_reads                              │     │
│  │ 6. Use templates for consistent multi-channel messages               │     │
│  └─────────────────────────────────────────────────────────────────────┘     │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

📊 Table Reference

notif_items

Core notification definitions with content, badges, and actions.

Field	Type	Attributes	Description
`id`	BIGINT	PK, Auto Increment	Primary key
`notif_id`	VARCHAR(50)	UNIQUE	Public notification identifier
`source`	VARCHAR(50)	NOT NULL	Notification source (system, user, order)
`status`	INT	Default: 1	0=hidden, 1=visible
`type`	VARCHAR(50)	NOT NULL	info, warning, success, error
`variant`	VARCHAR(50)	Default: simple	simple, actionable, rich
`title`	VARCHAR(255)	NOT NULL	Notification title
`description`	TEXT	NULLABLE	Notification body text
`bdg_id`	VARCHAR(50)	FK, NULLABLE	References bdg_items.bdg_id
`inst_id`	INT	FK, NULLABLE	Related instrumentation ID
`pri_label`	VARCHAR(50)	NULLABLE	Primary action button label
`pri_id`	VARCHAR(50)	FK, NULLABLE	References action_items.act_id
`pri_variant`	VARCHAR(50)	NULLABLE	Primary button style
`sec_label`	VARCHAR(50)	NULLABLE	Secondary action label
`sec_id`	VARCHAR(50)	FK, NULLABLE	References action_items.act_id
`sec_variant`	VARCHAR(50)	NULLABLE	Secondary button style
`notif_from`	VARCHAR(100)	NULLABLE	Sender identifier
`notif_cnd`	JSON	NULLABLE	Display conditions
`is_ava`	BOOLEAN	Default: true	Is available for display
`custom`	JSON	NULLABLE	Custom metadata

bdg_items

Badge configurations for visual indicators on notifications.

Field	Type	Attributes	Description
`id`	BIGINT	PK, Auto Increment	Primary key
`bdg_id`	VARCHAR(50)	UNIQUE	Badge identifier
`type`	VARCHAR(50)	NOT NULL	number, text, dot
`text`	VARCHAR(20)	NULLABLE	Text for text badges
`number`	INT	NULLABLE	Number for number badges
`icon`	VARCHAR(50)	NULLABLE	Icon identifier
`size`	VARCHAR(20)	Default: md	xs, sm, md, lg
`bg_color`	VARCHAR(20)	NULLABLE	Background color
`border_color`	VARCHAR(20)	NULLABLE	Border color
`is_round`	BOOLEAN	Default: false	Rounded corners
`is_hover`	BOOLEAN	Default: false	Show on hover
`is_dot`	BOOLEAN	Default: false	Dot style indicator
`is_active`	BOOLEAN	Default: true	Badge availability

action_items

Action button definitions with navigation types and parameters.

Field	Type	Attributes	Description
`id`	BIGINT	PK, Auto Increment	Primary key
`act_id`	VARCHAR(50)	UNIQUE	Action identifier
`type`	VARCHAR(50)	NOT NULL	navigate, execute, dismiss
`nav_type`	VARCHAR(20)	Default: internal	internal, external
`base_url`	VARCHAR(500)	NOT NULL	URL with {placeholders}
`params`	JSON	NULLABLE	URL parameters

notification_templates

Reusable templates for multi-channel notifications.

Field	Type	Attributes	Description
`id`	BIGINT	PK, Auto Increment	Primary key
`template_key`	VARCHAR(100)	UNIQUE	Template identifier
`placeholders`	VARCHAR(255)	NULLABLE	Comma-separated placeholder names
`content`	TEXT	NOT NULL	Template body with {placeholders}
`channel_type`	VARCHAR(20)	Default: push	push, email, sms, in_app
`description`	TEXT	NULLABLE	Template description
`is_active`	BOOLEAN	Default: true	Template availability

notif_reads

Tracks which users have read which notifications (one record per user per notification).

Field	Type	Attributes	Description
`id`	BIGINT	PK, Auto Increment	Primary key
`notif_id`	VARCHAR(50)	FK	References notif_items.notif_id
`user_id`	VARCHAR(32)	FK	References app_users.user_id
`read_at`	TIMESTAMP	NULLABLE	Read timestamp

💻 Usage Examples

// Create a notification with badge and actions
$notification = NotifItem::create([
    'notif_id' => 'order_12345_shipped',
    'source' => 'order',
    'type' => 'success',
    'variant' => 'actionable',
    'title' => 'Order Shipped!',
    'description' => 'Your order #12345 has been shipped.',
    'bdg_id' => 'new_badge',  // Shows "New" indicator
    'pri_label' => 'Track Order',
    'pri_id' => 'track_order_action',
    'sec_label' => 'View Details',
    'sec_id' => 'view_details_action',
    'notif_from' => 'orders-system',
    'is_ava' => true,
]);

// Create a badge
$badge = BdgItem::create([
    'bdg_id' => 'new_badge',
    'type' => 'text',
    'text' => 'New',
    'size' => 'sm',
    'bg_color' => '#10B981',
    'is_active' => true,
]);

// Create an action
$action = ActionItem::create([
    'act_id' => 'track_order_action',
    'type' => 'navigate',
    'nav_type' => 'internal',
    'base_url' => '/orders/{order_id}/track',
    'params' => ['order_id' => '12345'],
]);

// Mark notification as read for user
NotifRead::markAsRead('order_12345_shipped', 'ABC123');

// Check if user has read notification
$isRead = NotifRead::isReadByUser('order_12345_shipped', 'ABC123');

// Use template for email
$template = NotificationTemplate::where('template_key', 'order_shipped_email')
    ->where('channel_type', 'email')
    ->first();

$emailContent = $template->render([
    'username' => 'John Doe',
    'order_id' => '12345',
    'tracking_link' => 'https://track.example.com/12345',
]);
// Output: "Hello John Doe, Your order #12345 has been shipped..."

// Get notification with relationships
$notification = NotifItem::with('badge', 'primaryAction', 'secondaryAction')
    ->where('notif_id', 'order_12345_shipped')
    ->first();

// Check if notification is visible
if ($notification->isVisible()) {
    // Display notification
}