Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
Adding a notification kind
A notification kind is one NotifEvent variant. It is stored as a tagged JSON row,
pushed to phones, streamed to clients, served over REST and GraphQL, and rendered
by a dozen web modules. The compiler finds the Rust half; TypeScript finds most of
the web half; the rest is listed here. Most past kinds needed a follow-up fix, and
those misses are called out inline.
If the notification is about an entity type that has never carried notifications (it has no inbox rows, mark-done, or mute yet), do that first with add-entity.md; this guide assumes the entity side exists.
Pick a model to copy
| Building | Copy | Why |
|---|---|---|
| A kind on an existing entity, sent from a domain service | ChannelMessageReaction (crates/channels/src/outbound/notification_sender.rs) |
Newest end-to-end kind: push, realtime, GraphQL, inbox stacking, settings toggle |
| Kinds planned from domain events, with derived ids | AgentSession* (crates/agent_harness/src/domain/notifications.rs) |
Pure planner function, audience rules, idempotent ids, port + ingress adapter |
| A scheduled kind | CalendarEventReminder (crates/calendar_events/src/outbound/notification_notifier.rs) |
Fired by a poller, collapse key per occurrence |
Names: the variant is PascalCase; Notification::TYPE_NAME, the serde tag, the
notification_event_type column, and the web tag are all its snake_case
(channel_message_reaction). Pick it once. A rename later needs a serde alias
and a data migration (see "Renaming" below).
1. Metadata type (required)
In crates/model_notifications/src/metadata.rs (or a submodule like
metadata/crm_discussion.rs):
- Define
<Name>Metadatawith#[derive(Serialize, Deserialize, Debug, Clone, ToSchema)]and#[serde(rename_all = "camelCase")]. Doc every field; utoipa and GraphQL descriptions come from them. - Carry what clients need to render and navigate without another fetch (ids, a short content excerpt, display names). Do not carry anything you would not put in a push banner; the payload lands in the database, on phones, and in Kafka.
- Display names: carry a display name when the actor is not a Macro user (a bot, a GitHub login, an agent). Kinds that only carried an id later showed raw ids or emails in the inbox and needed fixes for bot and agent senders.
- Every field added after the first deploy must be
Optionor#[serde(default)]: rows already in thenotificationtable lack it, and a row that fails to decode silently disappears from lists. impl Notificationwithconst TYPE_NAME = "<snake_name>".impl NotificationTitle(format_title/format_body). This text is the push banner, the Android notification, and the email digest preview. Branch on subtype where it changes the noun (a document mention of a task says "task"; that was a fix). Render mention XML through the existingparse_message_plain_texthelpers so bot and user mentions show their names.- Push-capable kinds:
impl NotificationExtIos. Build the alert withalert_apns, and choosecollapse_keydeliberately. It replaces an earlier banner on the device and is also the Android identifier, so key it on what a newer notification should supersede (the reaction keys on message + emoji, a reminder on its reminder id). Android pushes are derived from the APNS payload incrates/notification/src/domain/service/egress.rs; there is no separate Android formatter. - Add title/body tests to
crates/model_notifications/src/metadata/test.rs.
Only invite-style kinds send direct email (NotificationExtEmail, see
crates/invite_email). Everything else reaches email through the digest, which
formats any NotifEvent via NotificationTitle.
2. Register the variant (required)
In crates/model_notifications/src/lib.rs:
- Re-export the type from the
pub use metadata::{...}list. - Add the variant at the end of
NotifEventinsidedefine_notif_event!. The macro fails the build ifTYPE_NAMEis not the variant'ssnake_case. Order matters for generated code: orval names union members by position (notifEventOneOfFivefive), so inserting in the middle renames dozens of generated web files. - Add arms to both
format_titleandformat_bodyinimpl NotificationTitle for NotifEvent.
Then decide two lists in other crates; nothing will force you to:
- Blockable: add
<Name>Metadata::TYPE_NAMEtoBLOCKABLE_NOTIFICATIONSinservices/notification_service/src/api/user_notification.rsunless users must not be able to turn it off (account-security kinds likeinbox_reauth_requiredstay out). The preferences endpoint rejects disabling any type not listed. - Category filter: check
push_include_types_filterincrates/notification/src/outbound/repository.rs. Categories mostly match onevent_item_type, andMessagealso matches any metadata with amessageId. A new kind filed under an existing entity type joins that category, which leaked agent rows into the channel filter once. GitHub kinds are a hand-kept list (GITHUB_EVENT_TYPES_SQL) because this crate cannot seemodel_notifications.
Add a to_typed_row_<snake_name> case to
services/notification_service/src/api/user_notification/test.rs.
3. Send it from the owning domain (required)
Follow the hexagonal architecture skill:
the domain decides whether and to whom; an outbound adapter calls
NotificationIngress::send_notification.
- Plan in the domain. A pure function from the domain fact to the
notifications it warrants, with tests for every audience rule. Copy
crates/agent_harness/src/domain/notifications.rs. - Port + adapter. A domain port (e.g.
AgentSessionNotifier) and an outbound adapter generic overnotification::domain::service::NotificationIngress(crates/agent_harness/src/outbound/notifications.rs). Build the request withSendNotificationRequestBuilder { notification_entity, secondary_notification_entity, notification, sender_id, recipient_ids }, then.into_request(),.with_apns()for a push, and.with_conn_gateway()for live delivery. - Wire the composition root. Services construct
SqsNotificationIngress { queue: SqsQueue::new(sqs, macro_queues::NotificationIngressQueue::new().to_string()) }(seeservices/agent_harness_service/src/main.rs). A service that has never notified also needssqs:SendMessageon the ingress queue: takenotificationIngressQueueArnfromgetMacroNotify()(infra/packages/shared/src/macro_notify.ts), asinfra/stacks/email-service/index.tsdoes.
Pitfalls, each of which shipped once:
- Sender. Set
sender_idto the acting Macro user; ingress then drops the sender from recipients. When the actor is not a Macro user id (GitHub, bots), filter the actor out yourself; users were notified of their own PR activity. - Audience. Recipients must be people who can open the entity, computed from live data. Participants from deleted messages, and the callee instead of the caller in DM call titles, were both fixes.
- Double notifying. If another path already notifies the same people about the same thing (a channel message mentioning them), emit nothing. Agent mention notifications duplicated channel mention notifications until fixed.
- No-op changes. Gate on whether the state actually changed. An
ON CONFLICT DO NOTHINGre-add of a reaction still published "added" and re-notified. - Idempotent ids. For event-driven producers, use
into_request_with_idwith a UUIDv5 derived from everything that makes two notifications distinct; ingress creates idempotently on the id. Leaving out a component (the question within a turn) silently swallows the second notification. Ingress also returns early for an existing id, so retrying a send whose row was written does not re-push. - Failure handling. A failed enqueue is logged and dropped, not retried into the caller's transaction (see the adapter's doc comment).
Push banners are rendered in the producing service (ingress messages carry the
built APNS payload), so a format_title change only reaches phones once that
producer redeploys.
4. GraphQL (required)
In crates/graphql_notification/src/notification_event.rs:
- A wrapper
pub struct Graphql<Name>Metadata(<Name>Metadata);with an#[Object]impl exposing each field (ids asID). - A variant in the
GraphqlNotifEventunion and an arm inFrom<NotifEvent> for GraphqlNotifEvent.
Regenerate the SDL and the web client (see crates/complete_graph/AGENTS.md):
cargo run -p complete_graph --bin graphql_schema -- static_assets/schema.graphql
cd apps/web && bun gen-graphql
Any SDL change rotates every persisted client GraphQL cache; that is expected.
5. REST spec and generated clients (required)
NotifEvent is registered in services/notification_service/src/api/swagger.rs,
so new metadata types are pulled in transitively; listing them there is optional.
Regenerate and commit:
cd apps/web && bun run gen-api notification-service # openapi.json, schemas, zod.ts
cd packages/sdk && bun run sync-specs && bun run generate
The web validates realtime notifications with the generated zod.ts; a stale one
logs parse warnings for the new kind. Never hand-edit generated/ or specs/.
6. Web (required for anything user-visible)
The GraphQL union is mapped back to the REST NotifEvent shape, and every web
consumer matches on notification_metadata.tag.
apps/web/src/lib/service-clients/service-storage/graphql/soup.graphql: add... on Graphql<Name>MetadatatoSoupNotificationNavigationMetadataFields(fields needed to route a click) orSoupNotificationMetadataFields. Alias every field with a variant prefix (channelMessageReactionMessageId: messageId); union members share field names with different types, which GraphQL rejects unaliased. Rerunbun gen-graphql.apps/web/src/lib/service-clients/service-storage/graphql-soup.ts: an arm inmapGraphqlNotificationMetadataending insatisfies NotifEventMember<'<snake_name>'>. Every GraphQL notification must go throughmapGraphqlNotification; a past bug bypassed it.- Exhaustive matches, which type-check will flag:
apps/web/src/features/notifications/notification-preview.ts(label)apps/web/src/features/notifications/notification-metadata.ts(action text, target)apps/web/src/features/notifications/notification-navigation.ts(click target)apps/web/src/features/entity/extractors-notification/notification-icon.tsxapps/web/src/features/entity/extractors-notification/notification-description-helpers.tsapps/web/src/features/entity/utils/notification.ts
- Non-exhaustive matches that silently fall through; check each:
apps/web/src/features/notifications/use-notification-updates.ts: refresh only the affected Soup entity. Broad invalidation here caused list refresh storms.apps/web/src/features/notifications/notification-stacking.tsandapps/web/src/features/notifications/notification-source.ts(CHANNEL_EVENT_TYPES)- Channel-thread scoping:
apps/web/src/features/notifications/channel-thread-root.ts,apps/web/src/features/notifications/top-level-channel-notification.ts,apps/web/src/features/soup/entity-notifications.ts, andapps/web/src/features/entity/utils/channel-thread-name.ts. Reactions initially vanished from thread rows because one helper did not know the tag. - Inbox:
apps/web/src/features/next-soup/soup-view/views/inbox/inbox-card-layouts.tsxandapps/web/src/features/next-soup/soup-view/views/inbox/utils.ts. - Desktop banners:
apps/web/src/features/notifications/notification-platform.tsandapps/web/src/features/notifications/notification-sender.tswhen the sender is notsender_id.
- Settings: if blockable, add an entry to
NOTIFICATION_EVENT_GROUPSinapps/web/src/features/notifications/notification-event-catalog.ts. It must matchBLOCKABLE_NOTIFICATIONS; no test checks that. - Mobile push taps retain the notification id for authenticated lookup through
notification-navigation.ts. iOS channel pushes also carry typednavigationdata (channel, message, and nullable thread-root IDs) plus a per-recipientrecipientId, allowing a matching signed-in account to open the destination before notification hydration. Add channel destinations incrates/model_notifications/src/metadata/channel_push.rsand the metadata'sNotificationExtIosimplementation; regenerate the service OpenAPI and the web push validators withscripts/generate-api-schema.ts. Older pushes and other notification kinds still follow the lookup path, so step 3 covers phones too. Never infer a root from an absent thread ID: the direct payload requiresthreadId: nullfor a known top-level message.
Mark done and mute act on the notification's entity, so an existing entity type
needs nothing more. Copy .otherwise arms rather than throwing: older tabs ignore
kinds introduced by a newer backend.
7. Server-built feeds (when relevant)
- Home work feed:
crates/attention_feed/src/domain/keying.rs(channel_thread_root) attributes channel notifications to thread roots, andcrates/work_feed/src/domain/stacking.rsstacks channel and comment events. A new kind defaults to a standalone stack (_ => None); add it to the thread-root andis_channel_event/is_comment_eventmatches if it belongs to a conversation. - Notifications inbox:
place_eventincrates/notification_inbox/src/domain/rows.rsmatches everyNotifEvent, so the compiler asks where a new kind's row goes: an existing slot, a new slot (one row per request id), or none. Hide noise there rather than dropping it, so done still acknowledges it. Give the row its actor inactorand any buttons inactions(as data; the client performs them). A new row type or action kind also needsInboxRowTypeorInboxRowActionKind, its GraphQL enum incrates/graphql_notification_inbox, and the regeneratedstatic_assets/schema.graphql; adding enum values is compatible, removing them is not. - Channel unread scoping: channel thread SQL in
crates/notification/src/outbound/entity_notifications.rslists event types by name. Add a channel-scoped kind there, with tests beside it.
8. Docs
Update the app agent guide page for the surface where
the notification appears (channels.md, home.md, notifications.md, ...).
Compatibility and observability
- Deploy order. Readers skip rows they can't decode: REST lists and the digest
drop them with a warning, and the web ignores unknown tags. A single
GETby id errors, and the document storage service's realtime consumer rejects unknown kinds. Ship the variant in the same change as its producer, and don't let a separately released producer emit beforenotification_serviceanddocument_storage_serviceare deployed. - Renaming. Keep the old tag readable with
#[serde(alias = "<old>")]on the variant and a migration rewritingnotification.notification_event_typeanduser_notification_type_preference.notification_event_type. Copycrates/macro_db_client/migrations/20260618152324_rename_call_started_notification_type.sql(generate the file withsqlx migrate add; see the database guide). - Privacy. Never put notification payloads on spans or in logs. Use
#[tracing::instrument(skip_all, fields(...))]with ids and the type name only;retand default argument capture leaked payloads and were fixed twice. See the observability rule. - Malformed messages. Ingress acknowledges and drops messages it can't decode; don't rely on SQS retries to fix a bad payload.
Verify locally
cargo test -p model_notifications
cargo test -p notification_service
cargo test -p graphql_notification
cargo test -p <producing crate> # with SQLX_OFFLINE unset
cargo run -p complete_graph --bin graphql_schema -- static_assets/schema.graphql
cd apps/web && bun run gen-api --check && bun run check
cd packages/sdk && just check && just coverage
Then trigger the event on a local stack (running locally)
and confirm the row in the inbox, its click target, the live update in a second
tab, and the settings toggle. The live-debug skill shows the ingress and egress
spans; local-e2e notification tests live in
crates/integration_tests/local_e2e/tests/channel_mutations.rs.