Notifications

What this is

Notifications is one inbox for the whole account: every project you belong to writes into the same list, read against your own user, not against whichever project happens to be selected right now (api/routers/notifications.py#list_notifications). A separate endpoint tracks how many are unread, read independently of the list itself, so the badge in the app chrome never depends on how many rows the list happens to have loaded (#unread_count).

Seven kinds, and where each comes from

Seven kinds exist today, one write site each, and nothing else in the product writes to this table: every Notification(...) construction in the backend was checked, and these seven are all of them.

• visibility_digest: the daily watchdog run described in Alerts (api/services/watchdog.py#run_watchdog_for_project, #VISIBILITY_DIGEST)
• weekly_report_ready: a week's Weekly report finishing (api/services/weekly_report.py#_notify_report_ready, #WEEKLY_REPORT_READY)
• growth_briefing_ready: a Growth Advisor briefing finishing (api/services/growth_advisor.py#_notify_briefing_ready, #GROWTH_BRIEFING_READY)
• llms_txt_audit_ready: an llms.txt Advisor run finishing (api/services/llms_txt/service.py#_notify_audit_ready, #LLMS_TXT_AUDIT_READY)
• citation_gaps_ready: fresh citation gap opportunities found for a project (api/services/citation_gap.py#notify_citation_gaps_ready, #_NOTIFICATION_KIND)
• optimization_ready: a new on-page recommendation ready to review (api/services/optimization/service.py#notify_optimization_ready, #OPTIMIZATION_READY_KIND)
• article_ready: a drafted article finishing (api/services/articles.py#_notify_article_ready, #ARTICLE_NOTIFICATION_READY)

The screen keeps its own copy of this same seven-entry table to decide each row's icon and where it links (frontend/src/routes/(app)/notifications/+page.svelte#KINDS).

The boundary with alerts

An alert and a notification are not the same thing, and they are not even one-to-one. When the watchdog described in Alerts persists one or more fresh alerts for a project, it writes exactly one visibility_digest notification per project member for that run, summarizing every alert together; a day with three alerts still produces one notification, not three (api/services/watchdog.py#run_watchdog_for_project). Going the other way, most notifications are not about an alert at all: six of the seven kinds above come from a report or a recommendation finishing, with no visibility_alerts row behind them anywhere.

Read, unread, and marking it so

A row's read state is a plain boolean you set directly, not a toggle the server flips for you: the caller sends the state it wants stored (api/routers/notifications.py#update_notification). One action clears every unread row on the account at once (#mark_all_read). The list itself returns up to 100 rows, newest first, optionally filtered to unread only; the screen asks for 50 and says so once that many come back (#list_notifications, frontend/src/routes/(app)/notifications/+page.server.js#ROW_CAP).

Delivery

Four of the seven kinds also send an email to the project owner, on top of the in-app row: the watchdog's digest, but only when the owner is on a paid plan (api/services/email.py#send_visibility_alert_email); the weekly report, also paid-plan gated (api/tasks.py#_email_weekly_report); and citation gaps and a finished article, sent to the owner whenever they have an email on file, with no plan check of their own (api/services/email.py#send_citation_gaps_ready_email, #send_article_ready_email). A growth briefing, an llms.txt audit and an optimization recommendation stay in-app only: nothing in the product sends an email for any of those three.

Whose project it is about

A notification can be about a project other than the one currently selected, since the inbox spans every project on the account, not just the current one. Each row's project name is resolved from your own project list, and a row whose project has since left that list, access removed, project deleted, renders with no link forward rather than sending you to an error (frontend/src/routes/(app)/notifications/+page.svelte#projectNames).

Related

• Alerts: the one kind of notification with a stored watchdog record behind it, and the only one covered here that is not itself a full report
• Weekly report: the other periodic email this inbox also carries a row for
• Growth Advisor: one of the three kinds that never leaves the app