Skip to content

Realtime Setup

Ankit Upadhyay edited this page Jul 9, 2026 · 1 revision

Realtime Setup

How live updates actually work across the stack, operationally. Architecture and rationale: Realtime and Notifications.

Chat (Stream Chat)

  • Backend: chat.service.ts uses StreamChat.getInstance with STREAM_API_KEY / STREAM_API_SECRET. Appointment channels are windowed by appointment status; there's also network/colleague chat. Stream posts events back to the raw-body webhook /v1/chat/webhooks/stream (ChatWebhookController.handleStreamEvent). At boot, config/stream-upload-policy.ts pushes a blocked-extension allowlist to Stream.
  • Web: features/chat/services/streamChatService.ts + chatService.ts; features/chat/hooks/useChatNotifications.ts listens to client.on('message.new') and raises a browser Notification when the tab is hidden. The CSP allowlists chat.stream-io-api.com + wss: (Frontend Overview).
  • Mobile: stream-chat-react-native via src/features/chat/services/streamChatService.ts.

Cross-tab live sync (web)

Beyond chat, the web app keeps itself fresh without a socket event bus:

  • Custom window events + useSyncExternalStore: e.g. useAppointmentLockWindow.ts subscribes to a yc:appointment-lock-window-changed event and the storage event so multiple tabs stay consistent; SessionInitializer runs a MutationObserver terminology rewriter keyed on yc:companion-terminology-changed.
  • Bulk hydration on org change: SessionInitializer fires Promise.allSettled([...loadX({silent:true})]) across all org-scoped Zustand stores whenever the primary org changes.

Push notifications

  • Mobile: firebase-admin (server) → FCM → Notifee (device), routed via a yc:// deep link. Setup: Notifications Setup.
  • Device tokens are registered/unregistered through deviceToken.service.ts.

Background automation (BullMQ)

queues/index.ts (initQueues()) starts BullMQ queues on the shared Redis connection (queues/bull.config.ts), processed by src/workers: appointment no-show, task recurrence/reminder/schedule, and IDEXX lab sync/status/results. Redis env vars are shared with the rest of the app.

The Socket.IO org-event bus is a design, not current behavior

docs/guide/realtime-backend.md proposes a Redis Pub/Sub + Socket.IO EventBus that would fan org:{orgId}:events out to browsers, with a shared OrgEvent contract and a frontend hook to apply them. This is not implemented — socket.io is an installed dependency but no Socket.IO server exists in apps/backend, and there is no useRealtimeSync hook in the frontend. If you're wiring browser live-sync, that guide is the starting design; today, use the mechanisms above.

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