# Notification Patterns

# Purpose

This document defines how the platform delivers notifications to users — the notification center, delivery channels, priority levels, grouping, and persona-specific behavior. Notifications are the connective tissue of the platform — they tell users what happened, what needs attention, and what's coming up.

The design constraint: notifications must be useful without being overwhelming. A Volunteer Coordinator during a busy event weekend might receive 50 notifications in an hour (volunteer signups, shift cancellations, check-in confirmations). An Org Admin during election day might receive 200. The system must surface what matters and suppress what doesn't.

# Notification Anatomy

Every notification has a consistent structure:

┌──────────────────────────────────────────────────────┐
│  [Icon]  Source · Time                      [⋯]     │
│                                                      │
│  Title (bold, concise — what happened)               │
│  Body (1-2 lines — context and detail)               │
│                                                      │
│  [Primary Action]  [Secondary Action]                │
└──────────────────────────────────────────────────────┘

# Fields

# Notification Center

# Access

• Desktop: Bell icon in the header bar. Badge count shows unread notifications. Click opens a drawer from the right edge.
• Mobile: Bell icon in the top bar. Tap opens a full-screen notification view.

# Layout

┌──────────────────────────────────────────────────────┐
│  Notifications (12 unread)        [Mark all read]    │
├──────────────────────────────────────────────────────┤
│  [All]  [Messages]  [Shifts]  [Alerts]  [Other]     │  ← Filter tabs
├──────────────────────────────────────────────────────┤
│                                                       │
│  TODAY                                                │
│  ┌────────────────────────────────────────────────┐   │
│  │  🚨 Compliance · 15 min ago                    │   │
│  │  Contribution limit approaching                │   │
│  │  John Smith: $2,700 of $2,900 limit used       │   │
│  │  [Review]  [Dismiss]                           │   │
│  └────────────────────────────────────────────────┘   │
│  ┌────────────────────────────────────────────────┐   │
│  │  📋 Shifts · 1 hour ago                        │   │
│  │  Shift cancellation: Maria Lopez               │   │
│  │  Tomorrow 2pm-6pm · Turf 12 · No replacement   │   │
│  │  [Find Replacement]  [Dismiss]                 │   │
│  └────────────────────────────────────────────────┘   │
│                                                       │
│  YESTERDAY                                            │
│  ...                                                  │
│                                                       │
│  [Notification Preferences]                           │
└──────────────────────────────────────────────────────┘

# Grouping

Notifications are grouped by time (Today, Yesterday, This Week, Older) and can be filtered by source category:

# Behaviors

• Unread indicator — unread notifications have a colored left border or background tint. Read notifications are visually muted.
• Mark as read — clicking a notification marks it as read. "Mark all read" button at the top.
• Dismiss — removes the notification from the center. Does not affect the underlying event.
• Deep link — tapping a notification navigates to the relevant screen (the donation detail, the shift management page, the conversation, etc.).
• Persistent critical notifications — notifications marked as critical (compliance deadlines, security alerts) cannot be dismissed, only resolved by acting on them.
• Badge count — shows on the bell icon. On mobile, also appears on the relevant bottom tab (Messages tab shows unread message count, Shifts tab shows pending shift notifications).

# Priority Levels

# Definitions

# User-Configurable Priority

Per the decision in messaging.md, users can configure notification priority for each source. The platform provides sensible defaults per persona, and users can adjust:

┌──────────────────────────────────────────────────────┐
│  Notification Preferences                             │
├──────────────────────────────────────────────────────┤
│                                                       │
│  Messages                                             │
│    Direct messages    [● High  ▾]  [Push ✓] [Email ✓]│
│    Group messages     [● Normal ▾] [Push ✓] [Email ☐]│
│    Broadcasts         [● Normal ▾] [Push ☐] [Email ✓]│
│                                                       │
│  Shifts                                               │
│    Shift reminders    [● High  ▾]  [Push ✓] [Email ✓]│
│    Cancellations      [● High  ▾]  [Push ✓] [Email ✓]│
│    New assignments    [● Normal ▾] [Push ✓] [Email ☐]│
│                                                       │
│  Fundraising                                          │
│    New donations      [● Normal ▾] [Push ☐] [Email ✓]│
│    Compliance flags   [● Critical] [Push ✓] [Email ✓]│  ← Cannot change
│    ...                                                │
│                                                       │
│  [Reset to Defaults]                                  │
└──────────────────────────────────────────────────────┘

Non-configurable: Some notifications are always critical and cannot be downgraded: security alerts, compliance violations, system errors. These are marked "Cannot change" in the preferences.

# Delivery Channels

Notifications reach users through multiple channels. Which channels are available depends on the notification source and user preferences.

# Channel Matrix

# Channel Selection Logic

1. In-app — always delivered. This is the canonical notification.
2. Push — delivered if the user has push enabled and the notification priority is >= their configured threshold for that source.
3. Email — delivered if the user has email notifications enabled for that source. Emails may be batched (see Digests below).
4. SMS — delivered only for critical notifications when the user has opted in to SMS alerts. Used as a last-resort channel for users who may not have the app open (e.g., Org Admin during a security incident).

# Duplicate Prevention

If a user sees a notification via push and then opens the app, the in-app notification should already be marked as "seen" (not necessarily "read" — they saw the push but may not have acted on it). This prevents the notification center from showing notifications the user already dismissed via push.

# Persona-Specific Defaults

Each persona has notification defaults tuned to their role and typical usage pattern.

# Org Admin

Sees the broadest set of notifications — system health, compliance, and cross-functional alerts.

# Communications Director

Focused on content delivery and engagement.

# Finance Director

Focused on money and compliance.

# Field Director

Focused on operations and GOTV.

# Volunteer Coordinator

Focused on people.

# Data Manager

Focused on data operations.

# Volunteer

Minimal, action-oriented notifications.

# Team Lead

Everything a Volunteer gets, plus team management.

# Candidate

Curated, important-only.

# Supporter

Minimal, transactional.

# Email Digests

For notifications that don't require immediate attention, the platform offers email digests that batch notifications into periodic summaries.

# Digest Options

Users configure their digest preferences in notification settings. Digest emails are well-formatted summaries, not just lists of notifications — they include context, trends, and direct links to the relevant screens.

# Election Day Notification Behavior

When GOTV/election day mode is activated, the notification system shifts:

# Changes

• GOTV notifications elevated. All GOTV-related notifications (turnout updates, escalations, resource reallocation suggestions, ride requests, poll watcher issues) are promoted to high priority regardless of user configuration.
• Non-GOTV notifications suppressed. Normal operational notifications (new volunteer signups, data imports, routine messages) are batched into a post-election digest. They don't disappear — they're deferred.
• War room feed. War room staff see a continuous notification feed integrated into the war room dashboard. This is a live feed, not the standard notification center — it auto-scrolls with new events.
• Escalation notifications are modal. Critical GOTV escalations (poll watcher safety issue, major turnout anomaly) appear as modal dialogs that require acknowledgment — they can't be missed by scrolling past.

# Post-Election

After election day mode deactivates, deferred notifications are delivered as a digest email ("Here's what happened while you were in election day mode"). The notification center returns to normal behavior.

# Notification-Related UI Elements

# Badge Counts

Badge counts appear on:

• Bell icon (header bar) — total unread count
• Mobile bottom tabs — per-tab counts where relevant:
  • Messages tab: unread message count
  • Shifts tab: pending shift notifications
  • Approvals tab (Candidate): pending approval count
• Sidebar items (desktop) — subtle count badges on relevant nav items

# Toast Notifications

Transient notifications for immediate feedback (not persisted in the notification center):

┌──────────────────────────────────────┐
│  ✓  Contact saved                    │  ← Success toast (3 seconds)
└──────────────────────────────────────┘

┌──────────────────────────────────────┐
│  ⚠  Save failed · Retry             │  ← Error toast (persistent until action)
└──────────────────────────────────────┘

• Success toasts — appear briefly (3 seconds), auto-dismiss. Confirm that an action completed.
• Error toasts — persist until dismissed or retried. Include a retry action for recoverable errors.
• Position — bottom-center on desktop, top-center on mobile (avoid bottom tab bar conflict).

# Notification Sounds

• Critical notifications — system alert sound (respects device mute settings)
• High notifications — subtle notification sound
• Normal/Low — no sound (push vibration only, if enabled)
• Field mode — all sounds suppressed except critical (volunteer shouldn't be distracted while canvassing)

# Do Not Disturb

Users can enable Do Not Disturb mode:

• Manual toggle — accessible from the user menu
• Scheduled — set hours (e.g., 10pm-7am)
• During shifts — automatically enabled during active field mode shifts (only critical and shift-related notifications come through)

When DND is active:

• Push notifications are silenced
• In-app notifications still accumulate (visible when the user checks)
• Critical notifications break through DND (security, compliance)
• A "DND active" indicator appears subtly in the header

# Open Questions

1. Notification lifespan. How long should notifications persist in the notification center? Currently proposed: 30 days for normal, 7 days for low, until resolved for critical. Is 30 days too long?

2. Cross-device notification sync. If a user dismisses a notification on their phone, should it also be dismissed on their desktop? (Yes, probably — notifications should sync across devices.)

3. Notification analytics. Should the platform track notification engagement rates (what percentage of notifications are opened, acted on, dismissed)? This data could inform future priority defaults and digest timing.