The notify service tells people what happened on the network while they were not looking. For example, when someone replies to your comment, notify adds a row to your inbox and sends you an email. The web app, the desktop app, the vault and the mobile app all read their notification inbox from it.
The service does four jobs:
Notify always lives on a site's own origin, at /hm/api/notify. The hosted service is https://hyper.media/hm/api/notify, and the development one is https://dev.hyper.media/hm/api/notify. A self-hosted site serves it at https://<site>/hm/api/notify. The reverse proxy in front of the site sends that prefix to the service.
Notifications come from one place. The desktop app does not find its own notifications over peer-to-peer sync. The notify server is the only source, and read state syncs only when a client is online.
This page is the map of the program. The notify API is the reference for its HTTP routes, for how a client finds the service, and for the read-state rules.
Where the code is
The code is in frontend/apps/notify, package @shm/notify. It is a Bun service with no user interface, built on Bun.serve, bun:sqlite, nodemailer and Sentry (@sentry/bun). It serves no HTML. The email settings page is part of the web app. The email templates are a separate package, frontend/apps/emails (@shm/emails, written in MJML). That package also builds every link an email carries (notify-links.ts).
Path | What it holds |
|---|---|
| Boot: opens the database, starts |
| The route table: canonical paths, legacy aliases, CORS preflight. |
| The SQLite schema, migrations and statements. |
| The loops that read the activity feed, classify events, write inbox rows and send email. |
| The unified state API: snapshot and actions. |
| The check of request signatures and of the |
| The email sender: the hosting email relay when configured, SMTP otherwise. |
| One module per endpoint, exporting |
| The code every client shares: the client transport, the payload shape, the read-state logic and the comment classifier. |
frontend/apps/notify/README.md is the file-by-file map of the service and its clients. This page describes how the pieces work together.
How it talks to the daemon
The service holds one gRPC-web client to DAEMON_HTTP_URL, the daemon's HTTP port. It uses the daemon for three things:
It reads ActivityFeed.ListEvents, page by page, for new events.
It asks AccessControl.ListCapabilitiesForDelegate whether a signing key holds an AGENT capability for the account it claims.
The hosted service reads from the daemon of the hyper.media gateway, so it sees what that node has synced.
The notifier
When it starts, the service processes new events once. Then it runs two loops.
Loop | Every | Produces |
|---|---|---|
Immediate | 15 seconds |
|
Batch | 30 seconds, sending at most every 4 hours (6 minutes in development) |
|
Each loop keeps a cursor in the notifier_status table, so it knows where it stopped. An event id comes from the blob: blob-<cid> or mention-<cid>-<type>-<target>. The same id is the key of the inbox row and the key of the read state. One pass of a loop reads at most 100 pages.
Three things send no notification:
A document change. Nobody gets email when a document changes. site-doc-update is in the payload schema and the notifyOwnedDocChange flag is in the settings, but the notifier does not deliver document updates.
A digest in the inbox. The batch loop only sends email. It does not write digest notifications to the inbox.
A new capability. The notifier does not look at Capability blobs. So when you give someone a writer capability, they get nothing.
The immediate loop moves its cursor forward in a finally clause. So a pass that fails part way still marks its events as processed. A short daemon or SMTP failure can then lose the notifications of that pass. The loop writes inbox rows before it tries email, so an email failure alone loses only the email.
Storage
The service keeps one SQLite file, web-db.sqlite, in DATA_DIR or in the working directory. These are the tables that matter:
Table | Holds |
|---|---|
| The saved notification payloads of each account. |
| A "read everything before this time" watermark per account, plus explicit reads above it. |
| An account's notification email and its verification. |
| Accounts registered for an inbox, used by the notifier and the vault. |
| The older public site subscriptions and the one-click unsubscribe tokens. |
| Loop cursors and the last batch send time. |
The watermark is one time per account: everything before it is read. So "mark all as read" changes one row, and you can still mark a single item as unread again. The notify API gives the read-state rules.
Configuration
Variable | Meaning |
|---|---|
| The daemon to read. |
| The port to listen on: 3000 by default and in the Docker image, 3060 for |
| Where |
| The gateway site used for document links when a document's own site is unknown. It is also the origin of email links when |
| This service's own public base URL, normally |
| Outgoing mail over SMTP. The default is STARTTLS on port 587. Port 465 switches to implicit TLS, which is unreliable under Bun. Without a host, user and password, and without a relay, the service logs each email and does not send it. |
| The Seed hosting email relay. Each email is one |
| The vault origins that this service trusts when they say an email address is already verified. |
| Error reporting. |
Running it
pnpm notify # bun --watch on :3060, against the desktop dev daemon on 58001
pnpm notify:standalone # its own daemon on 54000-54002 and notify on :3061
pnpm notify:build # bun build: one self-contained bundle, build/main.js
pnpm --filter @shm/notify test # vitest for the mocked suites, then bun test for *.bun.test.ts (bun:sqlite)./dev up starts it as the notify pane and points the vault pane at it. The images are seedhypermedia/notify:dev, built from main, and seedhypermedia/notify:latest, built for releases. An image is oven/bun running the built bundle as uid 1001 on port 3000, with data in /data (set DATA_DIR=/data).
Working with it
In the Seed app
The desktop app keeps a local notification store and syncs it with the notifications route. The store shows your change at once, before the server confirms it. The app signs each request through the daemon's SignData call.
The store is in the main process, in frontend/apps/desktop/src/app-notifications.ts. The app saves it in Electron app storage under the key NotificationsState-v001. For every key in the daemon's keystore, the store holds three things:
The last snapshot: the inbox, the read state and the email config.
A queue of actions the server has not confirmed.
The time and the error of the last sync.
A change in the interface goes through these steps:
The app applies the change to the local snapshot and adds it to the queue.
A sync fetches the server's snapshot and applies the queue on top of it.
If the queue is not empty, the sync sends apply-notification-actions.
The app drops the actions that the server applied.
The sync runs every 30 seconds while a window has focus, every 5 minutes when none has, and when the app asks for it. The renderer reads the local store over tRPC and never calls the notify service itself. So the desktop app can show state that the server has not confirmed, and old state while the service cannot be reached. The files app-notification-config.ts, app-notification-inbox.ts and app-notification-read-state.ts beside it are thin tRPC wrappers over the one store.
Seed API
The notify API has the routes, the way requests are signed, and the way a site tells clients where its notify service is.
The web app's /hm/notifications page is the browser client, in frontend/apps/web/app/web-notifications.ts. It works like this:
It reads the notify URL stored beside the session key in IndexedDB.
The browser signs the CBOR request with WebCrypto. It adds accountUid, because the session key signs for the account and is not the account's own key.
It fetches the snapshot into React Query. It applies each action to the cached snapshot before it sends the action, and fetches again after the server answers.
The browser never classifies feed events. It only shows the NotificationPayload rows that the service saved.
The web app has a second, older way to turn on email. It is the unsigned subscribe form in email-notifications.tsx, which the app also offers after you comment. The form posts JSON to /hm/api/public-subscribe and creates a site subscription for the address. It is separate from the signed inbox. It has its own settings page, /hm/email-notifications, which the web app serves. A token in the link opens that page, and the page calls email-notif-token.
SDK
The SDK has no notify client. The client code is in @shm/shared (models/notification-service.ts). You can write your own with the SDK's CBOR and signing helpers.
Agents
Seed Agents do not use the notify service. The app environment watches the activity feed itself. See triggers.
See also
The notify API, for the routes, URL resolution and read-state rules.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime