Notification System

Skill Profile

(Select at least one profile to enable specific modules)

• DevOps
• Backend
• Frontend
• AI-RAG
• Security Critical

Overview

A notification system delivers messages to users through various channels. This skill covers notification types (email, SMS, push, in-app), service integration (SendGrid/AWS SES, Twilio, Firebase), template management, notification preferences, queue-based delivery, retry logic, delivery tracking, rate limiting, testing, and best practices.

Why This Matters

Notification systems are critical for:

• User Engagement: Keep users informed and engaged
• Operational Reliability: Ensure messages are delivered reliably
• User Experience: Respect user preferences for channels and timing
• Cost Efficiency: Optimize delivery costs through queueing and batching
• Compliance: Meet regulatory requirements for transactional communications
• Analytics: Track delivery rates and user engagement

Poor notification system implementation leads to:

• Missed or delayed notifications
• Spamming users who opted out
• High delivery costs from inefficient sending
• Poor user experience from inconsistent messaging
• Inability to troubleshoot delivery issues

Core Concepts & Rules

1. Core Principles

• Follow established patterns and conventions
• Maintain consistency across codebase
• Document decisions and trade-offs

2. Implementation Guidelines

• Start with the simplest viable solution
• Iterate based on feedback and requirements
• Test thoroughly before deployment

Inputs / Outputs / Contracts

• Inputs:
  • <e.g., env vars, request payload, file paths, schema>
• Entry Conditions:
  • <Pre-requisites: e.g., Repo initialized, DB running, specific branch checked out>
• Outputs:
  • <e.g., artifacts (PR diff, docs, tests, dashboard JSON)>
• Artifacts Required (Deliverables):
  • <e.g., Code Diff, Unit Tests, Migration Script, API Docs>
• Acceptance Evidence:
  • <e.g., Test Report (screenshot/log), Benchmark Result, Security Scan Report>
• Success Criteria:
  • <e.g., p95 < 300ms, coverage ≥ 80%>

Skill Composition

• Depends on: None
• Compatible with: None
• Conflicts with: None
• Related Skills: None

Quick Start

Assumptions

• Third-party services (SendGrid, Twilio, Firebase) are available
• Redis or similar queue system is available
• User contact information is validated
• Templates are designed and tested
• Webhooks are configured for delivery tracking

Compatibility

• Works with all email providers (SendGrid, AWS SES, Mailgun)
• Compatible with all SMS providers (Twilio, Nexmo, Plivo)
• Supports all push providers (FCM, APNs, OneSignal)
• Works with all backend frameworks
• Compatible with all queue systems

Test Scenario Matrix (QA Strategy)

Technical Guardrails & Security Threat Model

1. Security & Privacy (Threat Model)

• Top Threats: Injection attacks, authentication bypass, data exposure

• Data Handling: Sanitize all user inputs to prevent Injection attacks. Never log raw PII
• Secrets Management: No hardcoded API keys. Use Env Vars/Secrets Manager
• Authorization: Validate user permissions before state changes

2. Performance & Resources

• Execution Efficiency: Consider time complexity for algorithms
• Memory Management: Use streams/pagination for large data
• Resource Cleanup: Close DB connections/file handlers in finally blocks

3. Architecture & Scalability

• Design Pattern: Follow SOLID principles, use Dependency Injection
• Modularity: Decouple logic from UI/Frameworks

4. Observability & Reliability

• Logging Standards: Structured JSON, include trace IDs request_id
• Metrics: Track error_rate, latency, queue_depth
• Error Handling: Standardized error codes, no bare except
• Observability Artifacts:
  • Log Fields: timestamp, level, message, request_id
  • Metrics: request_count, error_count, response_time
  • Dashboards/Alerts: High Error Rate > 5%

Agent Directives

When Sending Notifications:

1. Check user preferences for channel and type
2. Render template with user-specific data
3. Create notification record
4. Enqueue for delivery
5. Track delivery status
6. Handle failures with retry logic

When Managing Templates:

1. Design responsive templates
2. Test on multiple devices and email clients
3. Validate all variables are used
4. Document template variables
5. Version templates for changes

When Handling Bounces:

1. Identify reason for bounce
2. Update user contact information
3. Disable invalid contacts
4. Track bounce metrics
5. Investigate if bounce rate is high

Definition of Done (DoD) Checklist

• Tests passed + coverage met
• Lint/Typecheck passed
• Logging/Metrics/Trace implemented
• Security checks passed
• Documentation/Changelog updated
• Accessibility/Performance requirements met (if frontend)

Anti-patterns

Ignoring User Preferences

• Sending to disabled channels
• Ignoring opt-out requests
• Sending unwanted notifications

No Retry Logic

• Failing on transient errors
• Not retrying failed deliveries
• Poor delivery rates

Hardcoding Content

• Not using templates
• Inconsistent messaging
• Difficult to maintain

No Delivery Tracking

• Can't measure success rates
• Can't troubleshoot issues
• Poor user experience

Reference Links & Examples

• Internal documentation and examples
• Official documentation and best practices
• Community resources and discussions

Versioning & Changelog

• Version: 1.0.0
• Changelog:
  • 2026-02-22: Initial version with complete template structure