/

Ambitwin · source-available, not open source · © 2026 Nicolò Ghignatti

Notification Schema

Keywords on this page
WordMeaningExample
CrateA Rust library other Rust code builds againstnotification-schema
NotificationOne message to people of one domain“Lab 2 Temperature is 31.4 °C”
BellThe in-app list of messages in the browserTop bar icon
Web PushA pop-up the browser shows even with the page closedSent through the browser maker’s push server
Service workerA browser script that receives Web Pushfrontend/public/service-worker.js
SeverityHow serious a message is: info, warning, dangerdanger for a breach
DomainA group of people and buildings inside an organizationeng
Room (socket)A named group of browser connectionsdomain:eng
FixtureA JSON file of example messages every language must agree onschemas/fixtures/notification.json

Rust crate at schemas/notification-schema. It holds the one message notification sends to people, and the Redis channel it travels on.

Depends only on serde and serde_json. Tests also use jsonschema.


Why one shape for two deliveries

notification delivers every message twice:

Both get the same Notification value, serialised by the same code. So the bell and the pop-up can never show different text for one event.

flowchart LR
    N["notification<br/>builds Notification"] -- "Redis channel notifications" --> S["socket<br/>routes on domainName"]
    S -- "event notification to room domain:eng" --> B["frontend bell<br/>type, message, timestamp"]
    N -- "Web Push, same JSON, encrypted" --> W["service worker<br/>title, message, icon"]

What is inside

ItemValueUsed by
NOTIFICATIONS_CHANNELnotificationsnotification publishes, socket subscribes
Severityinfo, warning, dangerField type; FromStr parses the text of POST /notification/trigger
NotificationThe messagenotification builds, socket parses, browser reads

The message

{"id":"1757251200000","type":"danger",
 "title":"Temperature Alert - Innovation Hub",
 "message":"Innovation Hub : Lab 2 Temperature is 31.4 °C (above maximum)",
 "timestamp":"2025-09-07T13:20:00.000Z","domainName":"eng","metric":"temperature"}
FieldRustRuleRead by
idid: StringMillisecond clock at build time, as textBell, to tell items apart
typer#type: SeverityOnly info, warning, danger. Anything else fails to parseBell colour
titletitleRequiredPop-up heading
messagemessageRequiredBell text and pop-up body
timestamptimestamp: StringISO-8601 in UTC with milliseconds, never a numberBell
domainNamedomain_nameRequired and not emptysocket, to pick the room
metricOption<String>Set on a breach only. Left out when emptyBell filter
iconOption<String>Left out when emptyService worker

Why a missing domain must fail

socket routes by domainName and never broadcasts. If a message with no domain parsed, socket would have no room for it. The safe outcome is “not a notification”: it is skipped.

Example. {"type":"danger",…,"domainName":""}

  1. socket calls serde_json::from_str::<Notification>.
  2. non_empty sees "" and returns must not be empty.
  3. get_notification_delivery_plan returns None. socket counts it as skipped. No browser gets it.

A breach notification end to end

sequenceDiagram
    autonumber
    participant A as notification<br/>Alerts::on_breach
    participant Dm as domain/notification.rs
    participant R as Redis
    participant S as socket<br/>shell/server.rs
    participant P as notification<br/>Push::to_domain
    participant W as Push server
    participant B as Browser
    A->>A: domains_for_building gives eng
    A->>A: fan_out, one round per domain
    A->>Dm: notification(now, now, Danger, title, message, eng)
    Dm-->>A: Notification, metric set to temperature
    A->>R: RedisBus publish: serde_json::to_string on notifications
    R->>S: message on notifications
    S->>S: consume, then get_notification_delivery_plan(text)
    S->>S: parse Notification, room_for_domain gives domain:eng
    S->>B: emit notification to room domain:eng
    B->>B: isVisible(message, preferences), then show in the bell
    A->>P: to_domain(sent, eng, temperature)
    P->>P: accounts_subscribed_to(eng, temperature)
    P->>W: WebPushSender send: serde_json::to_vec, encrypt, POST
    W->>B: push event
    B->>B: service worker: showNotification(title, body = message)

Data at each step

Example: a 31.4 °C breach in Lab 2 of Innovation Hub, building owned by domain eng, clock at 1757251200000.

StepHolderData
1on_breach["eng"]
3argumentsid and time 1757251200000, Danger, title Temperature Alert - Innovation Hub, message Innovation Hub : Lab 2 Temperature is 31.4 °C (above maximum), domain eng
4Notificationthe JSON above; timestamp from iso8601(1757251200000) is 2025-09-07T13:20:00.000Z
5Text on notificationsthe same JSON as one string
8Delivery in socketroom domain:eng, payload the parsed JSON
10Bellshown only if preferences["eng"]["temperature"] === true
12Accountse.g. ["ada"]: only accounts that switched temperature on for eng
13Push bodythe same JSON as bytes, then encrypted with the subscription’s keys
15Pop-upheading Temperature Alert - Innovation Hub, body the message, no icon

What the bell decides

frontend/src/utils/commons/notification.ts, isVisible:

flowchart TD
    M["notification arrives"] --> Q{"metric present?"}
    Q -- no --> Show["show: manual alert, nothing to check"]
    Q -- yes --> P{"preferences[domainName][metric] is true?"}
    P -- yes --> Show2["show"]
    P -- no --> Hide["hide"]

Push makes the same choice on the server, in accounts_subscribed_to. So one rule, applied in two places.


A manual notification

POST /notification/trigger builds the same shape, through Alerts::trigger:

  1. Empty message? Use Manual Alert Triggered.
  2. type given? Parse it with Severity::from_str. alert or any other word gives 400 type must be one of: info, warning, danger. No type: danger.
  3. buildingName missing: 400.
  4. Find the domains of the building, then keep only the ones the caller may reach.
  5. One notification per kept domain, title Ambitwin Alert, no metric. So the bell always shows it.

Example. {"message":"Fire drill at 15:00","type":"warning","buildingName":"Innovation Hub"} from a member of eng gives one warning to room domain:eng.


Tests

WhereChecks
tests/notification_conformance.rsEvery fixture case re-serialises byte for byte; every rejected case fails; Severity parses only its own names; channel is notifications
tests/notification_schema.rsEvery fixture case passes schemas/json/notification.schema.json; every rejected case fails it
tests/notification_preferences_schema.rsThe GET / POST /notification/preferences fixture against its schema
notification domain/notification.rsid is the clock as text; timestamp like 2023-11-14T22:13:20.123Z; type not kind; no icon by default
socket core/relay.rsEvery case routed to its domain room, every rejection skipped
frontend notification.spec.tsEvery severity has a colour; isVisible follows the stored preferences

Rejected cases in the fixture: no domainName, empty domainName, type: "alert", no title, a number as timestamp.

The preferences fixture has no Rust type here: only notification parses it, and it reads raw JSON. The crate hosts the schema check because it already depends on jsonschema.

mise exec -- cargo test --manifest-path schemas/notification-schema/Cargo.toml