# 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 prefs
```

The 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 to `EMAIL_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.com` and `hello@mail.acrune.com`
share 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_at` on the queue row, and
a hard bounce or a complaint writes the address to `email_opt_outs` without
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.
