Technical reference. For task-based help, see the corresponding user guide.

Documentation status: reviewed against implementation · Reviewed: 2026-07-21 · Viewers: family and coach · Authoring: global owner/super-admin only · Surfaces: mobile web, coach portal and platform API

Notification banners deliver time-bound product or service announcements to a controlled audience. The platform decides eligibility; mobile web presents the highest-priority eligible message and records interaction; the coach portal provides a read-only current/past inbox for coach announcements.

1. Mobile requests GET /notification-banners/eligible with ios, android or web from the current runtime.
2. The platform requires an active lifecycle state, the current schedule window, matching platform and audience/scope, and include/exclude eligibility.
3. A prior seen, dismissed or clicked receipt removes that banner from the eligible feed for the actor.
4. Eligible banners are returned in priority/start/creation order. The host presents one banner at a time.
5. The session cache is scoped to actor, authentication session and platform; home refreshes are throttled to avoid repeated requests.

1. Tone/icon maps to info, success, warning or urgent presentation.
2. Short copy remains compact. A CTA, newline or longer message enables expansion/detail.
3. First display records seen once for that actor/banner.
4. The close control exists only when dismissible is true. Dismissal records dismissed and removes the cached item.
5. CTA selection records clicked before navigation.
6. app://feedback and app://getting-started resolve to the viewer's role-specific in-app route. Other links use the native/browser external opener.
7. A banner reached from a push/deep-link query can be shown locally; a purely local fallback does not fabricate platform receipts.

1. GET /coach/notification-banners returns global coach/all banners available to that active coach organization context.
2. The portal separates Current (started scheduled/live and not ended) from Past, shows audience/availability/published metadata and opens a detail modal.
3. External CTA links render only when they parse as HTTP or HTTPS.
4. The optional Family tab belongs to the family-activity notification inbox documented in Feature 22, not banner authoring.

1. The owner creates a draft with content, audience, schedule, priority, targeting, CTA, dismissibility and push preference.
2. Publishing/scheduling sets the status and publication audit metadata. Pausing removes it from active eligibility; expiry follows its lifecycle/end window; archive retains history.
3. Owner APIs expose aggregate per-user receipts for operational review.
4. All create/update/status/receipt-list/delete routes under /coach/notification-banners deliberately return 403. Dormant coach banner editor components are not a supported product surface.

• Authoring and receipt inspection are owner/super-admin operations; coach portal access is read-only.
• Eligibility is computed from the authenticated platform actor. Query parameters cannot select another audience or email.
• Receipts contain user/banner identity, interaction timestamps and optional device platform/app version; they do not grant targeting access.
• External URLs are not treated as trusted application routes. In-app schemes are mapped through an explicit allowlist.
• Banner push uses the registered-device system in Feature 32; the in-app eligibility checks remain authoritative when opened.

Coach-side authoring code exists in dormant components and domain helpers, but every coach mutation route is intentionally denied. Document and support owner-only global authoring until that boundary is deliberately changed end to end.

1. [ ] Audience, platform, schedule, lifecycle and email targeting are all enforced server-side.
2. [ ] Highest-priority eligible banner is shown without blocking the host page.
3. [ ] Seen/dismissed/clicked receipts are idempotently upserted.
4. [ ] Dismissibility and CTA rules match the shared schema.
5. [ ] In-app CTA schemes map only to supported routes; external links use a safe opener.
6. [ ] Coach portal classifies current/past correctly and cannot mutate banners.
7. [ ] Owner status transitions and receipt access produce audit events.

• Mobile web: mobile-web/src/components/NotificationBannerHost.tsx, mobile-web/src/components/notification-banner-cta.ts
• Coach portal: admin-web/src/routes/NotificationsPanel.tsx
• Platform: platform/packages/shared/src/notification-banners.ts, platform/apps/api/src/routes/notification-banner-routes.ts, platform/apps/api/src/services/notification-banner-service.ts, platform/apps/api/src/services/prisma-notification-banner-service.ts

• 22 — Family activity notifications
• 28 — FAQs, feedback and support
• 29 — Getting-started guides
• 31 — Review prompts
• 32 — Realtime updates and push notifications