feat: realtime work-item updates over the live server (auto-refresh boards/lists)

[Liewzheng]

Description

Work-item views (kanban/list/calendar/gantt/spreadsheet) are fetch-on-mount today: when a teammate drags a card, edits an item, or a CI bot changes state through the v1 API, everyone else's screen stays stale until a manual reload. This PR adds realtime work-item updates by reusing the live (collaboration) server that already ships with CE for pages — no new realtime stack.

Flow: API write → issue_activity celery task → POST /broadcasts/issue-events (shared key) → live server relays to issue-events:<project_id> over Redis → subscribed web clients soft-refetch with existing pagination.

API (apps/api):

• New plane/utils/issue_events.py: fire-and-forget broadcast_issue_event() — POSTs {project_id, issue_id, type, actor_id} (metadata only, no work-item data) to the live server with an x-internal-api-key header, 2s timeout, failure logs a warning and never breaks the request/task.
• Emitted from the single choke point issue_activity task, which covers detail edits, drag & drop (state/sort), creation, deletion, archiving, cycle/module membership, links/attachments/relations and API-token-driven changes. BulkDeleteIssuesEndpoint (which bypasses activity logging) emits explicitly.
• Disabled unless LIVE_INTERNAL_API_KEY is set (new optional env, empty by default → zero behavior change).

Live server (apps/live):

• New POST /broadcasts/issue-events controller: shared-key auth (401/400 on bad requests), relays the payload with the existing Redis extension's broadcastToDocument (multi-instance safe).
• database and title-sync extensions guard the ephemeral issue-events: document namespace (no page fetches/writes for these channels).

Web (apps/web):

• New useIssueRealtime(projectId, onEvent) hook: HocuspocusProvider subscribed to the project channel (same URL construction and cookie auth as the page editor), parses stateless events, ignores events caused by the current user, debounces bursts (500ms), then calls fetchIssuesWithExistingPagination — a background soft refresh with no loader flash.
• Mounted once in project-layout-root, covering all five project work-item layouts.

Type of Change

• Feature (non-breaking change which adds functionality)

Test Scenarios

• check:types passes for live and web; lint/format clean; py_compile on changed API modules.
• Verified end-to-end on a self-hosted CE deployment (api + live + web rebuilt): with a project board open in Chrome, changing a work item's state through the public v1 API (separate bot credential) updated the open page's group counts and card placement within ~1s, no reload. Live server logs show Published to issue-events:<project>, 1 subscribers; endpoint returns 401 without / 200 with the shared key.
• With LIVE_INTERNAL_API_KEY unset (default), the broadcast path is fully inert.

References

• Closes [feature]: Realtime work-item updates over the live server (auto-refresh boards/lists without manual reload) #9779

[coldtea-pr-lens]

◈ PR Lens

🟢 +2 new · 🟠 ~8 changed · 🔴 -0 removed · 1 flow · 14 files · commit 11aad69

Architecture

10 components touched across 4 lanes.

Open the interactive canvas

Inside the changed components — 2 views

Component view — Live collaboration server broadcast pipeline

The internal controller, Redis pub/sub dispatcher, and extension overrides handling ephemeral issue events.

Component view — Web client realtime subscription

The React layout integration and Hocuspocus provider hook that listens for remote issue mutations.

Data flow

Broadcasting and receiving realtime issue updates

Open the interactive canvas

Drill down

Client Applications — 3 components

🟡 CHANGED Plane Web App

Next.js frontend application that renders project issue views and subscribes to realtime issue updates.

• apps/web/package.json:28
• apps/web/core/hooks/use-issue-realtime.ts:1-102
• apps/web/core/components/issues/issue-layouts/roots/project-layout-root.tsx:57-62

🟡 CHANGED Project Layout Root

Main container component for project issue views that triggers pagination-preserving refetches when issue events arrive.

• apps/web/core/components/issues/issue-layouts/roots/project-layout-root.tsx:53-65

🟢 NEW useIssueRealtime Hook

React hook that maintains a Hocuspocus WebSocket connection to ephemeral project event channels and debounces incoming notifications.

• apps/web/core/hooks/use-issue-realtime.ts:34-102

Application Services — 6 components

🟡 CHANGED Django REST API Server

Core API backend configured with internal API keys for authenticating broadcast requests to the live server.

• apps/api/.env.example:65-71
• apps/api/plane/settings/common.py:418-423
• apps/api/plane/utils/issue_events.py:1-44

🟡 CHANGED Core Domain API (plane.app)

Application views including bulk issue deletion endpoints that broadcast deletion events directly to the live server.

• apps/api/plane/app/views/issue/base.py:790-802

🟡 CHANGED Live Collaboration Server

Node.js Hocuspocus server relaying document collaboration and ephemeral issue event broadcasts across connected clients.

• apps/live/.env.example:8-14
• apps/live/src/env.ts:24-28
• apps/live/src/controllers/broadcast.controller.ts:1-85
• apps/live/src/controllers/index.ts:7-19

🟢 NEW Broadcast Controller

Express controller exposing authenticated HTTP endpoints to receive issue change events and publish them to Redis.

• apps/live/src/controllers/broadcast.controller.ts:25-85
• apps/live/src/controllers/index.ts:12-19

🟡 CHANGED Hocuspocus DB Extension

Database storage extension updated to treat issue-events documents as ephemeral channels without database queries.

• apps/live/src/extensions/database.ts:27-88

🟡 CHANGED Title Sync Extension

Title synchronization extension updated to bypass title migration and observation for issue-events documents.

• apps/live/src/extensions/title-sync.ts:30-86

Background Workers — 1 component

🟡 CHANGED Celery Background Worker

Asynchronous task worker running issue_activity tasks that dispatch live broadcast notifications on issue changes.

• apps/api/plane/bgtasks/issue_activities_task.py:1525-1536

View

• Architecture lens
• Data flow lens
• Expand every detail
• Show unchanged neighbours

Tip

Draw a diff before it is even a pull request: npx @coldtea/pr-lens-cli analyze --base origin/main reads the diff with your own model key, and npx @coldtea/pr-lens-cli render .pr-lens/graph.json draws the same lenses on your machine.

🪧 More tips

• Run PR Lens on your own machine: npx skills add coldteadotai/pr-lens installs the agent skill. Then tell your coding agent: "Diagram the change you just made with PR Lens and attach it to the pull request."
• The boxes under View are live. Tick Architecture lens or Data flow lens to choose which diagrams appear, or Expand every detail to open every drill-down at once. The comment redraws in place a few seconds later.
• Show unchanged neighbours lists the components this change did not touch alongside the ones it did, so the drill-down shows what the changed code sits next to.
• GitHub will not let you zoom an image in a comment. The link under each diagram opens it on an interactive canvas, where you can zoom, pan and step through the flow.
• The CLI's render picks up .github/pr-lens.yml automatically and applies your corrections (renames, exclusions, lane pins) at draw time.
• Would you rather run it from CI on a key of your own? Add .github/workflows/pr-lens.yml with coldteadotai/pr-lens/packages/action@v0 and a model key in your repository secrets, say GEMINI_API_KEY. The Action asks Gemini by default, or OpenAI and any endpoint speaking /chat/completions through its provider input.
• PR Lens is free for open source. A star on the repository is what keeps it going.
• Push a new commit and the whole comment re-renders for the new head. An older run never overwrites a newer one, so a slow render cannot put a stale diagram back.
• The diagrams follow your GitHub theme, so dark mode gets the dark render and light mode the light one, and the moving dots show this pull request's data in motion.

---

◈ Rendered by PR Lens · crafted with ❤️ by the Coldtea team · Come say hi on Discord

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 07568b73-51a9-45d6-a6f1-4e02dc0dbb63

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}