[Feature] Notifications: a bell with an unread badge, a notification history, and delivery settings per person

claude-bot commented

2026-09-15 18:08:21 +00:00

Collaborator

Context

Discussions (#654) need this: a new group question notifies everyone. Several v4.6.0 issues need it as well:

#121: a flag has to reach the GM
#122: the prompt after a session
#123: a handout given to one player

What exists today:

Email over SMTP, configured in Admin. It sends recap emails, controlled by a per-user users.recap_email_opt_in and a per-campaign recap_email_enabled, plus iCalendar invites (#189).
Posts to the campaign's Discord channel through the bot.
Needs you (GET /api/users/me/attention, #368).

There is no in-app history of what you were notified about, and no general preferences model.

Decisions (owner, 2026-09-15)

A bell in the corner of the top bar, with a red badge when anything is unread. Opening it lists everything you have been notified of, newest first.
Delivery is each person's choice. In their own settings, people decide whether to also get alerts by email or through any other channel that can send them.
This absorbs #12 (notification preference granularity). #11 (the weekly digest) stays in v5.4.0 as a delivery option built on this.
It ships in v4.6.0 with #654. The redesign (#366) leaves room for the bell in the top bar now, rather than adding it later.

Design

The bell is not Needs you. Needs you is what is waiting on you, and it empties as you act. The bell is a history of what happened. One event can be in both: "a new question for you" is a notification, and while it is unanswered it is also in Needs you.
A notification stores:
- the recipient and campaign
- the event type
- a reference to its subject (a thread, post, session or article)
- when it was created and when it was read
Its text is built when it is opened, from the subject and with the reader's permissions. If the reader can no longer see the subject, the entry says it is no longer available rather than showing what it once said.
Recipients are worked out on the server with the shared audience model (#593). Nobody is notified about something they cannot see.
Delivery channels are small adapters, so adding one later is easy:
- in-app, always
- email, through the existing SMTP path
- Discord DMs, through the bot (the backend never calls Discord itself)
- browser push, later, for the installed PWA
External alerts carry a short line and a link, never the content, so a GM's secret is never copied into someone's inbox.
Settings stay simple, following #12's rule: campaign settings enable a capability, and personal settings opt in or out. Rather than a toggle for every event:
- a few categories (Sessions, Discussions, Wiki, GM tasks)
- a channel choice for each
- a mute for each campaign
Existing behaviour carries over. Today's recap-email opt-in becomes a setting in the new model, and nobody's current email changes on the day this ships.
Delivery happens in the background (Celery). It must be safe to retry, so one notification is sent at most once per channel.

Out of scope

The weekly digest (#11).
The content of Discord embeds (v5.4.0).
Browser push, for now.

Acceptance criteria

The bell and unread count are in the top bar on phone and desktop. Opening it lists notifications, and one or all can be marked read.
A test shows that no notification reaches someone outside its subject's audience.
Email follows each person's settings, and existing recap-email opt-ins behave exactly as before.
A subject the recipient can no longer see shows as unavailable in their history, without its old text.
#654's rules hold: a new group thread notifies every member, and replies notify only followers.

## Context Discussions (#654) need this: a new group question notifies everyone. Several v4.6.0 issues need it as well: - #121: a flag has to reach the GM - #122: the prompt after a session - #123: a handout given to one player What exists today: - **Email over SMTP**, configured in Admin. It sends recap emails, controlled by a per-user `users.recap_email_opt_in` and a per-campaign `recap_email_enabled`, plus iCalendar invites (#189). - **Posts to the campaign's Discord channel** through the bot. - **Needs you** (`GET /api/users/me/attention`, #368). There is no in-app history of what you were notified about, and no general preferences model. ## Decisions (owner, 2026-09-15) - **A bell in the corner of the top bar,** with a red badge when anything is unread. Opening it lists everything you have been notified of, newest first. - **Delivery is each person's choice.** In their own settings, people decide whether to also get alerts by email or through any other channel that can send them. - **This absorbs #12** (notification preference granularity). **#11** (the weekly digest) stays in v5.4.0 as a delivery option built on this. - **It ships in v4.6.0 with #654.** The redesign (#366) leaves room for the bell in the top bar now, rather than adding it later. ## Design - **The bell is not Needs you.** Needs you is what is waiting on you, and it empties as you act. The bell is a history of what happened. One event can be in both: "a new question for you" is a notification, and while it is unanswered it is also in Needs you. - **A notification stores:** - the recipient and campaign - the event type - a reference to its subject (a thread, post, session or article) - when it was created and when it was read **Its text is built when it is opened,** from the subject and with the reader's permissions. If the reader can no longer see the subject, the entry says it is no longer available rather than showing what it once said. - **Recipients are worked out on the server** with the shared audience model (#593). Nobody is notified about something they cannot see. - **Delivery channels are small adapters,** so adding one later is easy: - in-app, always - email, through the existing SMTP path - Discord DMs, through the bot (the backend never calls Discord itself) - browser push, later, for the installed PWA External alerts carry a short line and a link, never the content, so a GM's secret is never copied into someone's inbox. - **Settings stay simple,** following #12's rule: campaign settings enable a capability, and personal settings opt in or out. Rather than a toggle for every event: - a few categories (Sessions, Discussions, Wiki, GM tasks) - a channel choice for each - a mute for each campaign - **Existing behaviour carries over.** Today's recap-email opt-in becomes a setting in the new model, and nobody's current email changes on the day this ships. - **Delivery happens in the background** (Celery). It must be safe to retry, so one notification is sent at most once per channel. ## Out of scope - The weekly digest (#11). - The content of Discord embeds (v5.4.0). - Browser push, for now. ## Acceptance criteria - The bell and unread count are in the top bar on phone and desktop. Opening it lists notifications, and one or all can be marked read. - A test shows that no notification reaches someone outside its subject's audience. - Email follows each person's settings, and existing recap-email opt-ins behave exactly as before. - A subject the recipient can no longer see shows as unavailable in their history, without its old text. - #654's rules hold: a new group thread notifies every member, and replies notify only followers.

Rows
Columns

[Feature] Notifications: a bell with an unread badge, a notification history, and delivery settings per person #655

Context

Decisions (owner, 2026-09-15)

Design

Out of scope

Acceptance criteria