Platform
Notifications
How somebody finds out that something happened.
Two audiences: the people on a client's account, and Acrune operators. Creators are not notified. Acrune holds no creator email address and should not start — that relationship belongs to the partner whose product the creator actually uses, which is the premise of the partner API. Partners get webhooks, which are a different contract and do not exist yet.
The path an event takes
apps/track notification_outbox apps/api the reader
something -> one row, unique -> resolve people -> feed + email
happened on a dedupe key honour prefsThe tracker knows what happened and nothing about people. It writes a row into
a table it owns and moves on. apps/api owns the people, the email queue and
the templates, so it reads that table, works out who should hear, and
delivers.
Reading across app ownership is what the dashboard already does with every tracker table. Writing across it stays forbidden, which is why this is an outbox and not a cross-app insert.
There is no queue, no event bus and no worker. The dispatcher runs on the same cron and the same opportunistic drain as the email queue.
Idempotency, twice
Producing is idempotent on a dedupe key the producer derives from the event
— campaign.first_click:<campaign id>. The first-click producer sits on the
redirect path and fires on every click, letting the unique index decide which
one was first. Reading to find out would put a SELECT on the only hot path in
the system to answer a question the index answers, and it is not awaited: a
redirect that is slower because a bell did not light up is a bad trade.
Delivering is idempotent on (user_id, dedupe_key). A claim that failed
halfway can be re-run and a digest can be recomputed on every cron without
anybody's feed growing a second copy.
What is delivered
| Kind | Who | Emails |
|---|---|---|
campaign.first_click | The account | Yes |
campaign.created | The account | No |
api_key.issued / api_key.revoked | The account | No |
links.missing_posts | The account, weekly | No |
outbox.stalled | Operators, and Slack | No |
Only one kind emails. The feed costs a reader nothing; an email is an interruption that has to earn itself, and the default for a new kind is in-app only until somebody asks otherwise.
links.missing_posts is the one that does real work. A link with no post URL
attached still counts clicks but cannot be ranked against the others, and
nobody discovers that by looking — the links appear fine. It only counts links
older than 48 hours, because telling somebody their hour-old campaign is broken
is how a channel gets muted on day one.
outbox.stalled is the system watching itself. A dispatcher that quietly stops
delivering is worse than none, because everybody downstream carries on
believing they would have been told.
Preferences
A column per kind on notification_preferences, one row per person — not per
organisation. Two people on the same account can want different things.
The column is part of the recipient query rather than a check after it, so a call site that forgets to filter is impossible to write. A missing row means every default, so nobody is backfilled and signing up costs no write.
email_enabled is a second axis, deliberately. Turning a kind off removes it
from the feed too; turning email off keeps every notification and stops any of
them leaving the building. Those are different wishes.
Sign-in links are unaffected by all of it. A sign-in link is not something anyone can meaningfully unsubscribe from, and withholding one because somebody left a notification stream would lock them out of their own account.
Deliverability
Three things protect the domain every sign-in link depends on:
Their own sender. Product notifications leave from
EMAIL_FROM_NOTIFICATIONS, which falls back toEMAIL_FROM.Worth being precise about what this buys, because it is easy to overstate: mailbox providers track reputation per domain and per sending IP, not per local part.
notifications@mail.acrune.comandhello@mail.acrune.comshare one reputation, so a distinct address makes the sender legible to a human and does nothing for deliverability. Separating the two so a complaint about a digest cannot reach the sign-in link needs a second verified subdomain, and that is only worth doing once notification volume could carry a domain's reputation on its own — two cold subdomains are worse than one warm one.Preview builds cannot mail a customer. In a preview deployment every recipient is rewritten to a sink address and the git branch is appended to the subject. A preview build has production credentials and real rows.
Bounces suppress themselves. Resend's webhook fills
delivered_at/opened_at/bounced_at/complained_aton the queue row, and a hard bounce or a complaint writes the address toemail_opt_outswithout anybody doing anything. Continuing to mail an address that bounced is how a sending domain gets blocked.
The webhook signature is verified against the raw body, before parsing.
Re-serialising a parsed object changes whitespace and key order, and the
signature never matches again. An unset RESEND_WEBHOOK_SECRET closes the
endpoint rather than opening it: it suppresses addresses, so an unverified one
would let anybody stop mail reaching anybody.
What is set up today
All application mail leaves as mail.acrune.com, verified in Resend: DKIM on
the resend selector, SPF via send.mail.acrune.com (include:amazonses.com,
since Resend sends over SES), and DMARC at p=quarantine; pct=100 with
aggregate reports going to contact@acrune.com. Google's reports show DKIM and
SPF both passing and nothing quarantined.
The apex acrune.com is Google Workspace and human mail only — its SPF names
no application sender and it carries no Resend selector. That separation is
already the valuable one: a problem with application mail cannot touch the
domain people actually correspond with.
Where the numbers come from
The feed is a table. Read state is server-side, so clearing the badge on a laptop clears it on a phone — which is the whole reason these are rows rather than something derived on the client. A notification is a thing that happened, and a thing that happened has to outlive the tab it arrived in.
Read notifications are deleted after 90 days by the same cron. Unread ones are kept.