docs: design notification system#1135
Draft
mistercrunch wants to merge 3 commits into
Draft
Conversation
Add design doc for a centralized notification system: bell + panel on the navbar, durable per-user inbox, three notification types in v1 (mention, session_returned, global_admin), and a toast-vs-notification rule. Takes positions on the open questions in the brief — collapse session-returned per (user, session, type), interaction-based default subscription, click marks read but doesn't dismiss, navbar message ticker cut from v1, sticky admin banner in the navbar center slot. No code yet — design + open questions + phased plan + effort estimate. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
… subs Per Max's review: - Drop `dismissed_at` column. Dismiss = hard-delete the row. No soft-delete state, no use case for keeping dismissed rows. Simplifies schema and queries. - Add §6.3 explicitly contrasting three subscription layers: implicit (v1, derived from interactions), explicit mute (v1.5, tiny opt-out table), full subscription primitive (v2 or never). - Fix §10 row 8 — earlier draft incorrectly said `data.muted_at` at the session level, which would mute it for everyone. Mute is per-(user, session); needs the new table, not a session field. - Add archive-time cleanup: when a session/worktree is archived, sweep its notification rows (and v1.5 mute rows) so users don't see stale invitations to retired sessions. - Add latest-task-only note in §5.2: collapsed `session_returned` surfaces only the most recent completion; older ones are not logged in the panel. The session detail panel is the log. - Simplify indexes (drop dismissed_at column from primary read index). - Narrow v1.5 retention scope to "aged read rows" (dismissed are gone immediately now). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…A..Q-G Generalize mute table and lock in remaining open questions. Schema/model changes: - Rename `session_notification_mutes` → `notification_mutes` with a polymorphic `(scope_type, scope_id)` key. Producer subtracts users who muted any scope an event falls under (session, comment_thread, worktree, board). Catches comment threads, which the previous session-only design missed. - Add §4.1 making explicit that `session_returned` fires per task completion (not per message), and the preview is the last assistant message of the completed task — same fetch logic as the parent- callback design. Individual messages never trigger notifications. - §3.6: client suppresses the toast when source page = current route (notification still created server-side; just no double-signal). Decisions made (all moved from "deferred" to "decided" in §10): - Q-A: Interaction-based subscription. Decided. - Q-B: Explicit data.mentions[] preferred; substring acceptable stop-gap. Decided. - Q-C: Assistant-session variant deferred until is_assistant marker exists. Decided. - Q-D: Retention sweep promoted to v1 (90-day aged-read delete). Decided. - Q-E: Fire on FAILED. Decided. - Q-F: Context-aware toast suppression. Decided. - Q-G: Skip self-mentions (recipient ≠ author). Decided. Effort estimate bumped to ~8d (was ~7-8d) to absorb retention sweep and toast-suppression line items. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Design doc (no code) for a centralized notification system in Agor: a bell + panel on the navbar, a durable per-user inbox, and a clear toast-vs-notification rule. Lives at
docs/notification-system-design.md.Key positions
mention,session_returned,global_admin. Worktree-created / session-created / environment / schedule events are explicitly out (too noisy or covered elsewhere).session_returnedcollapses per(user, session, type); mentions and broadcasts don't collapse.source_session_id(where you go);source_task_idis metadata.app.io.to(userRoomName(userId))atsocketio.ts:193,379). No new auth/channel infra.SettingsModal → Announcementstab, admin-role-gated.Things flagged for Max's call (in §10 of the doc)
data.mentions[]vs current substring detection for mention notifsis_assistantmarker existssession_returnedshould also fire on FAILED (recommended yes)What's in the doc
Test plan
board-comments🤖 Generated with Claude Code