MCintelligentplus DocsReal-Time Sync
How MCintelligentplus pushes live updates to every open tab with SSE and Redis Pub/Sub
Real-Time Sync
Real-time sync is what makes MCintelligentplus feel live: a document finishes indexing, a teammate comments on an answer, an automation run advances a step — and every open tab updates without a refresh. The transport is Server-Sent Events (SSE) backed by Redis Pub/Sub and React Query on the client.
This is the canonical reference for the feature; the how-to guide covers the operational checks.
Architecture
- A backend service (FastAPI route or Celery task) commits to PostgreSQL and
publishes an event to a Redis channel (
sse:<user_id>, org-scoped where applicable). - The SSE broker inside the backend process receives the Redis message.
- Each browser's persistent
EventSourceon/api/v1/sse/eventsreceives the pushed event. - React Query caches update — no polling, no page refresh.
| Component | Role |
|---|---|
| PostgreSQL | Source of truth |
| Redis | Pub/Sub bus (channel per user; org-scoped delivery) |
| Backend (FastAPI SSE) | Subscribes and streams events to browsers |
| Browser | Persistent EventSource + React Query invalidation |
The previous zero-cache WebSocket (/zero) was removed in favour of this
design (S1: remove the zero-cache SPOF, PR #495); deployments should no longer
see any client requesting /zero.
Synced entities
| Entity | Used by |
|---|---|
notifications | Inbox (comments, document processing, connector status) |
documents | Document list, processing status |
folders | Nested folder tree |
search_source_connectors | Connector status, indexing progress |
new_chat_messages | Live message sync for shared chats |
chat_comments | Real-time comment threads on AI responses |
chat_session_state | Collaboration indicators (who is typing) |
automation_runs | Live run status and per-step progress |
Configuration
| Env var | Default | What it does |
|---|---|---|
REDIS_URL | redis://localhost:6379/0 | Redis connection reused by SSE, Celery, and caching |
SURFSENSE_SSE_KEEPALIVE_INTERVAL_SECONDS | 15.0 | Idle interval after which a : keep-alive comment is sent so reverse proxies don't close silent streams (0 disables) |
The endpoint /api/v1/sse/events is served by the backend container and routed
through the same reverse proxy as the rest of the API. Streams resolve auth in a
short-lived session so a stream never holds a database connection open.
Troubleshooting
See How-to → Real-Time Sync for the DevTools checklist, Redis health checks, and known failure modes.
Related PRs
- #495 — S1: remove the zero-cache SPOF, replace with SSE + Redis + React Query
- #589 — org-scoped SSE delivery
- #1091 / #1038 — resolve SSE auth in a short-lived session (#1027)
- #1088 — SSE turn-stream keep-alive (#943)
- #1054 — traceback logging when pre-stream dependency resolution fails (#1047)
- #10 — original SSE heartbeat during deliverable waits