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

Documentation status: reviewed against implementation · Reviewed: 2026-07-21 · Primary users: family and coach · Surfaces: mobile web, coach portal, native wrapper, Supabase Realtime and platform API

Realtime makes an open app refresh sooner; push asks a backgrounded native app to reopen at a useful route. Both are delivery hints. Trusted records and authorization always come from a fresh platform REST request.

1. Client gate VITE_REALTIME_PRESENCE_ENABLED and server gate REALTIME_PRESENCE_ENABLED must be explicitly 1/true (server uses 1).
2. Authenticated clients request GET /realtime/presence/v2/credential; v1 remains compatibility-only.
3. Credentials are opaque, Cache-Control: no-store and expire between 60 seconds and 24 hours (24 hours by default). V2 binds the ticket to the current auth session.
4. The client tracks only while the document is visible, refreshes before expiry, disconnects when hidden and reconnects with bounded exponential backoff/jitter.
5. Owner view-as sessions cannot issue presence, so impersonation never creates a second online identity.
6. Only super-admin can resolve opaque presence entries to user identity through POST /admin/realtime/presence/v2/resolve (maximum 500 entries). Family/coach clients cannot resolve the directory.

Presence is operational “online” state only; it never grants access to a tenant, conversation or family.

1. Client VITE_REALTIME_BROADCAST_ENABLED and server REALTIME_BROADCAST_ENABLED must be enabled; Supabase server configuration is also required.
2. The server publishes a schema-versioned resource.changed hint to the affected authenticated user's private topic.
3. Kinds cover resources such as activities, active timers, family/access state, activity-notification state and chat conversations/messages/unread state.
4. Mobile and portal validate the exact schema/identifier format, coalesce equivalent hints (normally for 250 ms), then call the appropriate REST loader.
5. Reconnect triggers a local resync for interested resources because broadcast is not a durable event log.
6. Window focus/visibility refresh and feature-specific polling remain fallbacks when Realtime is disabled, disconnected or misses a hint.
7. While a user edits a record, a matching invalidation can surface an external-update conflict rather than overwriting the draft silently.

1. Push is native iOS/Android only and is disabled for owner view-as.
2. Native supplies fcmToken, stable deviceId, platform, permission status, wrapper version and app/web version to POST /push/devices.
3. Registration upserts the current actor/device and disables an older active token for the same device when the token rotates.
4. Family bootstrap may request/register permission. Coach bootstrap checks status without prompting; an explicit activity/chat push toggle requests permission.
5. If native permission/token is not immediately available, the app can retry without blocking sign-in.

1. Turning a product preference off suppresses that push type but need not invalidate the whole device.
2. Logout first asks native to unregister and calls DELETE /push/devices/current by token/device ID, then signs out. Cleanup is best-effort, and every sender also rechecks enabled state before delivery.

1. UI gate VITE_COACH_ACTIVITY_PUSH_ENABLED and backend COACH_ACTIVITY_PUSH_ENABLED must permit the feature (both default off in production unless explicitly enabled).
2. The native wrapper must be SemVer 4.6.0 or newer; older versions see update-required copy instead of a usable toggle.
3. Only a family-created activity is queued. At enqueue and again before send, the platform checks active assignment/current record access, active subscription/support boundary, global activity alerts, per-family mute, push preference, enabled device, permission granted/provisional and compatible wrapper.
4. Copy is deliberately generic: New family activity — Open Littles Baby Tracker to review. Data carries only schema/source, activity ID and /coach/notifications.

1. Chat itself, chat push and organization rollout/canary must all be enabled on server; mobile also requires VITE_COACH_FAMILY_CHAT_PUSH_ENABLED.
2. Minimum wrapper is 4.7.0.
3. Delivery rechecks active coach/family relationship, organization chat rollout, open moderation state, both participants' chat settings, recipient unread/push preference and an enabled device with granted permission.
4. Copy is deliberately generic: New message — Open Littles Baby Tracker to read it. It contains no message text, baby name or family name.
5. Wrapper validates source/schema and routes by recipient role to /family/messages/<conversation> or /coach/messages/<conversation>.

• Private Realtime channels use the genuine Supabase JWT; application API bearer tokens are not copied into broadcast payloads.
• A resource hint has no trusted business data. Every refresh is authorized by the platform API at read time.
• Presence identity resolution is server-ticket validated and super-admin-only.
• Push payloads are generic because lock-screen text may be visible to other people.
• Sender workers re-evaluate access, preferences, device status and wrapper compatibility at delivery—not only when queued.

Realtime is not a consistency or authorization layer, and push is not proof that a user still has access. New resource kinds and push data fields require privacy review, strict schema validation and an authorized REST refresh/deep-link destination.

1. [ ] Presence/broadcast stay inert unless both relevant client/server configuration is enabled.
2. [ ] View-as cannot publish genuine presence; only super-admin resolves identities.
3. [ ] Broadcast events contain only validated invalidation metadata and trigger authorized REST refresh.
4. [ ] Reconnect/focus paths recover freshness after missed events.
5. [ ] Token rotation and logout disable stale device registrations best-effort.
6. [ ] Activity push enforces 4.6.0, family-created source and every preference/access gate.
7. [ ] Chat push enforces 4.7.0, chat rollout/relationship/moderation and participant preferences.
8. [ ] Lock-screen copy contains no care record, message text, baby or family identity.

• Mobile web: mobile-web/src/realtime/, mobile-web/src/App.tsx, mobile-web/src/components/CoachActivityNotificationsPanel.tsx, chat push settings and mobile-web/src/webview/native-messages.ts
• Coach portal: admin-web/src/realtime/, admin-web/src/App.tsx, chat/activity notification integrations
• Platform: platform/packages/shared/src/realtime.ts, push-devices.ts, coach-activity-notifications.ts, coach-family-chat.ts; platform/apps/api/src/routes/realtime-presence-routes.ts, push-device-routes.ts; realtime and push services
• Native wrapper: mobile-wrapper/src/native/chatPushNotifications.ts and notification/bridge handlers

• 14 — Coach–family messaging
• 22 — Family activity notifications
• 27 — Announcements and notification banners
• 33 — Offline, cache and app updates