Notification Service Architecture

Bounded context: Alerting · Stack: Rust / Axum · Code-level walkthrough: Notification Service

The notification realises the Alerting context. Architecturally it is a rule engine and dispatcher: it decides whether an event warrants an alert and fans it out to the right people across more than one channel.

Architectural Style

Ports & Adapters — driving adapters → use cases → ports → driven adapters — organised around two responsibilities that map directly onto the context’s two aggregates: managing where a principal can be reached, and what they have chosen to receive.

The service has two driving adapters into the same use cases, not just one. HTTP requests arrive through adapters/driving/http_api; breach alerts also arrive through adapters/driving/alert_listener.rs, a Kafka consumer on the alerts topic — a driving path with no controller in front of it, since there’s no HTTP request to adapt. It keeps IN_FLIGHT records in flight at once, so a slow twin lookup never holds up the record behind it, and reconnects on its own if the stream dies. Both reach the same cooldown/domain-resolution/dual-delivery logic in service/alerts.rs.

graph TD
    subgraph "Driving adapters"
        HTTP["http_api/controllers.rs\nsubscribe · preferences · trigger"]
        EL["alert_listener.rs\nKafka consumer: alerts"]
    end
    subgraph "Use cases — service/"
        ALERTS["alerts.rs\ndebounce · resolve domains · dual delivery"]
        PUSH["push.rs\nrecipient resolution · fan-out · cleanup"]
        PREFS["preferences.rs\ndevice registration · opt-in writes"]
    end
    subgraph "Ports — service/ports.rs"
        P["NotificationBus · Cooldown · DomainDirectory\nSubscriptionStore · PreferenceStore · PushSender · Clock"]
    end
    HTTP --> ALERTS
    HTTP --> PREFS
    EL --> ALERTS
    ALERTS --> PUSH
    ALERTS --> P
    PUSH --> P
    PREFS --> P
    P --> TW[digital-twin: resolve domains]
    P -.-> DB[(notification-db)]
    P -.->|publish + cooldown| BR[(broker)]

POST /trigger and the alerts Kafka subscription — the path that actually fires for every automatic sensor-driven threshold breach (see Communication & Data Flow’s Threshold Alert flow) — both resolve recipients via digital-twin and dispatch on both channels; only the breach path is debounced. The HTTP route forwards the calling user’s own x-gateway-claims header to digital-twin’s building→domain lookup; the event-listener path has no HTTP caller to forward a token from, so it presents a fixed system identity instead (system_claims_header() in domain/identity.rs) — safe only because that specific digital-twin route (GET /domain/:building_name) doesn’t perform any per-identity authorization, it just requires a structurally valid claims header to exist.

The lookup client carries a 2-second timeout, matching socket’s. Without one a stalled digital-twin would block the alert pipeline forever and the unscoped fallback below would be unreachable — it only triggers on an error, and a hang never produces one.

The lookup client also caches, in process, like socket’s: building name → domains, 15-minute TTL, behind a Mutex<HashMap> in adapters/driven/twin.rs. Buildings change domain rarely, so a repeat alert costs nothing and a brief digital-twin outage is served from the cache instead of falling through to the unscoped broadcast. Two deliberate holes: an empty result is never cached, so a building that finishes provisioning is picked up on the next alert rather than staying unroutable for the whole TTL; and a failed lookup is never cached either. The map is bounded by building count and expired entries are only replaced on the next lookup, never swept — fine at this scale, revisit if a pod ever sees thousands of buildings. Cache is per pod: it is derived data, not session state, so the stateless golden rule still holds.

The TTL is picked by the staleness it costs, not the traffic it saves. Domains do change — PATCH /building/:id overwrites them (digital-twin’s BuildingService::update) — and the expensive direction is a domain being removed: until the entry expires, alerts for that building are still pushed to a domain that no longer owns it, and on the Kafka path nothing filters that, since a system: caller is Audience::Unrestricted. Meanwhile the 300s cooldown already caps lookups at one per building+room per 5 minutes, so raising the TTL from 15 minutes to 6 hours saves about four HTTP calls per hour per building and widens that window twenty-fourfold. The savings curve flattens almost immediately; the leak window does not. If the lookup ever genuinely shows up in a profile, invalidate on a building-updated event rather than lengthening the timer.

socket caches the same mapping at 60 seconds. The gap is deliberate, not drift: its copy gates may_read_building, an authorization decision on live telemetry, so it buys a tighter window at a higher refresh cost. Two different questions, two different numbers.

Because twin’s answer is unscoped, notification scopes it itself: the resolved domains are intersected with the caller’s own memberships before anything is published or pushed. See Notification Service’s membership table.

POST /trigger has a third caller besides the browser: digital-twin itself, on a failed building provisioning (Provisioning::fail, see Digital Twin Service. Same shape as the event-listener path — no end user in the loop, so it authenticates as a fixed system identity too — but it’s an in-mesh service-to-service call, not a Redis event.

Components & Connectors diagram

Key Architectural Decisions

• Two responsibilities, two models. Delivery channels and alert preferences are kept apart so a device can be revoked without losing choices, and choices can change without re-registering devices.
• Dual-channel delivery, on every alert path. trigger and the automatic alerts listener both dispatch an in-app event (through the broker) and a push to offline devices, so reachability does not depend on the app being open.
• Repeat suppression, on the breach path. A 5-minute Redis-backed cooldown, keyed per metric, breached field, building and room (alert:{metric}:{field}:{buildingId}:{roomId}), stops the same condition from re-alerting on every reading — including the automatic sensor-driven path, which is the one under the most repeat-alert pressure (a stuck sensor reading the same breach every tick).
• Recipient resolution by collaboration. Where a path resolves recipients at all, it asks digital-twin which domains a building belongs to and translates that into recipients, rather than keeping its own copy of building structure (an anti-corruption boundary).
• Self-pruning channels. A delivery channel that the provider reports as permanently dead (410/403) is removed automatically on the next push attempt, keeping the model clean without a scheduled job.

Integration

• Owns notification-db; no other service reads it.
• Receives breach events from telemetry via the Kafka alerts topic (group alerts, auto.offset.reset=earliest; the payload is telemetry_schema::AlertEvent; a metric outside telemetry_schema::ALERTABLE_METRICS has no delivery path — it is logged, counted unsupported_metric and settled); publishes to the notifications Redis channel for socket to relay — see Communication & Data Flow.
• Calls digital-twin to resolve a building’s domains — from the authenticated HTTP alert route (trigger, forwarding the caller’s own claims, then intersecting the answer with their memberships) and from the alerts event listener (using a fixed system identity, since there’s no caller to forward).
• Called by digital-twin on a failed building provisioning (POST /trigger, system identity, in-mesh) — see Digital Twin Service.

For the throttle mechanics, VAPID delivery, the cleanup behaviour, and the API, see the Notification Service internals page.