notification-system

Getting Started

1. Install the skill using the command above
2. Open your AI coding agent (Claude Code, Codex, Gemini CLI, or Cursor)
3. Reference the skill in your prompt
4. The AI will use the skill's capabilities automatically

Example Prompts

• "Review the open pull requests and summarize what needs attention"
• "Generate a changelog from the last 20 commits on the main branch"

Overview

This skill enables AI agents to architect, implement, and configure multi-channel notification systems. It covers channel routing, user preference management, template rendering across formats, delivery tracking, retry logic, and compliance requirements like CAN-SPAM unsubscribe.

Instructions

1. Notification Architecture

Every notification system needs these components:

Event Source → Notification Router → Channel Adapters → Delivery
                    ↓                      ↓
            Preference Store         Retry Queue
                                         ↓
                                   Dead Letter Queue

Notification Router: Receives a typed event, resolves the user's channel preferences, and dispatches to the appropriate channel adapters.

Channel Adapters: Pluggable handlers for each delivery channel. Must implement a common interface:

interface ChannelAdapter {
  channel: 'email' | 'push' | 'in-app';
  send(notification: FormattedNotification): Promise<DeliveryResult>;
  validateRecipient(userId: string): Promise<boolean>;
}

Preference Store: Database-backed user preferences with per-notification-type, per-channel toggles. Some notifications (transactional/security) must be non-disableable.

2. Notification Type Classification

Always classify notifications into categories that determine default behavior:

3. Channel-Specific Constraints

Email:

• Must include unsubscribe link (CAN-SPAM / GDPR)
• Use List-Unsubscribe header for one-click unsubscribe
• HTML + plain text versions
• Sender reputation — batch marketing emails separately from transactional

Push Notifications:

• Title: max 65 characters, Body: max 178 characters (iOS truncation)
• Include data payload for deep linking
• Handle token expiration and refresh
• Respect OS-level notification settings

In-App:

• Store in database with read/unread status
• Deliver in real-time via WebSocket if user is online
• Group related notifications (e.g., "3 people commented on your post")
• Paginate the notification feed

4. Retry and Failure Handling

Implement exponential backoff per channel:

• Email: 3 retries at 1min, 5min, 30min (provider outages are temporary)
• Push: 2 retries at 30s, 2min (invalid tokens should fail fast)
• In-app: 0 retries (direct DB write, either succeeds or doesn't)

After max retries, move to dead letter queue with full context for debugging.

5. Template Strategy

Use a single data context per notification type that renders differently per channel:

interface NotificationContext {
  type: 'new-comment';
  actor: { name: string; avatarUrl: string };
  target: { title: string; url: string };
  content: { preview: string; full: string };
}
// → Email: Full HTML with actor avatar, comment preview, and action button
// → Push: "Alex commented: 'Great analysis of the…'"
// → In-app: "Alex commented on Your Post Title" with link

6. Delivery Tracking

Track these states for every notification:

queued → sent → delivered → read → failed

Store in a notification_deliveries table with: notification_id, user_id, channel, status, attempted_at, delivered_at, read_at, error_message.

Examples

Example 1: Express + BullMQ notification router

Prompt: "Build a notification service for my Express app that sends order confirmations via email and in-app."

Output: The agent creates a BullMQ-backed router that accepts { type: 'order-confirmed', userId, data: { orderId, total, items } }, checks user preferences, and dispatches to the email adapter (SendGrid) and in-app adapter (PostgreSQL insert + Socket.io emit).

Example 2: Preference management API

Prompt: "Create an API for users to manage their notification preferences with a React settings page."

Output: The agent generates REST endpoints for CRUD on notification preferences, a migration for the notification_preferences table with a composite unique constraint on (user_id, notification_type, channel), and a React component rendering a matrix of toggles with notification types as rows and channels as columns.

Guidelines

• Never allow users to disable security notifications (password reset, 2FA codes)
• Always send email notifications from a queue, never synchronously in the request handler
• Batch notification grouping (e.g., "5 new comments") to avoid notification fatigue
• Test with notification-heavy scenarios: a user mentioned in a thread with 50 replies
• Include rate limiting on notifications per user per hour to prevent notification storms
• Log delivery metrics for monitoring: sent/delivered/failed rates by channel