Notification Engine

Overview

The notification engine is a multi-gate system that decides whether a disaster event should trigger an alert to a specific organization's teams. Every gate must pass for a notification to be sent. Every gate result -- pass or fail -- is persisted to a SystemActionLog for debugging and audit.

The system is intentionally conservative. False negatives (missing a real alert) are unacceptable, but false positives (unnecessary alerts) erode trust and cause alert fatigue. The five-gate architecture ensures that notifications are both targeted and reliable.

The Five Gates

Gate 1: Is the Event Actionable?

Only events with priority MEDIUM or HIGH are eligible for notifications. LOW and NOISE events are visible on the dashboard but never trigger alerts.

This gate eliminates the vast majority of events. Of the hundreds of events ingested daily, typically only 5-15% reach MEDIUM or HIGH priority.

Gate 2: Should This Trigger?

An actionable event triggers a notification only under specific conditions:

Re-scoring an event to the same priority level does not re-trigger notifications. An event that was already HIGH and gets re-scored as HIGH generates no new alert.

Gate 3: Idempotency Check

Before sending, the engine checks the SystemActionLog for an existing record with the same:

• disaster_event_id
• organization_id
• notification_type
• trigger_condition

If a matching record exists and its status is SENT, the notification is suppressed. This prevents duplicate alerts during retries, Inngest replays, or concurrent processing.

Gate 4: Organization Matrix Match

Each organization defines an alert matrix that maps event severity levels to teams. The matrix specifies exactly which alert levels an organization cares about and which teams should be notified.

The match must be exact. If an organization's matrix includes RED earthquakes but not ORANGE earthquakes, an ORANGE earthquake will not trigger a notification for that organization -- even though it is actionable.

This design lets organizations tune their alerting precisely. A small NGO focused on cyclone response can configure their matrix to only receive RED and ORANGE tropical cyclone alerts, ignoring all other event types entirely.

Gate 5: Country Relationship

The final gate checks whether the organization has a relationship with the affected country. Each organization maintains a country configuration with a VF entity (Visiting Forces) status:

If an event affects a country where the organization's VF entity is NO, the notification is suppressed regardless of how severe the event is.

Organization Matrices

An organization's alert matrix is the core configuration that controls notification routing. It is structured as a grid of alert levels, event types, and team assignments.

Matrix Structure

Key design decisions:

• A team can appear in multiple cells (e.g., Rapid Response handles all RED alerts)
• A cell can have multiple teams (e.g., both Rapid Response and Logistics for RED cyclones)
• Empty cells mean no notification for that combination
• GREEN alert entries are uncommon but supported for monitoring-focused teams

Country Configurations

Each organization maintains per-country settings that include:

• VF Entity Status -- relationship type (YES, PARTNERSHIP, MONITORING, NO)
• Deployment Likelihood -- HIGH, MEDIUM, LOW (feeds into scoring context modifier)
• Regional Assignment -- which regional team covers this country
• Notes -- free-text context about the relationship

Notification Types

Initial Alert

Sent when a new event first meets all five gates. Contains:

• Event type, location, and severity
• AI-generated situation summary
• Key measurements (magnitude, wind speed, etc.)
• Population exposure estimate
• Links to GDACS, USGS, or NHC source pages

Scheduled Follow-Ups

Automatic update notifications are sent at fixed intervals after event onset:

Each follow-up goes through all five gates again. If the event has been downgraded or archived between intervals, the follow-up is suppressed.

Priority Escalation

When an event's priority changes from LOW to MEDIUM or from MEDIUM to HIGH, an escalation notification is sent. The email clearly states the previous and new priority levels.

Downgrade Notification

When an event drops from HIGH to MEDIUM, a brief notification informs teams that the situation has de-escalated. This is important for resource allocation decisions.

Email Content Generation

Email content is generated by the Notify Agent (GPT-4o-mini) with live search grounding:

The agent receives:

• Event metadata (type, location, measurements)
• GeoPop data (affected countries, population)
• Recent search results (top 5 news articles)
• Organization context (team name, notification type)

It produces a professional, concise email that includes:

• One-paragraph situation summary
• Key facts (magnitude, location, affected population)
• Source links for further reading
• Clear subject line with priority tag

Fallback Content

If the Notify Agent fails (API timeout, rate limit), a template-based fallback generates the email from structured data alone, without AI-generated prose. This ensures that notifications are never blocked by an AI service outage.

Telegram Integration

In addition to email, notifications can be delivered to Telegram channels. Each team can optionally configure a Telegram bot token and channel ID. Telegram messages are a condensed version of the email content, formatted in Markdown.

Decision Audit Trail

Every notification decision is recorded in the SystemActionLog table, regardless of outcome. This enables answering the question "Why wasn't organization X notified about event Y?"

The gate_results JSON field records the result of each gate:

{
  "gate_1_actionable": { "pass": true, "priority": "HIGH" },
  "gate_2_trigger": { "pass": true, "reason": "new_event" },
  "gate_3_idempotency": { "pass": true, "existing_count": 0 },
  "gate_4_matrix": { "pass": true, "matched_teams": ["rapid-response"] },
  "gate_5_country": { "pass": false, "country": "SY", "vf_entity": "NO" }
}

In this example, the notification was suppressed at Gate 5 because the organization's VF entity for Syria is "NO". The audit log makes this immediately diagnosable.

Notification Flow Summary