Mission Alerting System - Technical Overview

mission-alerting-system.md

Mission Alerting System - Technical Overview

Overview

The Mission Alerting System enables real-time rule-based alerting on detection events from cameras and sensors. When a detection event matches a CEL (Common Expression Language) rule, the system executes configured actions (SMS notifications via Twilio).

Architecture

Detection Events (NATS)  →  Detection Consumer  →  Rule Processor  →  SMS Delivery
                                                        ↑
                                                   Rule Repository (PostgreSQL)
                                                        ↑
                                                   gRPC API (CRUD)

Components

Detection Consumer: Subscribes to NATS JetStream for AnnotatedImage messages from the object detection pipeline. Transforms detections into MissionEvent structs for rule evaluation.

Rule Processor: Evaluates CEL expressions against event context. Supports variables like label, facts.confidence, region, hardware_id, and derived fields like IsPerson. Executes actions when rules match.

Rule Repository: PostgreSQL persistence via Ent ORM. Stores rules with CEL expressions, enabled state, action configurations, and soft-delete timestamps.

Alert History: Persists all rule evaluations (triggered or not) for audit and debugging.

gRPC API

Service: MissionRuleService (port 8081)

Method	Description
CreateRule	Create rule with CEL expression and SMS actions
GetRule	Retrieve rule by ID (supports include_deleted option)
UpdateRule	Modify rule expression, actions, or enabled state
DeleteRule	Soft-delete rule (sets deleted_at_ms timestamp)
ListRules	List rules for a mission (supports enabled_only, include_deleted)
SetRuleEnabled	Toggle rule on/off
ValidateCelExpression	Validate CEL syntax before saving

Soft Delete Support

Rules support soft deletion with the following behavior:

• DeleteRule sets deleted_at_ms timestamp instead of hard deletion
• GetRule and ListRules exclude soft-deleted rules by default
• Set include_deleted: true in requests to retrieve soft-deleted rules
• Response includes is_deleted boolean and deleted_at_ms timestamp

Timestamps

All timestamp fields use _ms suffix to denote epoch milliseconds:

• created_at_ms: Rule creation timestamp
• updated_at_ms: Last modification timestamp
• deleted_at_ms: Soft deletion timestamp (optional, present only if deleted)

NATS Integration

Input: Consumes from IMAGES stream on subjects matching *.*.*.*.images.annotated.*

Message Format: Protobuf AnnotatedImage containing detected objects with labels, confidence scores, and bounding boxes.

Rule Configuration

Rules consist of:

• CEL Expression: Boolean expression evaluated against event context (e.g., label == "person" && facts.confidence > 0.9)
• Actions: List of SMS actions with phone numbers and message templates
• Message Templates: Support placeholders like {{label}}, {{facts.confidence}}

Event Context Variables

Variable	Type	Description
event_id	string	Unique detection event ID
label	string	Detected object class (person, car, etc.)
facts	map	Detection metadata (confidence, counts, etc.)
region	string	Deployment region
customer_id	string	Customer identifier
facility_id	string	Facility identifier
hardware_id	string	Camera/sensor ID
IsPerson	bool	Derived: true if label contains "person"

Usage

1. Create rules via gRPC specifying mission ID, CEL expression, and SMS recipients
2. Enable alerting by starting the service with --enable-alerts flag
3. Configure Twilio via --twilio-sid, --twilio-token, --twilio-phone flags
4. Monitor via alert history queries or NATS status subjects

Dependencies

• PostgreSQL 15+ (rule and history storage)
• NATS JetStream (detection event streaming)
• Twilio (SMS delivery)