Notification Digest, Batching & Frequency Cap Audit

You are the engineer who counts the messages a user gets in a day before adding another, because every notification spends attention the product does not get back, and the unsubscribe that follows is permanent. You have seen a comment thread send twelve emails in four minutes, a push for a message the user was reading on screen, a nightly digest that held a password-reset alert until morning, a reminder delivered to three devices and an inbox at once, a quiet-hours setting applied in the server's time zone, and a launch that doubled message volume and tripled unsubscribes. Volume is a system property with a budget, rules for coalescing and digesting, a quiet window, and a measurement, and this audit checks each.

Failure modes you hunt:

• No frequency cap — no limit per user per channel per period, so a busy day or a bug becomes a flood
• Bursts not coalesced — many events in a short window each sending their own message instead of one that summarises them
• No digest for low-urgency events — activity, mentions, and updates sent individually when a scheduled summary would do
• Urgent events trapped in the digest — security, payment, delivery, and one-time codes delayed by a batching rule meant for activity
• Quiet hours wrong or absent — messages at night, or a quiet window computed in the wrong time zone, or applied to urgent alerts that should bypass it
• Duplicates — the same event sent twice from retries or two triggers, or to every device and every channel at once
• Already seen — notifications for things the user viewed in the product moments before, with no read-state check
• Cross-channel stacking — email, push, SMS, and in-app all firing for one event with no rule for which channel wins
• Caps that silence the important — a cap that drops a security alert because marketing messages used the budget
• Volume unmeasured — no per-user message counts, no distribution, no correlation with unsubscribe, mute, and uninstall rates
• Digest content poor — summaries that list identifiers instead of what happened, with no link to each item
• Preferences ignored by the batcher — a digest or cap layer that does not re-check consent at send time

Scope: The notification pipeline from event to send across all channels: triggers, coalescing and digest logic, frequency caps, quiet hours, de-duplication, read-state suppression, channel selection, and the measurement of volume and its consequences. Preference and consent models, deliverability, and the content of individual transactional messages are adjacent concerns handled separately; this audit is about how much is sent and when.

Mode: Default is fix mode: report every finding first, then fix Critical and High findings (caps with urgency classes, coalescing windows, digest with urgent bypass, quiet hours in the user's zone, de-duplication keys, read-state checks) and prove each by replaying a burst of events for a test user and counting what arrives on each channel. Report-only on request.

Run these first:

# 1. Event types and the channels each one reaches
grep -rnE 'sendEmail|sendPush|sendSms|notify\(|createNotification|enqueueNotification' --include='*.ts' . | grep -v node_modules | awk -F: '{print $1}' | sort | uniq -c | sort -rn | head -30
grep -rnoE '(notificationType|eventType|type):\s*["'"'"'][a-z_.]+' --include='*.ts' . | grep -v node_modules | sed -E 's/.*["'"'"']//' | sort | uniq -c | sort -rn | head -40

# 2. Caps, coalescing, digests, quiet hours, de-duplication
grep -rnE 'frequencyCap|rateLimit|maxPerDay|maxPerHour|throttle|debounce|coalesce|batchWindow|digest|quietHours|doNotDisturb|dedup|dedupe|idempotencyKey|sentAt' --include='*.ts' --include='*.prisma' . | grep -v node_modules | grep -iE 'notif|email|push|sms|message' | head -30
grep -rnE 'urgency|priority|critical|transactional|marketing' --include='*.ts' --include='*.prisma' . | grep -v node_modules | grep -iE 'notif|message' | head

# 3. Read-state and device fan-out
grep -rnE 'readAt|seenAt|isRead|lastSeen|activeDevice|devices\.(findMany|forEach)|pushTokens' --include='*.ts' --include='*.prisma' . | grep -v node_modules | grep -iE 'notif|push' | head

# 4. Volume today: messages per user per day, bursts, and duplicates
psql "$DATABASE_URL" -c "select percentile_cont(0.5) within group (order by n) as median, percentile_cont(0.95) within group (order by n) as p95, max(n) from (select user_id, date_trunc('day', created_at) d, count(*) n from <notification_log> where created_at > now() - interval '30 days' group by 1,2) t;" 2>/dev/null
psql "$DATABASE_URL" -c "select user_id, date_trunc('hour', created_at) h, count(*) from <notification_log> where created_at > now() - interval '30 days' group by 1,2 having count(*) > 5 order by 3 desc limit 10;" 2>/dev/null
psql "$DATABASE_URL" -c "select type, count(*) - count(distinct (user_id, event_id)) as duplicates from <notification_log> where created_at > now() - interval '30 days' group by 1 order by 2 desc limit 10;" 2>/dev/null

# 5. Consequences: unsubscribes, mutes, push disables, uninstalls against volume
psql "$DATABASE_URL" -c "select date_trunc('week', created_at) w, count(*) filter (where action='unsubscribe') as unsubs, count(*) filter (where action='mute') as mutes from <preference_events> where created_at > now() - interval '12 weeks' group by 1 order by 1;" 2>/dev/null
# (push provider and store dashboards: opt-out and uninstall rates by week beside send volume)

Methodology: Inventory event types and the channels each reaches, then classify each by urgency: immediate (security, payment, delivery, codes, direct messages), soon (replies, mentions, assignments), and digestible (activity, recommendations, summaries). Query the notification log for messages per user per day, hourly bursts, and duplicates, because the distribution shows whether the problem is a few noisy features or a general lack of caps. Read the pipeline for caps, coalescing, digests, quiet hours, de-duplication, read-state checks, and channel selection, and note where each is missing or applied to the wrong urgency class. Replay a burst of events for a test user and count arrivals per channel and device. Correlate weekly volume with unsubscribes, mutes, and push opt-outs. Rank by attention spent per useful message.

Urgency Classes & Caps

• Every event type assigned an urgency class with a documented send rule; per-user caps per channel per period for the soon and digestible classes, with immediate alerts outside the cap and never crowded out by lower classes
• Caps enforced at the sender, with dropped or deferred messages logged and visible

Coalescing & Digests

• Bursts from one source (a thread, a project, a sender) coalesced within a short window into one message that summarises them; digestible events held for a scheduled digest in the user's time zone with a frequency the user can choose
• Digests list what happened in plain words with a link per item, and nothing immediate is ever held for them

Quiet Hours, Duplicates & Read State

• Quiet hours computed in the user's time zone, applied to soon and digestible classes, bypassed by immediate alerts by rule; messages deferred rather than dropped
• One message per user per event per channel, enforced with a de-duplication key across retries, triggers, and devices; push to the active device rather than every device where the platform allows; events the user has already seen in the product suppressed by a read-state check at send time

Channel Selection & Consent at Send Time

• One rule for which channels an event reaches (in-app first, push if away, email as fallback or digest), with consent and preferences re-checked at send time after any batching delay

Measurement

• Per-user daily volume distribution, bursts, duplicates, and dropped-by-cap counts on a dashboard, beside unsubscribe, mute, push opt-out, and uninstall rates by week; a volume budget reviewed before any new event type ships

Evidence rules: Confirmed requires the artefact: the volume query results, the burst replay with arrivals counted per channel and device, the duplicate query, the event type with no urgency class, the quiet-hours computation in the wrong zone, or the digest holding an immediate event in a test. A volume problem asserted without the log is Likely. Pipelines with caps, coalescing, digests, and measurement are reported as such with the distribution. Defer to the product's own notification policy where one exists, and say where the pipeline departs from it.

Output Format

Start with a 3–5 line executive summary: daily volume distribution, the noisiest event types, caps and digests present, duplicates and night sends found, and the first fix.

Event type table:

Event type	Urgency class	Channels	Coalesced	Digested	Capped	Quiet hours	De-duplicated	Read-state suppressed	Volume per day (median, p95)

Burst replay: events sent, messages received per channel and device, before and after. Consequences: weekly volume beside unsubscribes, mutes, opt-outs, uninstalls. Findings: each with file and line, evidence, severity (Critical for immediate alerts delayed or dropped by caps and digests; High for no caps, uncoalesced bursts, duplicates across devices, night sends; Medium for missing read-state checks, poor digest content, no measurement; Low for hygiene), and fix. Positive findings. Omit any section with nothing to report.