Skip to content

Sub-Domain Blueprint: Unified Signals & Notifications

Domain: Unified (audit, communications, identity, library, notifications, search, signals, vault, workflow) Logical Sub-Domain: Signals (Observation & Alerting) Physical Packages: @sd/mod-unified-signals, @sd/mod-unified-notifications Related Documents: Data Definition Context: This document defines the Event Bus, Alerting Logic, and Automated Digest systems. Status: Stable (v2.5)

1. Mandate

The Signals Sub-Domain is the Nervous System of the platform. It ingests raw telemetry (IoT, Webhooks) and internal events, normalizes them into SystemSignals, and routes them to: 1. Reflex: Immediate alerts via NotificationService (for Critical items). 2. Digestion: Asynchronous summarization by the SignalAgent (for Info items).

2. Capabilities

Capability Description Component
Event Bus Centralized emission of system events (emit). SignalService
IoT Ingestion Normalizing raw webhooks from devices (e.g. Shelly) into Signals. SignalService.ingestWebhook
Reflex Alerting Immediate dispatch of Critical signals to Operations channels. SignalService (Reflex Logic)
Notification Dispatch Routing messages to users via In-App, Email, or SMS based on preferences. NotificationService
Auto-Digestion "News Feed" generation from low-priority signals (Mock AI). SignalAgent

3. Process Models

A. The Signal Loop (IoT Alarm)

Happy Path for a Critical Hardware Failure.

sequenceDiagram
    participant Device as IoT Sensor
    participant Bus as SignalService
    participant Notif as NotificationService
    participant Ops as OpsTeam

    Device->>Bus: POST /webhook (temp=90C)
    Bus->>Bus: ingestWebhook() -> Normalizes to CRITICAL Signal
    Bus->>DB: save(SystemSignal)

    rect rgb(255, 200, 200)
    Note over Bus, Notif: Critical Reflex Triggered
    Bus->>Notif: dispatch("global_ops", URGENT_ALERT)
    Notif->>Ops: SMS/Email "CRITICAL: Device Alarm"
    end

B. Daily Digest (Info/News)

Happy Path for summarizing daily activity.

sequenceDiagram
    participant Scheduler
    participant Agent as SignalAgent
    participant Bus as SignalService
    participant Editor as CMS

    Scheduler->>Agent: runDailyDigest()
    Agent->>Bus: getUnprocessed(limit=100)
    Bus-->>Agent: [DocAdded, ProjectUpdate, UserJoined...]
    Agent->>Agent: Group & Summarize
    Agent->>Editor: createDraft("Daily Digest", content)
    Agent->>Bus: markProcessed(ids)

4. State Machines

Notification Delivery

stateDiagram-v2
    [*] --> Created
    Created --> Dispatched: Channel Resolution
    Dispatched --> Sent: Provider Accepted (Resend/Twilio)
    Sent --> Read: User Opens
    Read --> [*]

5. Interface Definitions

SignalService

  • emit(signal): Promise<string>
  • ingestWebhook(payload, meta): Promise<string>
  • getUnprocessed(): Promise<SystemSignal[]>

NotificationService

  • dispatch(recipientId, template, data): Promise<Result>
  • setPreferences(userId, prefs): Promise<Prefs>

6. Changelog

Date Author Description Reference
2026-01-24 Antigravity Initial creation Implementation Plan