Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

chore(devex): move today highlight sources into their products (#118394)

Julian Beze631807a4830
diff --git a/.agents/skills/adding-today-highlights/SKILL.md b/.agents/skills/adding-today-highlights/SKILL.md
new file mode 100644
index 000000000000..ad7aaaf01bfd
--- /dev/null
+++ b/.agents/skills/adding-today-highlights/SKILL.md
@@ -0,0 +1,71 @@
+---
+name: adding-today-highlights
+description: Add a "For you today" highlight source, the rule that turns a product's facts into items on the Today home page (firing alerts, flags that lose reach, ticket SLA breaches, workflow failures). Use when asked to "add a Today highlight", "show X in For you today", "surface X on the home page", or when changing an existing source's query, thresholds, copy or icon. Covers where the rule and its declaration live, the Today facade contract, scopes, caching, ranking inputs, tests, tach, and the frontend icon.
+---
+
+# Adding a Today highlight source
+
+Today ranks facts that other products find and shows the best few in "For you today".
+The product that owns the data owns its source: the query, the thresholds, and the copy.
+Today owns the contract, the ranking, the shared helpers, and its own pulse (routine and key-metric tiles, pinned numbers, home dashboard).
+
+**A source lives in its own product, never in `products/today/`.**
+Today has no list of sources to edit. It finds each product's declaration by module name.
+
+## Steps
+
+1. Write the rule in the product's internals, for example `products/<x>/backend/today_highlights.py`, or a package of that name when the product has several sources.
+ The rule takes a `HighlightContext` and returns `HighlightFindings`.
+ Read the facts through the product's own code. Read other products only through their facades.
+2. Declare it in `products/<x>/backend/facade/today_highlights.py`:
+
+ ```python
+ """<Product>'s sources for the "For you today" list. Today finds this module by name."""
+
+ from products.today.backend.facade.contracts import HighlightSource
+
+ from ..today_highlights import find_stale_things
+
+ HIGHLIGHT_SOURCES = (HighlightSource(name="stale_things", find=find_stale_things, scopes=("thing:read",)),)
+ ```
+
+3. Add `"products.today"` to the product's `depends_on` in the root `tach.toml`, with a `# Facade-only:` comment like the other products have. Today gets no new dependency.
+4. Test the rule in the product with `products.today.backend.facade.testing.highlight_context`.
+ `products/alerts/backend/tests/test_alert_today_highlights.py` is a short example.
+ A test folder without `__init__.py` needs a product-specific file name, so pytest does not collide on `test_today_highlights.py`.
+5. The row icon comes from the product. If `PRODUCT_ICONS` in `frontend/src/scenes/project-homepage/today/todayRowIcons.tsx` has no entry for the product yet, add one. That file is Today's, so team-surfaces reviews it.
+
+`products/feature_flags/backend/today_highlights.py` is a complete source with a reach drop and a cleanup item.
+
+## Contract
+
+Import only from Today's facade:
+
+- `facade/contracts.py`: `HighlightCandidate`, `HighlightFindings`, `HighlightContext`, `HighlightSource`, `HighlightMetric`, `DailyValueNotReady`
+- `facade/enums.py`: `HighlightLabel`, `HighlightUnit`, `HighlightInterval`
+- `facade/highlight_helpers.py`: number and text formatting, `uses_product`, and trend detection
+
+Rules that are easy to get wrong:
+
+- **The source name is a stable key.** Today stores results and analytics under it, so a rename breaks them. The registry raises when two products use the same name.
+- **`scopes`** lists the API scopes the viewer needs. Today skips the source when the viewer's scopes or access controls do not cover them.
+- **`context.daily(name, compute)`** caches one value per team, property restrictions and day, and every viewer with the same restrictions shares it. Never compute a per-viewer value there. Prefix `name` with the source name.
+- **`context.guard(name, provider, default)`** records a failure and returns the default instead of failing the whole list. Use it around each call that can fail on its own.
+- Raise `DailyValueNotReady` when a value the source needs is still computing. Today retries the source soon.
+
+## Ranking inputs
+
+Each `HighlightCandidate` carries what Today ranks on:
+
+- `label`: `risk` when something got worse or broke, `opportunity` when the person can act to gain.
+- `importance` from 0 to 1, and `relevance` from 0 to 1 for how much this viewer cares. Compare with existing sources before you pick a number: suspended email sending is 0.95, a firing alert 0.85, a flag that lost reach 0.6, a cleanup suggestion 0.3.
+- `family`: Today shows at most two items of one family.
+- `ref`: items of different families that share a ref are about the same object, so Today shows one of them.
+- `key`: stable for the same fact on the same day, for example `flag_reach_drop:<id>`.
+
+Copy follows `/writing-user-facing-copy`: one sentence with numbers in `title`, the comparison and the next action in `detail`.
+
+## Limits
+
+- A row looks the same for every source. A source that needs its own row or preview still needs a change in Today's frontend.
+- Only Today's own pulse tiles can be pinned.
diff --git a/frontend/src/scenes/project-homepage/today/Today.stories.tsx b/frontend/src/scenes/project-homepage/today/Today.stories.tsx
index 980e0d8771a7..6d34ca6b9324 100644
--- a/frontend/src/scenes/project-homepage/today/Today.stories.tsx
+++ b/frontend/src/scenes/project-homepage/today/Today.stories.tsx
@@ -660,6 +660,7 @@ const HIGHLIGHTS: HighlightsApi = {
score: 0.85,
priority: 'P1',
source: 'alerts',
+ product: 'alerts',
},
{
key: 'new_error:0195a0b2-0000-0000-0000-000000000001',
@@ -671,6 +672,7 @@ const HIGHLIGHTS: HighlightsApi = {
score: 0.82,
priority: 'P1',
source: 'errors',
+ product: 'error_tracking',
},
{
key: 'home:rev01',
@@ -682,6 +684,7 @@ const HIGHLIGHTS: HighlightsApi = {
score: 0.6,
priority: 'P2',
source: 'home',
+ product: 'today',
},
{
key: 'key_metric:payment_event',
@@ -693,6 +696,7 @@ const HIGHLIGHTS: HighlightsApi = {
score: 0.57,
priority: 'P2',
source: 'key_metrics',
+ product: 'today',
},
{
key: 'experiment_ended:12',
@@ -704,6 +708,7 @@ const HIGHLIGHTS: HighlightsApi = {
score: 0.6,
priority: 'P3',
source: 'experiments',
+ product: 'experiments',
},
{
key: 'assigned_quiet',
@@ -715,6 +720,7 @@ const HIGHLIGHTS: HighlightsApi = {
score: 0.35,
priority: 'P4',
source: 'errors',
+ product: 'error_tracking',
},
],
}
diff --git a/frontend/src/scenes/project-homepage/today/todayRowIcons.tsx b/frontend/src/scenes/project-homepage/today/todayRowIcons.tsx
index 65e01edabdf5..82250fed3949 100644
--- a/frontend/src/scenes/project-homepage/today/todayRowIcons.tsx
+++ b/frontend/src/scenes/project-homepage/today/todayRowIcons.tsx
@@ -27,19 +27,23 @@ const ANALYTICS: TodayRowIcon = {
glyph: <IconTrends />,
}
-const WORKFLOWS: TodayRowIcon = { color: 'var(--color-product-workflows-light)', glyph: <IconDecisionTree /> }
+const REPLAY: TodayRowIcon = { color: 'var(--color-product-session-replay-light)', glyph: <IconRewindPlay /> }
-const HIGHLIGHT_ICONS: Record<string, TodayRowIcon> = {
+const PRODUCT_ICONS: Record<string, TodayRowIcon> = {
alerts: { color: 'var(--color-product-alerts-light)', glyph: <IconBell /> },
- errors: { color: 'var(--color-product-error-tracking-light)', glyph: <IconWarning /> },
+ conversations: { color: 'var(--color-product-support-light)', glyph: <IconSupport /> },
+ error_tracking: { color: 'var(--color-product-error-tracking-light)', glyph: <IconWarning /> },
experiments: { color: 'var(--color-product-experiments-light)', glyph: <IconFlask /> },
- flags: { color: 'var(--color-product-feature-flags-light)', glyph: <IconToggle /> },
- rage: { color: 'var(--color-product-session-replay-light)', glyph: <IconRewindPlay /> },
+ feature_flags: { color: 'var(--color-product-feature-flags-light)', glyph: <IconToggle /> },
+ replay: REPLAY,
surveys: { color: 'var(--color-product-surveys-light)', glyph: <IconMessage /> },
- ticket_sla: { color: 'var(--color-product-support-light)', glyph: <IconSupport /> },
- warehouse_syncs: { color: 'var(--color-product-data-warehouse-light)', glyph: <IconDatabase /> },
- workflow_ideas: WORKFLOWS,
- workflows: WORKFLOWS,
+ warehouse_sources: { color: 'var(--color-product-data-warehouse-light)', glyph: <IconDatabase /> },
+ workflows: { color: 'var(--color-product-workflows-light)', glyph: <IconDecisionTree /> },
+}
+
+// Rage clicks come from web analytics, but the row opens the recordings.
+const SOURCE_ICONS: Record<string, TodayRowIcon> = {
+ rage: REPLAY,
}
function sourceIcon(source: string | null | undefined): TodayRowIcon {
@@ -52,6 +56,6 @@ export function reportIcon(report: Pick<SignalReport, 'source_products'>): Today
return sourceIcon(report.source_products?.[0])
}
-export function highlightIcon(item: Pick<HighlightItemApi, 'source'>): TodayRowIcon {
- return HIGHLIGHT_ICONS[item.source] ?? ANALYTICS
+export function highlightIcon(item: Pick<HighlightItemApi, 'source' | 'product'>): TodayRowIcon {
+ return SOURCE_ICONS[item.source] ?? (item.product ? PRODUCT_ICONS[item.product] : undefined) ?? ANALYTICS
}
diff --git a/products/alerts/backend/facade/today_highlights.py b/products/alerts/backend/facade/today_highlights.py
new file mode 100644
index 000000000000..aec7a59c9bb4
--- /dev/null
+++ b/products/alerts/backend/facade/today_highlights.py
@@ -0,0 +1,7 @@
+"""Alerts' sources for the "For you today" list. Today finds this module by name."""
+
+from products.today.backend.facade.contracts import HighlightSource
+
+from ..today_highlights import find_firing_alerts
+
+HIGHLIGHT_SOURCES = (HighlightSource(name="alerts", find=find_firing_alerts, scopes=("alert:read",)),)
diff --git a/products/today/backend/tests/test_highlight_alerts.py b/products/alerts/backend/tests/test_alert_today_highlights.py
similarity index 70%
rename from products/today/backend/tests/test_highlight_alerts.py
rename to products/alerts/backend/tests/test_alert_today_highlights.py
index 354d7056ca7a..297a46d5d8dd 100644
--- a/products/today/backend/tests/test_highlight_alerts.py
+++ b/products/alerts/backend/tests/test_alert_today_highlights.py
@@ -6,10 +6,10 @@ from unittest.mock import MagicMock, patch
from parameterized import parameterized
+from products.alerts.backend import today_highlights
from products.alerts.backend.facade.contracts import FiringAlert
-from products.today.backend.logic.highlight_registry import load_sources
-from products.today.backend.logic.highlight_sources import alerts
-from products.today.backend.logic.highlight_types import Context
+from products.alerts.backend.facade.today_highlights import HIGHLIGHT_SOURCES
+from products.today.backend.facade.testing import highlight_context
class TestAlerts(BaseTest):
@@ -30,10 +30,10 @@ class TestAlerts(BaseTest):
self, _name: str, alert_name: str, insight_name: str | None, title: str, detail: str
) -> None:
alert = FiringAlert(id=uuid.uuid4(), name=alert_name, insight_name=insight_name, insight_short_id="abc123")
- registered = next(s for s in load_sources() if s.name == "alerts")
+ registered = next(s for s in HIGHLIGHT_SOURCES if s.name == "alerts")
- with patch.object(alerts, "list_firing_alerts_created_by", return_value=[alert]):
- found = registered.find(Context(self.team, self.user, date(2026, 10, 13)))
+ with patch.object(today_highlights, "list_firing_alerts_created_by", return_value=[alert]):
+ found = registered.find(highlight_context(team=self.team, user=self.user, today=date(2026, 10, 13)))
self.assertEqual(
[(c.key, c.title, c.detail, c.url) for c in found.items],
@@ -51,9 +51,9 @@ class TestAlerts(BaseTest):
self, _name: str, scopes: frozenset[str] | None, include: bool
) -> None:
listed = MagicMock(return_value=[])
- registered = next(s for s in load_sources() if s.name == "alerts")
+ registered = next(s for s in HIGHLIGHT_SOURCES if s.name == "alerts")
- with patch.object(alerts, "list_firing_alerts_created_by", listed):
- registered.find(Context(self.team, self.user, date(2026, 10, 13), scopes))
+ with patch.object(today_highlights, "list_firing_alerts_created_by", listed):
+ registered.find(highlight_context(team=self.team, user=self.user, today=date(2026, 10, 13), scopes=scopes))
self.assertEqual(listed.call_args.kwargs["include_metrics_insights"], include)
diff --git a/products/today/backend/logic/highlight_sources/alerts.py b/products/alerts/backend/today_highlights.py
similarity index 65%
rename from products/today/backend/logic/highlight_sources/alerts.py
rename to products/alerts/backend/today_highlights.py
index 0ac4d9952510..bb325b3a6e08 100644
--- a/products/today/backend/logic/highlight_sources/alerts.py
+++ b/products/alerts/backend/today_highlights.py
@@ -2,26 +2,18 @@ import re
from products.alerts.backend.facade.api import list_firing_alerts_created_by
from products.alerts.backend.facade.contracts import FiringAlert
-
-from ...facade.enums import HighlightLabel
-from ..highlight_rules import short
-from ..highlight_types import Candidate, Context, Found, Source
+from products.today.backend.facade.contracts import HighlightCandidate, HighlightContext, HighlightFindings
+from products.today.backend.facade.enums import HighlightLabel
+from products.today.backend.facade.highlight_helpers import short
ALERT_FIRING = "Alert ‘{alert}’ is firing"
UNNAMED_ALERT_FIRING = "An alert is firing"
ALERT_FIRING_DETAIL = "Insight ‘{insight}’"
-def find(context: Context) -> Found:
- alerts = list_firing_alerts_created_by(
- context.team, context.user, include_metrics_insights=context.allows("metrics:read"), limit=10
- )
- return Found(items=tuple(_candidate(alert) for alert in alerts))
-
-
-def _candidate(alert: FiringAlert) -> Candidate:
+def _candidate(alert: FiringAlert) -> HighlightCandidate:
name = re.sub(r"(?i)\s+alert$", "", short(alert.name))
- return Candidate(
+ return HighlightCandidate(
key=f"alert:{alert.id}",
label=HighlightLabel.RISK,
family="alerts",
@@ -34,4 +26,8 @@ def _candidate(alert: FiringAlert) -> Candidate:
)
-SOURCE = Source(name="alerts", find=find, scopes=("alert:read",))
+def find_firing_alerts(context: HighlightContext) -> HighlightFindings:
+ alerts = list_firing_alerts_created_by(
+ context.team, context.user, include_metrics_insights=context.allows("metrics:read"), limit=10
+ )
+ return HighlightFindings(items=tuple(_candidate(alert) for alert in alerts))
diff --git a/products/conversations/backend/facade/api.py b/products/conversations/backend/facade/api.py
index b63e1b47e2e3..e27e96977511 100644
--- a/products/conversations/backend/facade/api.py
+++ b/products/conversations/backend/facade/api.py
@@ -30,7 +30,6 @@ from posthog.models.team import Team
from posthog.slack.identity import resolve_slack_profile_by_email
from posthog.temporal.common.client import sync_connect
-from products.conversations.backend import role_sla
from products.conversations.backend.channel_summary_ids import build_channel_summary_workflow_id
from products.conversations.backend.facade.types import (
AccountEmailThreadMessage as AccountEmailThreadMessage,
@@ -43,7 +42,6 @@ from products.conversations.backend.facade.types import (
EmailThreadParticipantSummary as EmailThreadParticipantSummary,
PublicHumanReplies as PublicHumanReplies,
ResolvedTicketRevision as ResolvedTicketRevision,
- RoleSlaBreach as RoleSlaBreach,
SupportChannel as SupportChannel,
SupportSlackSender as SupportSlackSender,
SupportTicketMessage as SupportTicketMessage,
@@ -1103,12 +1101,6 @@ def _email_thread_addresses(value: object) -> list[EmailThreadAddress]:
return addresses
-def list_role_sla_breaches(
- team_id: int, user_id: int, *, due_after: datetime, due_before: datetime
-) -> list[RoleSlaBreach]:
- return role_sla.list_role_sla_breaches(team_id, user_id, due_after=due_after, due_before=due_before)
-
-
def list_account_email_thread_messages(
team_id: int,
account_id: str,
diff --git a/products/conversations/backend/facade/today_highlights.py b/products/conversations/backend/facade/today_highlights.py
new file mode 100644
index 000000000000..b78053892e9f
--- /dev/null
+++ b/products/conversations/backend/facade/today_highlights.py
@@ -0,0 +1,7 @@
+"""Conversations' sources for the "For you today" list. Today finds this module by name."""
+
+from products.today.backend.facade.contracts import HighlightSource
+
+from ..today_highlights import find_ticket_sla
+
+HIGHLIGHT_SOURCES = (HighlightSource(name="ticket_sla", find=find_ticket_sla, scopes=("ticket:read",)),)
diff --git a/products/conversations/backend/tests/test_role_sla.py b/products/conversations/backend/tests/test_role_sla.py
index ace2b1444011..7bdcd36cdb71 100644
--- a/products/conversations/backend/tests/test_role_sla.py
+++ b/products/conversations/backend/tests/test_role_sla.py
@@ -6,9 +6,9 @@ from posthog.models import Organization, Team, User
from products.access_control.backend.models.access_control import AccessControl
from products.access_control.backend.models.role import Role, RoleMembership
-from products.conversations.backend.facade.api import list_role_sla_breaches
from products.conversations.backend.models import Status, Ticket, TicketAssignment
from products.conversations.backend.models.constants import Channel
+from products.conversations.backend.role_sla import list_role_sla_breaches
NOW = datetime(2026, 10, 15, 12, 0, tzinfo=UTC)
DUE_BEFORE = NOW + timedelta(hours=24)
diff --git a/products/today/backend/tests/test_highlight_ticket_sla.py b/products/conversations/backend/tests/test_today_highlights.py
similarity index 77%
rename from products/today/backend/tests/test_highlight_ticket_sla.py
rename to products/conversations/backend/tests/test_today_highlights.py
index 2f58c7d3b92b..fa9b02531da6 100644
--- a/products/today/backend/tests/test_highlight_ticket_sla.py
+++ b/products/conversations/backend/tests/test_today_highlights.py
@@ -9,11 +9,11 @@ from parameterized import parameterized
from posthog.models import Team, User
+from products.conversations.backend import today_highlights
+from products.conversations.backend.facade.today_highlights import HIGHLIGHT_SOURCES
from products.conversations.backend.facade.types import RoleSlaBreach
from products.today.backend.facade.enums import HighlightLabel
-from products.today.backend.logic.highlight_registry import load_sources
-from products.today.backend.logic.highlight_sources import ticket_sla
-from products.today.backend.logic.highlight_types import Context
+from products.today.backend.facade.testing import highlight_context
ROLE_ID = UUID("11111111-1111-1111-1111-111111111111")
@@ -45,11 +45,10 @@ class TestTicketSlaHighlight(SimpleTestCase):
soonest_ticket_number=12,
soonest_due_at=datetime(2026, 10, 15, 14, 0, tzinfo=UTC),
)
- registered = next(source for source in load_sources() if source.name == "ticket_sla")
- with patch("products.today.backend.logic.highlight_types.property_restrictions", return_value="0"):
- context = Context(Team(id=1), User(id=2), date(2026, 10, 15))
+ registered = next(source for source in HIGHLIGHT_SOURCES if source.name == "ticket_sla")
+ context = highlight_context(team=Team(id=1), user=User(id=2), today=date(2026, 10, 15))
- with patch.object(ticket_sla, "list_role_sla_breaches", return_value=[breach]):
+ with patch.object(today_highlights, "list_role_sla_breaches", return_value=[breach]):
found = registered.find(context)
assert len(found.items) == 1
diff --git a/products/today/backend/logic/highlight_sources/ticket_sla.py b/products/conversations/backend/today_highlights.py
similarity index 75%
rename from products/today/backend/logic/highlight_sources/ticket_sla.py
rename to products/conversations/backend/today_highlights.py
index 55562f5b171b..3f0f351f54ee 100644
--- a/products/today/backend/logic/highlight_sources/ticket_sla.py
+++ b/products/conversations/backend/today_highlights.py
@@ -2,11 +2,10 @@ from datetime import timedelta
from django.utils import timezone
-from products.conversations.backend.facade.api import list_role_sla_breaches
from products.conversations.backend.facade.types import RoleSlaBreach
-
-from ...facade.enums import HighlightLabel
-from ..highlight_types import Candidate, Context, Found, Source
+from products.conversations.backend.role_sla import list_role_sla_breaches
+from products.today.backend.facade.contracts import HighlightCandidate, HighlightContext, HighlightFindings
+from products.today.backend.facade.enums import HighlightLabel
WINDOW = timedelta(hours=24)
# Relevance is 1 because the ticket is assigned to the viewer's role, so the score
@@ -20,18 +19,12 @@ MANY_DETAIL = "Ticket #{number} is the soonest."
OPEN_STATUSES = ("new", "open", "pending", "on_hold")
-def find(context: Context) -> Found:
- now = timezone.now()
- breaches = list_role_sla_breaches(context.team.id, context.user.id, due_after=now, due_before=now + WINDOW)
- return Found(items=tuple(_candidate(breach) for breach in breaches))
-
-
-def _candidate(breach: RoleSlaBreach) -> Candidate:
+def _candidate(breach: RoleSlaBreach) -> HighlightCandidate:
number = breach.soonest_ticket_number
role = breach.role_name
one = breach.ticket_count == 1
statuses = "&".join(f"status={status}" for status in OPEN_STATUSES)
- return Candidate(
+ return HighlightCandidate(
key=f"ticket_sla:{breach.role_id}",
label=HighlightLabel.RISK,
family="support",
@@ -48,4 +41,7 @@ def _candidate(breach: RoleSlaBreach) -> Candidate:
)
-SOURCE = Source(name="ticket_sla", find=find, scopes=("ticket:read",))
+def find_ticket_sla(context: HighlightContext) -> HighlightFindings:
+ now = timezone.now()
+ breaches = list_role_sla_breaches(context.team.id, context.user.id, due_after=now, due_before=now + WINDOW)
+ return HighlightFindings(items=tuple(_candidate(breach) for breach in breaches))
diff --git a/products/data_catalog/backend/facade/today_highlights.py b/products/data_catalog/backend/facade/today_highlights.py
new file mode 100644
index 000000000000..f3f6bef83a06
--- /dev/null
+++ b/products/data_catalog/backend/facade/today_highlights.py
@@ -0,0 +1,13 @@
+"""Data catalog's sources for the "For you today" list. Today finds this module by name."""
+
+from products.today.backend.facade.contracts import HighlightSource
+
+from ..today_highlights import find_pending_approvals
+
+HIGHLIGHT_SOURCES = (
+ HighlightSource(
+ name="data_catalog_approvals",
+ find=find_pending_approvals,
+ scopes=("data_catalog:read", "data_catalog_approval:write"),
+ ),
+)
diff --git a/products/today/backend/tests/test_highlight_data_catalog_approvals.py b/products/data_catalog/backend/tests/test_today_highlights.py
similarity index 69%
rename from products/today/backend/tests/test_highlight_data_catalog_approvals.py
rename to products/data_catalog/backend/tests/test_today_highlights.py
index 3f695b6d2e95..cb1019a45ca7 100644
--- a/products/today/backend/tests/test_highlight_data_catalog_approvals.py
+++ b/products/data_catalog/backend/tests/test_today_highlights.py
@@ -1,3 +1,4 @@
+from collections.abc import Callable
from types import SimpleNamespace
from typing import cast
@@ -7,11 +8,11 @@ from django.test import SimpleTestCase
from parameterized import parameterized
+from products.data_catalog.backend import today_highlights
from products.data_catalog.backend.facade.api import PendingGroup, PendingKind, TeamPendingReview
+from products.data_catalog.backend.facade.today_highlights import HIGHLIGHT_SOURCES
+from products.today.backend.facade.contracts import HighlightContext, HighlightFindings
from products.today.backend.facade.enums import HighlightLabel
-from products.today.backend.logic.highlight_registry import load_sources
-from products.today.backend.logic.highlight_sources import data_catalog_approvals
-from products.today.backend.logic.highlight_types import Context
METRICS = PendingGroup(kind=PendingKind.METRICS, noun="metric", count=3, sample_names=[])
RELATIONSHIPS = PendingGroup(kind=PendingKind.RELATIONSHIPS, noun="relationship", count=2, sample_names=[])
@@ -43,10 +44,10 @@ class TestDataCatalogApprovalsHighlight(SimpleTestCase):
review = TeamPendingReview(
team_id=1, team_name="Team", groups=groups, total=sum(group.count for group in groups)
)
- registered = next(source for source in load_sources() if source.name == "data_catalog_approvals")
+ registered = next(source for source in HIGHLIGHT_SOURCES if source.name == "data_catalog_approvals")
- with patch.object(data_catalog_approvals, "build_team_pending_review", return_value=review):
- found = registered.find(self._context(can_approve=True))
+ with patch.object(today_highlights, "build_team_pending_review", return_value=review):
+ found = self._find(registered.find, can_approve=True)
assert len(found.items) == 1
item = found.items[0]
@@ -58,14 +59,16 @@ class TestDataCatalogApprovalsHighlight(SimpleTestCase):
def test_a_user_who_cannot_approve_gets_no_item(self) -> None:
review = TeamPendingReview(team_id=1, team_name="Team", groups=[METRICS], total=3)
- with patch.object(data_catalog_approvals, "build_team_pending_review", return_value=review):
- found = data_catalog_approvals.find(self._context(can_approve=False))
+ with patch.object(today_highlights, "build_team_pending_review", return_value=review):
+ found = self._find(today_highlights.find_pending_approvals, can_approve=False)
assert found.items == ()
- def _context(self, *, can_approve: bool) -> Context:
+ def _find(self, find: Callable[[HighlightContext], HighlightFindings], *, can_approve: bool) -> HighlightFindings:
access = MagicMock()
access.check_access_level_for_resource.side_effect = lambda resource, level: (
can_approve and (resource, level) == ("data_catalog", "editor")
)
- return cast(Context, SimpleNamespace(team=SimpleNamespace(id=1), access=access))
+ context = cast(HighlightContext, SimpleNamespace(team=SimpleNamespace(id=1), user=SimpleNamespace(id=2)))
+ with patch.object(today_highlights, "UserAccessControl", return_value=access):
+ return find(context)
diff --git a/products/today/backend/logic/highlight_sources/data_catalog_approvals.py b/products/data_catalog/backend/today_highlights.py
similarity index 67%
rename from products/today/backend/logic/highlight_sources/data_catalog_approvals.py
rename to products/data_catalog/backend/today_highlights.py
index 82889c7ac519..52eb73f5520d 100644
--- a/products/today/backend/logic/highlight_sources/data_catalog_approvals.py
+++ b/products/data_catalog/backend/today_highlights.py
@@ -1,8 +1,7 @@
-from products.access_control.backend.facade.user_access_control import AccessControlLevel
+from products.access_control.backend.facade.user_access_control import AccessControlLevel, UserAccessControl
from products.data_catalog.backend.facade.api import PendingGroup, build_team_pending_review
-
-from ...facade.enums import HighlightLabel
-from ..highlight_types import Candidate, Context, Found, Source
+from products.today.backend.facade.contracts import HighlightCandidate, HighlightContext, HighlightFindings
+from products.today.backend.facade.enums import HighlightLabel
APPROVER_ACCESS_LEVEL: AccessControlLevel = "editor"
IMPORTANCE = 0.5
@@ -13,16 +12,22 @@ ONE_DETAIL = "Review it in the data catalog."
MANY_DETAIL = "Review them in the data catalog."
-def find(context: Context) -> Found:
- if not context.access.check_access_level_for_resource("data_catalog", APPROVER_ACCESS_LEVEL):
- return Found()
+def _join(groups: list[PendingGroup]) -> str:
+ counts = [f"{group.count} {group.noun}{'' if group.count == 1 else 's'}" for group in groups]
+ return counts[0] if len(counts) == 1 else f"{', '.join(counts[:-1])} and {counts[-1]}"
+
+
+def find_pending_approvals(context: HighlightContext) -> HighlightFindings:
+ access = UserAccessControl(user=context.user, team=context.team)
+ if not access.check_access_level_for_resource("data_catalog", APPROVER_ACCESS_LEVEL):
+ return HighlightFindings()
review = build_team_pending_review(context.team, sample_size=0)
if review is None:
- return Found()
+ return HighlightFindings()
one = review.total == 1
- return Found(
+ return HighlightFindings(
items=(
- Candidate(
+ HighlightCandidate(
key="data_catalog_approvals",
label=HighlightLabel.OPPORTUNITY,
family="data_catalog",
@@ -34,15 +39,3 @@ def find(context: Context) -> Found:
),
)
)
-
-
-def _join(groups: list[PendingGroup]) -> str:
- counts = [f"{group.count} {group.noun}{'' if group.count == 1 else 's'}" for group in groups]
- return counts[0] if len(counts) == 1 else f"{', '.join(counts[:-1])} and {counts[-1]}"
-
-
-SOURCE = Source(
- name="data_catalog_approvals",
- find=find,
- scopes=("data_catalog:read", "data_catalog_approval:write"),
-)
diff --git a/products/experiments/backend/facade/today_highlights.py b/products/experiments/backend/facade/today_highlights.py
new file mode 100644
index 000000000000..68b559577ba5
--- /dev/null
+++ b/products/experiments/backend/facade/today_highlights.py
@@ -0,0 +1,7 @@
+"""Experiments' sources for the "For you today" list. Today finds this module by name."""
+
+from products.today.backend.facade.contracts import HighlightSource
+
+from ..today_highlights import find_experiment_highlights
+
+HIGHLIGHT_SOURCES = (HighlightSource(name="experiments", find=find_experiment_highlights, scopes=("experiment:read",)),)
diff --git a/products/today/backend/tests/test_highlight_experiments.py b/products/experiments/backend/test/test_today_highlights.py
similarity index 70%
rename from products/today/backend/tests/test_highlight_experiments.py
rename to products/experiments/backend/test/test_today_highlights.py
index 6cdb615791e1..138e709cddc2 100644
--- a/products/today/backend/tests/test_highlight_experiments.py
+++ b/products/experiments/backend/test/test_today_highlights.py
@@ -6,10 +6,11 @@ from unittest.mock import MagicMock, patch
from parameterized import parameterized
+from products.experiments.backend import today_highlights
from products.experiments.backend.facade.contracts import EndedExperiment, RunningExperiment
-from products.today.backend.logic.highlight_registry import load_sources
-from products.today.backend.logic.highlight_sources import experiments
-from products.today.backend.logic.highlight_types import Context, Found
+from products.experiments.backend.facade.today_highlights import HIGHLIGHT_SOURCES
+from products.today.backend.facade.contracts import HighlightFindings
+from products.today.backend.facade.testing import highlight_context
MONDAY = date(2026, 10, 12)
TUESDAY = date(2026, 10, 13)
@@ -22,18 +23,18 @@ RUNNING = RunningExperiment(
@time_machine.travel(NOW, tick=False)
class TestExperiments(BaseTest):
- def _find(self, today: date, running: MagicMock, enrolled: MagicMock) -> tuple[Found, Context]:
- registered = next(s for s in load_sources() if s.name == "experiments")
- context = Context(self.team, self.user, today)
+ def _find(self, today: date, running: MagicMock, enrolled: MagicMock) -> HighlightFindings:
+ registered = next(s for s in HIGHLIGHT_SOURCES if s.name == "experiments")
+ context = highlight_context(team=self.team, user=self.user, today=today)
with (
- patch.object(experiments, "list_ended_experiments_without_conclusion", return_value=[ENDED]),
- patch.object(experiments, "list_running_experiments", running),
- patch.object(experiments, "count_enrolled_people", enrolled),
+ patch.object(today_highlights, "list_ended_experiments_without_conclusion", return_value=[ENDED]),
+ patch.object(today_highlights, "list_running_experiments", running),
+ patch.object(today_highlights, "count_enrolled_people", enrolled),
):
- return registered.find(context), context
+ return registered.find(context)
def test_an_ended_experiment_without_a_decision_is_an_opportunity(self) -> None:
- found, _ = self._find(TUESDAY, MagicMock(return_value=[]), MagicMock(return_value={}))
+ found = self._find(TUESDAY, MagicMock(return_value=[]), MagicMock(return_value={}))
self.assertEqual(
[(c.title, c.detail, c.url) for c in found.items],
@@ -70,17 +71,13 @@ class TestExperiments(BaseTest):
def test_a_long_running_experiment_with_few_users_is_a_risk(
self, _name: str, enrolled: int, title: str | None
) -> None:
- found, _ = self._find(
+ found = self._find(
TUESDAY, MagicMock(return_value=[RUNNING]), MagicMock(return_value={"onboarding-tips": enrolled})
)
self.assertEqual([c.title for c in found.items][1:], [title] if title else [])
def test_a_failed_count_keeps_the_ended_reminders(self) -> None:
- found, context = self._find(
- TUESDAY, MagicMock(return_value=[RUNNING]), MagicMock(side_effect=TimeoutError("slow"))
- )
+ found = self._find(TUESDAY, MagicMock(return_value=[RUNNING]), MagicMock(side_effect=TimeoutError("slow")))
- self.assertEqual(
- ([c.key for c in found.items], context.failures), (["experiment_ended:7"], ["experiments_enrolled"])
- )
+ self.assertEqual([c.key for c in found.items], ["experiment_ended:7"])
diff --git a/products/today/backend/logic/highlight_sources/experiments.py b/products/experiments/backend/today_highlights.py
similarity index 83%
rename from products/today/backend/logic/highlight_sources/experiments.py
rename to products/experiments/backend/today_highlights.py
index e343b01e6798..5f35b6d6b710 100644
--- a/products/today/backend/logic/highlight_sources/experiments.py
+++ b/products/experiments/backend/today_highlights.py
@@ -9,10 +9,9 @@ from products.experiments.backend.facade.api import (
list_running_experiments,
)
from products.experiments.backend.facade.contracts import EndedExperiment, RunningExperiment
-
-from ...facade.enums import HighlightLabel
-from ..highlight_rules import short, users
-from ..highlight_types import Candidate, Context, Found, Source
+from products.today.backend.facade.contracts import HighlightCandidate, HighlightContext, HighlightFindings
+from products.today.backend.facade.enums import HighlightLabel
+from products.today.backend.facade.highlight_helpers import short, users
ENDED = "Experiment ‘{experiment}’ ended {when}"
ENDED_DETAIL = "Read the results and decide whether to release the change"
@@ -25,35 +24,7 @@ JUST_CROSSED_DAYS = 67
MIN_PEOPLE = 100
-def find(context: Context) -> Found:
- now = timezone.now()
- ended = list_ended_experiments_without_conclusion(
- team_id=context.team.id, user_id=context.user.id, since=now - timedelta(days=ENDED_WINDOW_DAYS), limit=20
- )
- running = list_running_experiments(
- team_id=context.team.id,
- user_id=context.user.id,
- started_after=None if context.today.weekday() == 0 else now - timedelta(days=JUST_CROSSED_DAYS),
- started_before=now - timedelta(days=LONG_RUNNING_DAYS),
- limit=100,
- )
- enrolled = context.guard(
- "experiments_enrolled",
- lambda: count_enrolled_people(
- team=context.team, user=context.user, flag_keys=[experiment.flag_key for experiment in running]
- ),
- None,
- )
- counted = [] if enrolled is None else [(experiment, enrolled.get(experiment.flag_key, 0)) for experiment in running]
- return Found(
- items=(
- *(_ended(context, experiment) for experiment in ended),
- *(_few_users(experiment, people) for experiment, people in counted if people < MIN_PEOPLE),
- )
- )
-
-
-def _days_since(context: Context, moment: datetime) -> int:
+def _days_since(context: HighlightContext, moment: datetime) -> int:
return (context.today - timezone.localtime(moment, context.team.timezone_info).date()).days
@@ -65,8 +36,8 @@ def _name(name: str, limit: int) -> str:
return short(re.sub(r"(?i)\s+experiment$", "", name) or name, limit)
-def _ended(context: Context, experiment: EndedExperiment) -> Candidate:
- return Candidate(
+def _ended(context: HighlightContext, experiment: EndedExperiment) -> HighlightCandidate:
+ return HighlightCandidate(
key=f"experiment_ended:{experiment.id}",
label=HighlightLabel.OPPORTUNITY,
family="experiments",
@@ -80,8 +51,8 @@ def _ended(context: Context, experiment: EndedExperiment) -> Candidate:
)
-def _few_users(experiment: RunningExperiment, enrolled: int) -> Candidate:
- return Candidate(
+def _few_users(experiment: RunningExperiment, enrolled: int) -> HighlightCandidate:
+ return HighlightCandidate(
key=f"experiment_stale:{experiment.id}",
label=HighlightLabel.RISK,
family="experiments",
@@ -95,4 +66,29 @@ def _few_users(experiment: RunningExperiment, enrolled: int) -> Candidate:
)
-SOURCE = Source(name="experiments", find=find, scopes=("experiment:read",))
+def find_experiment_highlights(context: HighlightContext) -> HighlightFindings:
+ now = timezone.now()
+ ended = list_ended_experiments_without_conclusion(
+ team_id=context.team.id, user_id=context.user.id, since=now - timedelta(days=ENDED_WINDOW_DAYS), limit=20
+ )
+ running = list_running_experiments(
+ team_id=context.team.id,
+ user_id=context.user.id,
+ started_after=None if context.today.weekday() == 0 else now - timedelta(days=JUST_CROSSED_DAYS),
+ started_before=now - timedelta(days=LONG_RUNNING_DAYS),
+ limit=100,
+ )
+ enrolled = context.guard(
+ "experiments_enrolled",
+ lambda: count_enrolled_people(
+ team=context.team, user=context.user, flag_keys=[experiment.flag_key for experiment in running]
+ ),
+ None,
+ )
+ counted = [] if enrolled is None else [(experiment, enrolled.get(experiment.flag_key, 0)) for experiment in running]
+ return HighlightFindings(
+ items=(
+ *(_ended(context, experiment) for experiment in ended),
+ *(_few_users(experiment, people) for experiment, people in counted if people < MIN_PEOPLE),
+ )
+ )
diff --git a/products/feature_flags/backend/facade/today_highlights.py b/products/feature_flags/backend/facade/today_highlights.py
new file mode 100644
index 000000000000..7bdbac970b3e
--- /dev/null
+++ b/products/feature_flags/backend/facade/today_highlights.py
@@ -0,0 +1,7 @@
+"""Feature flags' sources for the "For you today" list. Today finds this module by name."""
+
+from products.today.backend.facade.contracts import HighlightSource
+
+from ..today_highlights import find_flag_highlights
+
+HIGHLIGHT_SOURCES = (HighlightSource(name="flags", find=find_flag_highlights, scopes=("feature_flag:read",)),)
diff --git a/products/today/backend/tests/test_highlight_flags.py b/products/feature_flags/backend/test/test_today_highlights.py
similarity index 91%
rename from products/today/backend/tests/test_highlight_flags.py
rename to products/feature_flags/backend/test/test_today_highlights.py
index b466d2476900..c997ac850fca 100644
--- a/products/today/backend/tests/test_highlight_flags.py
+++ b/products/feature_flags/backend/test/test_today_highlights.py
@@ -9,10 +9,10 @@ from django.test import SimpleTestCase
from parameterized import parameterized
+from products.feature_flags.backend import today_highlights
+from products.feature_flags.backend.facade.today_highlights import HIGHLIGHT_SOURCES
from products.feature_flags.backend.facade.usage import CreatedFlag, FlagCalls, FlagCallSummary
-from products.today.backend.logic.highlight_registry import load_sources
-from products.today.backend.logic.highlight_sources import flags
-from products.today.backend.logic.highlight_types import Context
+from products.today.backend.facade.contracts import HighlightContext
MONDAY = date(2026, 10, 12)
TUESDAY = date(2026, 10, 13)
@@ -55,7 +55,7 @@ class TestFlags(SimpleTestCase):
covers_all_environments: bool = True,
) -> list[tuple[str, str, str | None]]:
context = cast(
- Context,
+ HighlightContext,
SimpleNamespace(
team=SimpleNamespace(id=1, timezone_info=ZoneInfo("UTC")),
user=SimpleNamespace(id=2),
@@ -63,11 +63,11 @@ class TestFlags(SimpleTestCase):
daily=lambda _name, compute: compute(),
),
)
- registered = next(s for s in load_sources() if s.name == "flags")
+ registered = next(s for s in HIGHLIGHT_SOURCES if s.name == "flags")
summary = FlagCallSummary(by_key=by_key, complete=complete, covers_all_environments=covers_all_environments)
with (
- patch.object(flags, "list_flags_created_by", return_value=created_flags),
- patch.object(flags, "summarize_flag_calls", return_value=summary),
+ patch.object(today_highlights, "list_flags_created_by", return_value=created_flags),
+ patch.object(today_highlights, "summarize_flag_calls", return_value=summary),
):
return [(c.title, c.detail, c.url) for c in registered.find(context).items]
diff --git a/products/today/backend/logic/highlight_sources/flags.py b/products/feature_flags/backend/today_highlights.py
similarity index 85%
rename from products/today/backend/logic/highlight_sources/flags.py
rename to products/feature_flags/backend/today_highlights.py
index 6b269b42c9a2..4eea8ad714c9 100644
--- a/products/today/backend/logic/highlight_sources/flags.py
+++ b/products/feature_flags/backend/today_highlights.py
@@ -11,10 +11,9 @@ from products.feature_flags.backend.facade.usage import (
list_flags_created_by,
summarize_flag_calls,
)
-
-from ...facade.enums import HighlightLabel
-from ..highlight_rules import exact, human
-from ..highlight_types import Candidate, Context, Found, Source
+from products.today.backend.facade.contracts import HighlightCandidate, HighlightContext, HighlightFindings
+from products.today.backend.facade.enums import HighlightLabel
+from products.today.backend.facade.highlight_helpers import exact, human
REACH_DROP = "Flag ‘{flag}’ reached {pct}% fewer users in the last 7 days"
REACH_DROP_DETAIL = "{before} → {now} · Check the code that calls it"
@@ -37,37 +36,8 @@ NO_CALLS = FlagCalls(
)
-def find(context: Context) -> Found:
- flags = [
- flag
- for flag in list_flags_created_by(context.team.id, context.user.id, limit=500)
- if not flag.remote_configuration and not flag.key.startswith(INTERNAL_FLAG_PREFIXES)
- ]
- if not flags:
- return Found()
- summary = context.daily("flag_calls", lambda: summarize_flag_calls(context.team, context.user))
- items: list[Candidate] = []
- removable: list[CreatedFlag] = []
- same: list[tuple[CreatedFlag, FlagCalls]] = []
- for flag in flags:
- calls = summary.by_key.get(flag.key, NO_CALLS)
- if calls.people_last_week >= MIN_REACH and calls.people_this_week <= calls.people_last_week / 2:
- items.append(_reach_drop(flag, calls))
- if flag.removal_blocked or RISKY_FLAGS.search(flag.key) or not summary.covers_all_environments:
- continue
- age = (context.today - timezone.localtime(flag.created_at, context.team.timezone_info).date()).days
- if age >= SAME_VALUE_MIN_AGE_DAYS and calls.people_this_week >= MIN_REACH and calls.values_this_week == 1:
- removable.append(flag)
- same.append((flag, calls))
- elif age >= FLAG_CALL_DAYS and calls.calls == 0 and summary.complete:
- removable.append(flag)
- if cleanup := _cleanup(context, removable, same):
- items.append(cleanup)
- return Found(items=tuple(items))
-
-
-def _reach_drop(flag: CreatedFlag, calls: FlagCalls) -> Candidate:
- return Candidate(
+def _reach_drop(flag: CreatedFlag, calls: FlagCalls) -> HighlightCandidate:
+ return HighlightCandidate(
key=f"flag_reach_drop:{flag.id}",
label=HighlightLabel.RISK,
family="flags",
@@ -87,8 +57,8 @@ def _listing(keys: list[str]) -> str:
def _cleanup(
- context: Context, removable: list[CreatedFlag], same: list[tuple[CreatedFlag, FlagCalls]]
-) -> Candidate | None:
+ context: HighlightContext, removable: list[CreatedFlag], same: list[tuple[CreatedFlag, FlagCalls]]
+) -> HighlightCandidate | None:
if context.today.weekday() == 0 and removable:
keys = [flag.key for flag in sorted(removable, key=lambda flag: flag.created_at)]
if len(keys) > 1:
@@ -104,7 +74,7 @@ def _cleanup(
return None
title = CLEANUP_COST.format(n=len(same), cost=human(cost))
detail = CLEANUP_COST_DETAIL.format(names=_listing([flag.key for flag, _ in same]))
- return Candidate(
+ return HighlightCandidate(
key="flag_cleanup",
label=HighlightLabel.OPPORTUNITY,
family="flag_cleanup",
@@ -116,4 +86,30 @@ def _cleanup(
)
-SOURCE = Source(name="flags", find=find, scopes=("feature_flag:read",))
+def find_flag_highlights(context: HighlightContext) -> HighlightFindings:
+ flags = [
+ flag
+ for flag in list_flags_created_by(context.team.id, context.user.id, limit=500)
+ if not flag.remote_configuration and not flag.key.startswith(INTERNAL_FLAG_PREFIXES)
+ ]
+ if not flags:
+ return HighlightFindings()
+ summary = context.daily("flag_calls", lambda: summarize_flag_calls(context.team, context.user))
+ items: list[HighlightCandidate] = []
+ removable: list[CreatedFlag] = []
+ same: list[tuple[CreatedFlag, FlagCalls]] = []
+ for flag in flags:
+ calls = summary.by_key.get(flag.key, NO_CALLS)
+ if calls.people_last_week >= MIN_REACH and calls.people_this_week <= calls.people_last_week / 2:
+ items.append(_reach_drop(flag, calls))
+ if flag.removal_blocked or RISKY_FLAGS.search(flag.key) or not summary.covers_all_environments:
+ continue
+ age = (context.today - timezone.localtime(flag.created_at, context.team.timezone_info).date()).days
+ if age >= SAME_VALUE_MIN_AGE_DAYS and calls.people_this_week >= MIN_REACH and calls.values_this_week == 1:
+ removable.append(flag)
+ same.append((flag, calls))
+ elif age >= FLAG_CALL_DAYS and calls.calls == 0 and summary.complete:
+ removable.append(flag)
+ if cleanup := _cleanup(context, removable, same):
+ items.append(cleanup)
+ return HighlightFindings(items=tuple(items))
diff --git a/products/today/AGENTS.md b/products/today/AGENTS.md
index 26939790f899..9b8201606f83 100644
--- a/products/today/AGENTS.md
+++ b/products/today/AGENTS.md
@@ -5,36 +5,18 @@
Today ranks facts that other products find and shows the best few.
The product that owns the data owns its source: the query, the thresholds, and the copy.
Today owns the contract, the ranking, and the shared helpers.
+Today also owns the pulse: the routine and key-metric tiles, pinned numbers, and the home dashboard source.
+These live in `backend/logic/today_highlights/` and Today declares them in `backend/facade/today_highlights.py`.
-**A new source lives in its own product, never in `products/today/`.**
+**A source that another team owns lives in that team's product, never in `products/today/`.**
+The how-to for a product team is the `adding-today-highlights` skill (`.agents/skills/adding-today-highlights/SKILL.md`), because a producer works in its own product and never loads this file.
-1. Put the rule in the product's internals, for example `products/<x>/backend/today_highlights.py`.
- It takes a `HighlightContext` and returns `HighlightFindings`.
-2. Declare it in `products/<x>/backend/facade/today_highlights.py`:
-
- ```python
- from products.today.backend.facade.contracts import HighlightSource
-
- from ..today_highlights import find_stale_things
-
- HIGHLIGHT_SOURCES = (HighlightSource(name="stale_things", find=find_stale_things, scopes=("thing:read",)),)
- ```
-
-3. Add `"products.today"` to the product's `depends_on` in `tach.toml`. Today gets no new dependency.
-4. Test the rule in the product, with `products.today.backend.facade.testing.highlight_context`.
-
-Today finds the declaration through `posthog.products.load_product_modules`, so a new source changes no file in Today.
+Today finds every declaration through `posthog.products.load_product_modules`, so a new source changes no backend file in Today.
The registry raises on a missing declaration, an unusable entry, or a source name that another product already uses.
+It also records the product that declares each source, and the row icon comes from that product (`PRODUCT_ICONS` in `frontend/src/scenes/project-homepage/today/todayRowIcons.tsx`).
-Import only from Today's facade:
-
-- `facade/contracts.py`: `HighlightCandidate`, `HighlightFindings`, `HighlightContext`, `HighlightSource`, `HighlightMetric`, `DailyValueNotReady`
-- `facade/enums.py`: `HighlightLabel`, `HighlightUnit`, `HighlightInterval`
-- `facade/highlight_helpers.py`: number and text formatting, `uses_product`, and trend detection
-
-`HighlightContext.daily()` caches one value per team, property restrictions and day, so every viewer with the same restrictions shares it.
-Never compute a per-viewer value there without the user id in its name.
+The facade (`contracts.py`, `enums.py`, `highlight_helpers.py`, `testing.py`) is a contract with every producing product.
+Change it only in a backward-compatible way: an added field gets a default, because Today validates stored results against these types.
-**Status:** `backend/logic/highlight_sources/` is deprecated.
-The sources in it still load, through legacy aliases in `logic/highlight_types.py`, until each one moves into its product.
-Do not add a file there and do not copy those files as an example.
+**Status:** every other team's source lives in its own product.
+`backend/logic/highlight_sources/` and its `SOURCE` lookup are gone, so a file there no longer loads.
diff --git a/products/today/backend/facade/contracts.py b/products/today/backend/facade/contracts.py
index e9f26052b63e..46cac6e6a5c0 100644
--- a/products/today/backend/facade/contracts.py
+++ b/products/today/backend/facade/contracts.py
@@ -205,6 +205,8 @@ class HighlightItem:
url: str | None
series: list[float] | None
score: float
+ # Results stored before this field existed have no product.
+ product: str | None = None
@dataclass(frozen=True)
@@ -304,7 +306,7 @@ class HighlightSource:
Today finds that module by name, so a new source changes no file in Today.
"""
- # Unique across products. Today keys stored results and the frontend icon by it.
+ # Unique across products and stable: Today keys stored results and analytics by it, so a rename breaks them.
name: str
find: Callable[[HighlightContext], HighlightFindings]
# Today skips the source when the viewer's API scopes or access controls do not cover these.
diff --git a/products/today/backend/facade/today_highlights.py b/products/today/backend/facade/today_highlights.py
new file mode 100644
index 000000000000..a7bc9cb41951
--- /dev/null
+++ b/products/today/backend/facade/today_highlights.py
@@ -0,0 +1,5 @@
+"""Today's own sources for the "For you today" list: the pulse and the home dashboard. Today finds this module by name."""
+
+from ..logic.today_highlights import home, key_metrics, routine
+
+HIGHLIGHT_SOURCES = (home.SOURCE, key_metrics.SOURCE, routine.SOURCE)
diff --git a/products/today/backend/logic/highlight_registry.py b/products/today/backend/logic/highlight_registry.py
index 8ae68c148339..de3976473d4c 100644
--- a/products/today/backend/logic/highlight_registry.py
+++ b/products/today/backend/logic/highlight_registry.py
@@ -1,13 +1,10 @@
-import pkgutil
-import importlib
-from collections.abc import Iterator
+from collections.abc import Mapping
from functools import cache
-from types import ModuleType
+from posthog.dataclasses import frozen
from posthog.products import load_product_modules
from ..facade.contracts import HighlightSource
-from . import highlight_sources
SOURCES_MODULE = "facade.today_highlights"
SOURCES_ATTRIBUTE = "HIGHLIGHT_SOURCES"
@@ -17,30 +14,28 @@ class HighlightRegistryError(Exception):
pass
-def _legacy_modules() -> Iterator[ModuleType]:
- for name in sorted(module.name for module in pkgutil.iter_modules(highlight_sources.__path__)):
- yield importlib.import_module(f"{highlight_sources.__name__}.{name}")
+@frozen
+class HighlightRegistry:
+ sources: tuple[HighlightSource, ...]
+ products: Mapping[str, str]
-def _declared(module: ModuleType) -> object:
- if module.__name__.startswith(f"{highlight_sources.__name__}."):
- source = getattr(module, "SOURCE", None)
- return None if source is None else (source,)
- return getattr(module, SOURCES_ATTRIBUTE, None)
+def _product(module_name: str) -> str:
+ # Product apps are named `products.<product>.backend`.
+ return module_name.split(".")[1]
@cache
-def load_sources() -> tuple[HighlightSource, ...]:
+def load_registry() -> HighlightRegistry:
"""Every source that a product declares in `backend/facade/today_highlights.py`, sorted by name.
- A product depends on Today's facade to declare a source, so Today needs no import of that product.
- Sources still in the legacy `highlight_sources/` package declare a module-level `SOURCE` and load too.
+ Today imports no product by name, so the dependency points from the product to Today's facade.
A broken declaration raises instead of dropping the source without a trace.
"""
sources: dict[str, HighlightSource] = {}
owners: dict[str, str] = {}
- for module in [*load_product_modules(SOURCES_MODULE), *_legacy_modules()]:
- declared = _declared(module)
+ for module in load_product_modules(SOURCES_MODULE):
+ declared = getattr(module, SOURCES_ATTRIBUTE, None)
if not isinstance(declared, tuple | list):
raise HighlightRegistryError(f"{module.__name__}.{SOURCES_ATTRIBUTE} must be a tuple of HighlightSource")
for source in declared:
@@ -54,4 +49,16 @@ def load_sources() -> tuple[HighlightSource, ...]:
)
sources[source.name] = source
owners[source.name] = module.__name__
- return tuple(sources[name] for name in sorted(sources))
+ return HighlightRegistry(
+ sources=tuple(sources[name] for name in sorted(sources)),
+ products={name: _product(module_name) for name, module_name in owners.items()},
+ )
+
+
+def load_sources() -> tuple[HighlightSource, ...]:
+ return load_registry().sources
+
+
+def source_product(name: str) -> str | None:
+ """None for a name that no product declares, such as a source removed after a result was stored."""
+ return load_registry().products.get(name)
diff --git a/products/today/backend/logic/highlight_sources/__init__.py b/products/today/backend/logic/highlight_sources/__init__.py
deleted file mode 100644
index 2135e1b95106..000000000000
--- a/products/today/backend/logic/highlight_sources/__init__.py
+++ /dev/null
@@ -1,5 +0,0 @@
-"""Deprecated: sources that still live inside Today.
-
-New sources belong in their own product: `HIGHLIGHT_SOURCES` in `products/<x>/backend/facade/today_highlights.py`.
-The modules here move out into their products, after which this package goes away.
-"""
diff --git a/products/today/backend/logic/highlight_types.py b/products/today/backend/logic/highlight_types.py
index ab2924f46dfe..06acfd95c1a9 100644
--- a/products/today/backend/logic/highlight_types.py
+++ b/products/today/backend/logic/highlight_types.py
@@ -29,7 +29,7 @@ from ..facade.contracts import (
HighlightSource,
)
-# Legacy names for the sources still in highlight_sources/. New sources use the facade contract.
+# Short names for Today's own sources in today_highlights/. Other products use the facade contract.
Candidate = HighlightCandidate
Found = HighlightFindings
@@ -113,10 +113,10 @@ class Context:
return default
-def Source( # noqa: N802 - keeps the legacy name the sources in highlight_sources/ call
+def Source( # noqa: N802 - reads like the HighlightSource it builds
*, name: str, find: Callable[[Context], HighlightFindings], scopes: tuple[str, ...] = (), pulse_order: int = 0
) -> HighlightSource:
- # A legacy source reads Today's own Context. Today always calls it with one, so the cast holds.
+ # Today's own sources read Today's full Context. Today always calls them with one, so the cast holds.
return HighlightSource(
name=name,
find=cast(Callable[[HighlightContext], HighlightFindings], find),
diff --git a/products/today/backend/logic/highlights.py b/products/today/backend/logic/highlights.py
index 19f435289262..a1e789f4795c 100644
--- a/products/today/backend/logic/highlights.py
+++ b/products/today/backend/logic/highlights.py
@@ -37,7 +37,7 @@ from ..temporal.inputs import (
highlights_workflow_id,
)
from . import pulse_pins
-from .highlight_registry import load_sources
+from .highlight_registry import load_sources, source_product
from .highlight_types import CACHE_SECONDS, Context, property_restrictions
from .pinned import PINNED_METRICS
@@ -259,6 +259,7 @@ def _item(candidate: HighlightCandidate) -> contracts.HighlightItem:
url=candidate.url,
series=candidate.series,
score=score,
+ product=source_product(candidate.source),
)
diff --git a/products/today/backend/logic/pinned.py b/products/today/backend/logic/pinned.py
index 3a8cce00011f..969d84d912e7 100644
--- a/products/today/backend/logic/pinned.py
+++ b/products/today/backend/logic/pinned.py
@@ -11,10 +11,10 @@ from products.customer_analytics.backend.facade.api import get_key_metrics
from ..facade import contracts
from ..temporal.inputs import PinnedNumber, ResolvePinsInputs, ResolvePinsResult
-from .highlight_sources.key_metrics import tile
-from .highlight_sources.routine import dashboard_tile_metric, insight_metric
from .highlight_types import Context
from .pulse_pins import INSIGHT_PREFIX, required_scopes
+from .today_highlights.key_metrics import tile
+from .today_highlights.routine import dashboard_tile_metric, insight_metric
PINNED_METRICS = TypeAdapter(list[contracts.HighlightMetric])
diff --git a/products/today/backend/logic/today_highlights/__init__.py b/products/today/backend/logic/today_highlights/__init__.py
new file mode 100644
index 000000000000..e69de29bb2d1
diff --git a/products/today/backend/logic/highlight_sources/home.py b/products/today/backend/logic/today_highlights/home.py
similarity index 100%
rename from products/today/backend/logic/highlight_sources/home.py
rename to products/today/backend/logic/today_highlights/home.py
diff --git a/products/today/backend/logic/highlight_sources/key_metrics.py b/products/today/backend/logic/today_highlights/key_metrics.py
similarity index 100%
rename from products/today/backend/logic/highlight_sources/key_metrics.py
rename to products/today/backend/logic/today_highlights/key_metrics.py
diff --git a/products/today/backend/logic/highlight_sources/routine.py b/products/today/backend/logic/today_highlights/routine.py
similarity index 100%
rename from products/today/backend/logic/highlight_sources/routine.py
rename to products/today/backend/logic/today_highlights/routine.py
diff --git a/products/today/backend/presentation/serializers.py b/products/today/backend/presentation/serializers.py
index 08ae3007ddfb..f6e0280d48a5 100644
--- a/products/today/backend/presentation/serializers.py
+++ b/products/today/backend/presentation/serializers.py
@@ -422,6 +422,9 @@ class HighlightItemSerializer(DataclassSerializer):
dataclass = HighlightItem
extra_kwargs = {
"source": {"help_text": "Name of the highlight source that found the item, for example alerts."},
+ "product": {
+ "help_text": "Product that declares the source, for example feature_flags. Null for items stored before this field existed and for sources that no product declares any more."
+ },
}
diff --git a/products/today/backend/tests/test_api.py b/products/today/backend/tests/test_api.py
index 602b320ef11d..7b43ac9f2567 100644
--- a/products/today/backend/tests/test_api.py
+++ b/products/today/backend/tests/test_api.py
@@ -27,8 +27,8 @@ from posthog.models.personal_api_key import hash_key_value
from products.access_control.backend.models.access_control import AccessControl
from products.signals.backend.facade import api as signals
from products.signals.backend.models import SignalReport
+from products.today.backend.facade.contracts import HighlightFindings, HighlightSource
from products.today.backend.logic import highlights, pinned
-from products.today.backend.logic.highlight_types import Found, Source
from products.today.backend.logic.jev import JevPick
from products.today.backend.temporal.inputs import (
ComputeHighlightsInputs,
@@ -355,9 +355,9 @@ def _temporal() -> MagicMock:
class TestTodayHighlightsAPI(TodayTeamScopedTestMixin, APIBaseTest):
def _get(self, connect: MagicMock, flag: bool = True, pulse: tuple[str, ...] = ("k1",)) -> "_MonkeyPatchedResponse":
- source = Source(
+ source = HighlightSource(
name="alerts",
- find=lambda _c: Found(
+ find=lambda _c: HighlightFindings(
items=(candidate("alert:1", "alerts", 0.8),), pulse=tuple(metric(key) for key in pulse)
),
)
diff --git a/products/today/backend/tests/test_highlight_insights.py b/products/today/backend/tests/test_highlight_insights.py
index bebf82e89ff6..c6e44e4eede8 100644
--- a/products/today/backend/tests/test_highlight_insights.py
+++ b/products/today/backend/tests/test_highlight_insights.py
@@ -16,9 +16,9 @@ from posthog.models import FileSystemViewLog
from products.dashboards.backend.facade.api import DashboardInsights, DashboardInsightTile
from products.product_analytics.backend.facade.contracts import InsightDashboardContext, InsightSeries
from products.today.backend.logic.highlight_rules import human, short
-from products.today.backend.logic.highlight_sources import home, routine
from products.today.backend.logic.highlight_trends import BAD_METRIC, MONEY, UNCLEAR_LABEL, UNKNOWN_DIRECTION
from products.today.backend.logic.highlight_types import Context
+from products.today.backend.logic.today_highlights import home, routine
TODAY = date(2026, 10, 13)
diff --git a/products/today/backend/tests/test_highlight_key_metrics.py b/products/today/backend/tests/test_highlight_key_metrics.py
index 2ec2ac1dc9da..ec92961b04a2 100644
--- a/products/today/backend/tests/test_highlight_key_metrics.py
+++ b/products/today/backend/tests/test_highlight_key_metrics.py
@@ -10,8 +10,8 @@ from django.test import SimpleTestCase
from products.customer_analytics.backend.facade.contracts import KeyMetric
from products.today.backend.logic.highlight_registry import load_sources
-from products.today.backend.logic.highlight_sources import key_metrics
from products.today.backend.logic.highlight_types import Context, DailyValueNotReady
+from products.today.backend.logic.today_highlights import key_metrics
TODAY = date(2026, 10, 13)
diff --git a/products/today/backend/tests/test_highlights.py b/products/today/backend/tests/test_highlights.py
index 89587a653433..8d5e2925beb0 100644
--- a/products/today/backend/tests/test_highlights.py
+++ b/products/today/backend/tests/test_highlights.py
@@ -490,4 +490,19 @@ class TestLoadSources(SimpleTestCase):
def test_a_broken_declaration_raises(self, _name: str, module: SimpleNamespace) -> None:
with patch.object(highlight_registry, "load_product_modules", return_value=[module]):
with self.assertRaises(highlight_registry.HighlightRegistryError):
- highlight_registry.load_sources.__wrapped__()
+ highlight_registry.load_registry.__wrapped__()
+
+ def test_each_source_belongs_to_the_product_that_declares_it(self) -> None:
+ flags = SimpleNamespace(
+ __name__="products.feature_flags.backend.facade.today_highlights",
+ HIGHLIGHT_SOURCES=(HighlightSource(name="flags", find=lambda _c: HighlightFindings()),),
+ )
+ pulse = SimpleNamespace(
+ __name__="products.today.backend.facade.today_highlights",
+ HIGHLIGHT_SOURCES=(HighlightSource(name="routine", find=lambda _c: HighlightFindings()),),
+ )
+
+ with patch.object(highlight_registry, "load_product_modules", return_value=[flags, pulse]):
+ registry = highlight_registry.load_registry.__wrapped__()
+
+ self.assertEqual(dict(registry.products), {"flags": "feature_flags", "routine": "today"})
diff --git a/products/today/backend/tests/test_pinned.py b/products/today/backend/tests/test_pinned.py
index 2909bbd7d01c..3c9cf62f219d 100644
--- a/products/today/backend/tests/test_pinned.py
+++ b/products/today/backend/tests/test_pinned.py
@@ -15,7 +15,7 @@ from products.product_analytics.backend.facade.contracts import InsightSeries
from products.today.backend.facade import contracts
from products.today.backend.facade.contracts import PulsePin
from products.today.backend.logic import pinned, pulse_pins
-from products.today.backend.logic.highlight_sources import routine
+from products.today.backend.logic.today_highlights import routine
from products.today.backend.temporal.inputs import PinnedNumber, ResolvePinsInputs
TODAY = date(2026, 10, 13)
diff --git a/products/today/frontend/generated/api.schemas.ts b/products/today/frontend/generated/api.schemas.ts
index 859cbdc0e6fe..0e33722c4c35 100644
--- a/products/today/frontend/generated/api.schemas.ts
+++ b/products/today/frontend/generated/api.schemas.ts
@@ -247,6 +247,11 @@ export interface HighlightItemApi {
score: number
/** Name of the highlight source that found the item, for example alerts. */
source: string
+ /**
+ * Product that declares the source, for example feature_flags. Null for items stored before this field existed and for sources that no product declares any more.
+ * @nullable
+ */
+ product?: string | null
}
/**
diff --git a/products/web_analytics/backend/facade/today_highlights.py b/products/web_analytics/backend/facade/today_highlights.py
new file mode 100644
index 000000000000..024f118309c3
--- /dev/null
+++ b/products/web_analytics/backend/facade/today_highlights.py
@@ -0,0 +1,7 @@
+"""Web analytics' sources for the "For you today" list. Today finds this module by name."""
+
+from products.today.backend.facade.contracts import HighlightSource
+
+from ..today_highlights import find_rage_page
+
+HIGHLIGHT_SOURCES = (HighlightSource(name="rage", find=find_rage_page),)
diff --git a/products/today/backend/tests/test_highlight_rage.py b/products/web_analytics/backend/test/test_today_highlights.py
similarity index 83%
rename from products/today/backend/tests/test_highlight_rage.py
rename to products/web_analytics/backend/test/test_today_highlights.py
index 5e45451ffc78..5197ed9090a3 100644
--- a/products/today/backend/tests/test_highlight_rage.py
+++ b/products/web_analytics/backend/test/test_today_highlights.py
@@ -10,10 +10,10 @@ from django.test import SimpleTestCase
from parameterized import parameterized
from products.error_tracking.backend.facade.contracts import ErrorTrackingIssueBasics
-from products.today.backend.logic.highlight_registry import load_sources
-from products.today.backend.logic.highlight_sources import rage
-from products.today.backend.logic.highlight_types import Context
+from products.today.backend.facade.contracts import HighlightContext
+from products.web_analytics.backend import today_highlights
from products.web_analytics.backend.facade.rage_pages import ErrorsBeforeRage, RagePage
+from products.web_analytics.backend.facade.today_highlights import HIGHLIGHT_SOURCES
ISSUE_ID = uuid.UUID("01890000-0000-7000-8000-000000000002")
PAGE = RagePage(path="/checkout/…", people=12, clicks=340)
@@ -100,7 +100,7 @@ class TestRage(SimpleTestCase):
expected: list[tuple[str, str, str]],
) -> None:
context = cast(
- Context,
+ HighlightContext,
SimpleNamespace(
team=SimpleNamespace(id=1),
user=SimpleNamespace(id=2),
@@ -120,14 +120,14 @@ class TestRage(SimpleTestCase):
created_at=datetime(2026, 10, 1, tzinfo=UTC),
first_seen=None,
)
- registered = next(s for s in load_sources() if s.name == "rage")
+ registered = next(s for s in HIGHLIGHT_SOURCES if s.name == "rage")
with (
- patch.object(rage, "uses_product", return_value=relevant),
- patch.object(rage, "find_top_rage_page", return_value=page),
- patch.object(rage, "find_top_rage_element", return_value=element),
- patch.object(rage, "find_errors_before_rage", return_value=errors),
- patch.object(rage, "get_issue_basics", return_value=issue),
+ patch.object(today_highlights, "uses_product", return_value=relevant),
+ patch.object(today_highlights, "find_top_rage_page", return_value=page),
+ patch.object(today_highlights, "find_top_rage_element", return_value=element),
+ patch.object(today_highlights, "find_errors_before_rage", return_value=errors),
+ patch.object(today_highlights, "get_issue_basics", return_value=issue),
):
found = registered.find(context)
diff --git a/products/today/backend/logic/highlight_sources/rage.py b/products/web_analytics/backend/today_highlights.py
similarity index 81%
rename from products/today/backend/logic/highlight_sources/rage.py
rename to products/web_analytics/backend/today_highlights.py
index 1d10fca3092c..5c9ece4fbeea 100644
--- a/products/today/backend/logic/highlight_sources/rage.py
+++ b/products/web_analytics/backend/today_highlights.py
@@ -1,6 +1,9 @@
import hashlib
from products.error_tracking.backend.facade.api import get_issue_basics
+from products.today.backend.facade.contracts import HighlightCandidate, HighlightContext, HighlightFindings
+from products.today.backend.facade.enums import HighlightLabel
+from products.today.backend.facade.highlight_helpers import human, short, users, uses_product
from products.web_analytics.backend.facade.rage_pages import (
ErrorsBeforeRage,
RagePage,
@@ -9,10 +12,6 @@ from products.web_analytics.backend.facade.rage_pages import (
find_top_rage_page,
)
-from ...facade.enums import HighlightLabel
-from ..highlight_rules import human, short, users, uses_product
-from ..highlight_types import Candidate, Context, Found, Source
-
RAGE_PAGE = "{people} rage-clicked on {page} in the last 7 days"
RAGE_PAGE_DETAIL = "{clicks} rage clicks · Top element: ‘{element}’"
RAGE_PAGE_NO_ELEMENT_DETAIL = "{clicks} rage clicks"
@@ -24,12 +23,36 @@ MIN_ERROR_SHARE = 0.3
NO_ERRORS = ErrorsBeforeRage(sessions=0, issue_id=None, issue_sessions=0)
-def find(context: Context) -> Found:
+def _error_item(
+ context: HighlightContext, page: RagePage, errors: ErrorsBeforeRage, title: str
+) -> HighlightCandidate | None:
+ issue_id = errors.issue_id
+ share = errors.issue_sessions / errors.sessions if errors.sessions else 0
+ if issue_id is None or errors.issue_sessions < MIN_ERROR_SESSIONS or share < MIN_ERROR_SHARE:
+ return None
+ issue = context.guard("rage_issue", lambda: get_issue_basics(context.team.id, issue_id), None)
+ if issue is None:
+ return None
+ name = f"{issue.name or 'Issue'}: {issue.description}" if issue.description else issue.name or "Issue"
+ return HighlightCandidate(
+ key=f"rage:{page.path}",
+ label=HighlightLabel.RISK,
+ family="replay",
+ importance=0.6,
+ relevance=1.0,
+ title=title,
+ detail=RAGE_PAGE_ERROR_DETAIL.format(pct=f"{share * 100:.0f}", issue=short(name, 50)),
+ url=f"/error_tracking/{issue_id}",
+ ref=issue_id,
+ )
+
+
+def find_rage_page(context: HighlightContext) -> HighlightFindings:
if not uses_product(context, *RAGE_PRODUCTS):
- return Found()
+ return HighlightFindings()
page = context.daily("rage_page", lambda: find_top_rage_page(context.team, context.user))
if page is None:
- return Found()
+ return HighlightFindings()
path_key = hashlib.sha256(page.path.encode()).hexdigest()[:16]
title = RAGE_PAGE.format(people=users(page.people), page=(page.path or "/")[:40])
if context.allows("error_tracking:read"):
@@ -42,7 +65,7 @@ def find(context: Context) -> Found:
)
error = _error_item(context, page, errors, title)
if error is not None:
- return Found(items=(error,))
+ return HighlightFindings(items=(error,))
top_element = context.guard(
"rage_element",
lambda: context.daily(
@@ -52,9 +75,9 @@ def find(context: Context) -> Found:
)
element = short(top_element or "", 30)
clicks = human(page.clicks)
- return Found(
+ return HighlightFindings(
items=(
- Candidate(
+ HighlightCandidate(
key=f"rage:{page.path}",
label=HighlightLabel.RISK,
family="replay",
@@ -68,28 +91,3 @@ def find(context: Context) -> Found:
),
)
)
-
-
-def _error_item(context: Context, page: RagePage, errors: ErrorsBeforeRage, title: str) -> Candidate | None:
- issue_id = errors.issue_id
- share = errors.issue_sessions / errors.sessions if errors.sessions else 0
- if issue_id is None or errors.issue_sessions < MIN_ERROR_SESSIONS or share < MIN_ERROR_SHARE:
- return None
- issue = context.guard("rage_issue", lambda: get_issue_basics(context.team.id, issue_id), None)
- if issue is None:
- return None
- name = f"{issue.name or 'Issue'}: {issue.description}" if issue.description else issue.name or "Issue"
- return Candidate(
- key=f"rage:{page.path}",
- label=HighlightLabel.RISK,
- family="replay",
- importance=0.6,
- relevance=1.0,
- title=title,
- detail=RAGE_PAGE_ERROR_DETAIL.format(pct=f"{share * 100:.0f}", issue=short(name, 50)),
- url=f"/error_tracking/{issue_id}",
- ref=issue_id,
- )
-
-
-SOURCE = Source(name="rage", find=find)
diff --git a/products/workflows/backend/facade/today_highlights.py b/products/workflows/backend/facade/today_highlights.py
new file mode 100644
index 000000000000..4f59ed3fcdfb
--- /dev/null
+++ b/products/workflows/backend/facade/today_highlights.py
@@ -0,0 +1,11 @@
+"""Workflows' sources for the "For you today" list. Today finds this module by name."""
+
+from products.today.backend.facade.contracts import HighlightSource
+
+from ..today_highlights.health import find_workflow_health
+from ..today_highlights.ideas import find_workflow_ideas
+
+HIGHLIGHT_SOURCES = (
+ HighlightSource(name="workflows", find=find_workflow_health, scopes=("hog_flow:read",)),
+ HighlightSource(name="workflow_ideas", find=find_workflow_ideas, scopes=("hog_flow:read",)),
+)
diff --git a/products/today/backend/tests/test_highlight_workflows.py b/products/workflows/backend/tests/test_workflow_today_highlights.py
similarity index 82%
rename from products/today/backend/tests/test_highlight_workflows.py
rename to products/workflows/backend/tests/test_workflow_today_highlights.py
index ab7812e5ffa7..04701126e0ce 100644
--- a/products/today/backend/tests/test_highlight_workflows.py
+++ b/products/workflows/backend/tests/test_workflow_today_highlights.py
@@ -9,14 +9,14 @@ from django.test import SimpleTestCase
from parameterized import parameterized
+from products.today.backend.facade.contracts import HighlightContext
from products.today.backend.facade.enums import HighlightLabel
-from products.today.backend.logic.highlight_registry import load_sources
-from products.today.backend.logic.highlight_sources import workflow_ideas, workflows
-from products.today.backend.logic.highlight_types import Context
from products.workflows.backend.facade.contracts import EmailSendingState, OwnedWorkflowHealth
+from products.workflows.backend.facade.today_highlights import HIGHLIGHT_SOURCES
+from products.workflows.backend.today_highlights import health, ideas
WORKFLOW_ID = uuid.UUID("00000000-0000-4000-8000-000000000001")
-CONTEXT = cast(Context, SimpleNamespace(team=SimpleNamespace(id=1), user=None))
+CONTEXT = cast(HighlightContext, SimpleNamespace(team=SimpleNamespace(id=1), user=None))
def _workflow(**fields: Any) -> OwnedWorkflowHealth:
@@ -92,11 +92,11 @@ class TestWorkflows(SimpleTestCase):
def test_a_workflow_shows_what_needs_its_owner(
self, _name: str, workflow: OwnedWorkflowHealth, expected: list[tuple[HighlightLabel, str, str, str]]
) -> None:
- registered = next(s for s in load_sources() if s.name == "workflows")
+ registered = next(s for s in HIGHLIGHT_SOURCES if s.name == "workflows")
with (
- patch.object(workflows, "list_owned_workflow_health", return_value=[workflow]),
- patch.object(workflows, "get_email_sending_state", return_value=None),
+ patch.object(health, "list_owned_workflow_health", return_value=[workflow]),
+ patch.object(health, "get_email_sending_state", return_value=None),
):
found = registered.find(CONTEXT)
@@ -112,7 +112,7 @@ class TestWorkflows(SimpleTestCase):
def test_a_suspended_project_shows_to_workflow_owners(
self, _name: str, owned: list[OwnedWorkflowHealth], suspended: bool, expected: list[str]
) -> None:
- registered = next(s for s in load_sources() if s.name == "workflows")
+ registered = next(s for s in HIGHLIGHT_SOURCES if s.name == "workflows")
state = EmailSendingState(
suspended_at=datetime(2026, 10, 1, tzinfo=UTC) if suspended else None,
suspension_reason="",
@@ -122,8 +122,8 @@ class TestWorkflows(SimpleTestCase):
)
with (
- patch.object(workflows, "list_owned_workflow_health", return_value=owned),
- patch.object(workflows, "get_email_sending_state", return_value=state),
+ patch.object(health, "list_owned_workflow_health", return_value=owned),
+ patch.object(health, "get_email_sending_state", return_value=state),
):
found = registered.find(CONTEXT)
@@ -137,9 +137,9 @@ class TestWorkflows(SimpleTestCase):
]
)
def test_waiting_workflow_ideas_show_once(self, _name: str, count: int, expected: list[str]) -> None:
- registered = next(s for s in load_sources() if s.name == "workflow_ideas")
+ registered = next(s for s in HIGHLIGHT_SOURCES if s.name == "workflow_ideas")
- with patch.object(workflow_ideas, "count_waiting_data_suggestions", return_value=count):
+ with patch.object(ideas, "count_waiting_data_suggestions", return_value=count):
found = registered.find(CONTEXT)
self.assertEqual([(c.title, c.url) for c in found.items], [(title, "/workflows") for title in expected])
diff --git a/products/workflows/backend/today_highlights/__init__.py b/products/workflows/backend/today_highlights/__init__.py
new file mode 100644
index 000000000000..e69de29bb2d1
diff --git a/products/today/backend/logic/highlight_sources/workflows.py b/products/workflows/backend/today_highlights/health.py
similarity index 85%
rename from products/today/backend/logic/highlight_sources/workflows.py
rename to products/workflows/backend/today_highlights/health.py
index d0140076601d..11b156d869c7 100644
--- a/products/today/backend/logic/highlight_sources/workflows.py
+++ b/products/workflows/backend/today_highlights/health.py
@@ -1,10 +1,9 @@
+from products.today.backend.facade.contracts import HighlightCandidate, HighlightContext, HighlightFindings
+from products.today.backend.facade.enums import HighlightLabel
+from products.today.backend.facade.highlight_helpers import exact, short
from products.workflows.backend.facade.api import get_email_sending_state, list_owned_workflow_health
from products.workflows.backend.facade.contracts import OwnedWorkflowHealth
-from ...facade.enums import HighlightLabel
-from ..highlight_rules import exact, short
-from ..highlight_types import Candidate, Context, Found, Source
-
SENDING_SUSPENDED = "Email sending is suspended for this project"
SENDING_SUSPENDED_DETAIL = "Workflow and broadcast emails are not delivered. Contact support to turn sending back on"
EMAILS_PAUSED = "Emails are paused for workflow ‘{workflow}’"
@@ -19,20 +18,9 @@ MIN_FAILED = 10
MIN_FAILED_SHARE = 0.1
-def find(context: Context) -> Found:
- workflows = list_owned_workflow_health(team=context.team, user=context.user, limit=20)
- if not workflows:
- return Found()
- candidates = [candidate for workflow in workflows for candidate in _candidates(workflow)]
- state = get_email_sending_state(context.team.id)
- if state is not None and state.suspended_at is not None:
- candidates.insert(0, _sending_suspended())
- return Found(items=tuple(candidates))
-
-
-def _sending_suspended() -> Candidate:
+def _sending_suspended() -> HighlightCandidate:
# Suspension stops every email step in the project, so it outranks any one workflow's problem.
- return Candidate(
+ return HighlightCandidate(
key="workflows:email-sending-suspended",
label=HighlightLabel.RISK,
family="workflows",
@@ -44,7 +32,7 @@ def _sending_suspended() -> Candidate:
)
-def _candidates(workflow: OwnedWorkflowHealth) -> list[Candidate]:
+def _candidates(workflow: OwnedWorkflowHealth) -> list[HighlightCandidate]:
name = short(workflow.name)
candidates = []
if workflow.email_sending_paused:
@@ -100,8 +88,8 @@ def _candidate(
title: str,
detail: str,
tab: str,
-) -> Candidate:
- return Candidate(
+) -> HighlightCandidate:
+ return HighlightCandidate(
key=f"workflow:{workflow.workflow_id}:{kind}",
label=label,
family="workflows",
@@ -113,4 +101,12 @@ def _candidate(
)
-SOURCE = Source(name="workflows", find=find, scopes=("hog_flow:read",))
+def find_workflow_health(context: HighlightContext) -> HighlightFindings:
+ workflows = list_owned_workflow_health(team=context.team, user=context.user, limit=20)
+ if not workflows:
+ return HighlightFindings()
+ candidates = [candidate for workflow in workflows for candidate in _candidates(workflow)]
+ state = get_email_sending_state(context.team.id)
+ if state is not None and state.suspended_at is not None:
+ candidates.insert(0, _sending_suspended())
+ return HighlightFindings(items=tuple(candidates))
diff --git a/products/today/backend/logic/highlight_sources/workflow_ideas.py b/products/workflows/backend/today_highlights/ideas.py
similarity index 64%
rename from products/today/backend/logic/highlight_sources/workflow_ideas.py
rename to products/workflows/backend/today_highlights/ideas.py
index d18c35604110..d80a6b02c89e 100644
--- a/products/today/backend/logic/highlight_sources/workflow_ideas.py
+++ b/products/workflows/backend/today_highlights/ideas.py
@@ -1,21 +1,20 @@
+from products.today.backend.facade.contracts import HighlightCandidate, HighlightContext, HighlightFindings
+from products.today.backend.facade.enums import HighlightLabel
+from products.today.backend.facade.highlight_helpers import exact
from products.workflows.backend.facade.data_suggestions import count_waiting_data_suggestions
-from ...facade.enums import HighlightLabel
-from ..highlight_rules import exact
-from ..highlight_types import Candidate, Context, Found, Source
-
IDEAS = "{count} workflow ideas based on your events are ready"
IDEA = "1 workflow idea based on your events is ready"
IDEAS_DETAIL = "Pick one to build it as a draft workflow"
-def find(context: Context) -> Found:
+def find_workflow_ideas(context: HighlightContext) -> HighlightFindings:
count = count_waiting_data_suggestions(team=context.team)
if not count:
- return Found()
- return Found(
+ return HighlightFindings()
+ return HighlightFindings(
items=(
- Candidate(
+ HighlightCandidate(
key="workflow-ideas",
label=HighlightLabel.OPPORTUNITY,
family="workflows",
@@ -27,6 +26,3 @@ def find(context: Context) -> Found:
),
)
)
-
-
-SOURCE = Source(name="workflow_ideas", find=find, scopes=("hog_flow:read",))
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index dbc9815580c3..78a95291c5b9 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -58362,6 +58362,11 @@ export namespace Schemas {
score: number;
/** Name of the highlight source that found the item, for example alerts. */
source: string;
+ /**
+ * Product that declares the source, for example feature_flags. Null for items stored before this field existed and for sources that no product declares any more.
+ * @nullable
+ */
+ product?: string | null;
}
/**
diff --git a/tach.toml b/tach.toml
index c3b1464303ac..9169ea139cff 100644
--- a/tach.toml
+++ b/tach.toml
@@ -194,6 +194,8 @@ depends_on = [
"posthog",
"products.cdp",
"products.product_analytics", "products.access_control",
+ # Facade-only: alerts declares its Today highlight sources against the Today facade contract.
+ "products.today",
]
layer = "modules"
@@ -283,6 +285,8 @@ depends_on = [
# Facade-only: the deleted-ticket purge retracts the ticket's signal embeddings. products.signals
# depends on products.conversations in turn, so keep this direction on the facade.
"products.signals",
+ # Facade-only: conversations declares its Today highlight sources against the Today facade contract.
+ "products.today",
]
layer = "modules"
@@ -522,6 +526,8 @@ depends_on = [
"products.surveys",
"products.tasks",
"products.warehouse_sources",
+ # Facade-only: experiments declares its Today highlight sources against the Today facade contract.
+ "products.today",
]
layer = "modules"
@@ -541,6 +547,8 @@ depends_on = [
"products.product_tours",
"products.surveys", "products.access_control",
"products.notifications",
+ # Facade-only: feature flags declares its Today highlight sources against the Today facade contract.
+ "products.today",
]
layer = "modules"
@@ -1132,6 +1140,10 @@ depends_on = [
# The web trends, web vitals and calendar heatmap runners subclass product analytics' trends runners.
"products.product_analytics",
"products.replay_vision",
+ # Facade-only: the rage-click highlight names the error people saw before rage-clicking.
+ "products.error_tracking",
+ # Facade-only: web analytics declares its Today highlight sources against the Today facade contract.
+ "products.today",
]
layer = "modules"
@@ -1161,6 +1173,8 @@ depends_on = [
# Facade-only: the Replay Vision step's endpoint starts a scan through
# products.replay_vision.backend.facade.api.
"products.replay_vision",
+ # Facade-only: workflows declares its Today highlight sources against the Today facade contract.
+ "products.today",
]
layer = "modules"
@@ -1584,6 +1598,8 @@ depends_on = [
"products.product_analytics",
"products.warehouse_sources",
"products.data_modeling", "products.access_control",
+ # Facade-only: data catalog declares its Today highlight sources against the Today facade contract.
+ "products.today",
]
layer = "modules"
@@ -1680,19 +1696,11 @@ depends_on = [
"ee",
"posthog",
"products.access_control",
- "products.alerts",
- "products.conversations",
"products.customer_analytics",
"products.dashboards",
- "products.data_catalog",
- "products.error_tracking",
- "products.experiments",
- "products.feature_flags",
"products.product_analytics",
"products.signals",
"products.tasks",
- "products.web_analytics",
- "products.workflows",
]
layer = "modules"