Skip to content

Realtime and Notifications

Ankit Upadhyay edited this page Aug 25, 2026 · 2 revisions

Realtime and Notifications

How clinic staff and pet owners get live chat, push notifications, and time-based automation. Operational setup is in Realtime Setup and Notifications Setup; this page is the architecture.

Three mechanisms, not one

The platform's "realtime" surface is really three distinct systems:

Need Mechanism
Chat between people Stream Chat (getstream.io)
Push to devices Firebase Cloud Messaging (FCM) + Notifee (mobile), email via AWS SES/Pinpoint
Time-based / async automation BullMQ queues over Redis

Chat: Stream Chat

Conversations run on Stream Chat, not a home-grown socket layer:

  • The backend chat.service.ts uses StreamChat.getInstance to provision users and channels; the mobile app uses stream-chat-react-native.
  • Appointment-scoped channels are windowed by appointment status (chat opens/closes around the visit lifecycle). There's also a network/colleague chat and shared-entity chat.
  • Stream calls back into the backend at a raw-body webhook /v1/chat/webhooks/stream (ChatWebhookController.handleStreamEvent).
  • Upload safety: config/stream-upload-policy.ts pushes a blocked-extension allowlist to Stream at boot; attachments are virus-scanned (attachmentScanner.service.ts, VirusTotal). Enforcement of the blocklist against Stream was fixed in PR #2431 - it was previously configured but not applied.

The Support Chat plans add a dedicated SUPPORT session type on this same Stream infrastructure.

Push notifications

  • Mobile: server-side firebase-admin sends FCM messages; the device presents them with Notifee, routing taps via a yc:// deep-link scheme. Setup and entry points: Notifications Setup.
  • Backend: notification.service.ts + deviceToken.service.ts manage tokens and dispatch; templates in notificationTemplates.ts; email via AWS SES/Pinpoint.
  • Care-reminder emails carry opt-out/unsubscribe handling since PR #2419, with a recipient-level opt-out stored in the database.

Background automation: BullMQ

Time-based and async work runs on BullMQ (Redis-backed), initialized by queues/index.ts (initQueues()) at boot and processed by workers in src/workers:

  • Appointments — MARK_NO_SHOW (auto no-show after a window).
  • Tasks — recurrence, reminders, and schedule engines (taskRecurrence/taskReminder/taskSchedule workers).
  • Labs — IDEXX reference sync, lab-status polling, lab-result ingestion.

There is no central EventBus module today; decoupling is via BullMQ queues plus a FinanceEventService for finance audit events.

A note on the Socket.IO design

docs/guide/realtime-backend.md documents a proposed Redis Pub/Sub + Socket.IO event bus (org-scoped org:{orgId}:events fan-out to browsers) with a shared OrgEvent contract. As of this writing that design is not wired up — socket.io is an installed dependency but no Socket.IO server exists in apps/backend. Treat it as a forward-looking design for browser live-sync, not current behavior. See Realtime Setup for the distinction.

Related

Product & Domain
Architecture
Applications
Design & Accessibility
Engineering Handbook
Decisions (ADRs)
Design Docs & Plans
Roadmap
Operations
Meta

Canonical code & docs: main repo · Auto-generated companion: DeepWiki

Clone this wiki locally