PSA/ee/docs/plans/2026-05-07-live-ticket-updates/PRD.md

PRD — Live Ticket Updates

• Slug: live-ticket-updates
• Date: 2026-05-07
• Status: Draft
• Scope: Phases 1–3, tickets only (projects port deferred to a follow-up plan)

Summary

Add a real-time layer to the ticket detail page so that when one user saves a change, every other user viewing the same ticket sees it within ~500 ms — without requiring a refresh and without breaking when Hocuspocus is unavailable. Postgres remains the source of truth; Hocuspocus carries presence and lightweight "something changed" signals; the existing REST-based save model is unchanged.

Problem

Today, two users editing the same ticket cannot tell that the other is there, and a save by user B does not reach user A's screen until A reloads. The save flow already has good bones — optimistic per-field updates, a pendingRequestRef queue, and UnsavedChangesProvider — but no awareness of remote activity. The result is two visible failure modes:

1. Stale reads: A is looking at a ticket whose status was changed 10 minutes ago by B; A makes decisions on stale data.
2. Lost-update-style overwrites at the field level: A and B both change the same dropdown around the same time. The second save wins silently. Cross-entity validation in updateTicketWithCache (priority recompute, status↔board, etc.) means even non-overlapping fields can produce surprising server state.

Goals

• A second user's save shows up on my screen for the ticket I'm viewing without a manual refresh, within ~500 ms of the save committing.
• I can see who else is currently viewing this ticket (presence bar) and which structured field they are actively editing (focus indicator).
• If two users edit the same field and remote save lands while I have unsaved local changes for that field, I get an explicit Keep yours / Take theirs banner — no silent overwrite.
• If Hocuspocus is unreachable, the ticket page works exactly as it does today: reads, writes, optimistic updates, unsaved-changes warning all unchanged. The user sees a small "Live updates offline — reconnecting…" indicator; the live layer auto-reconnects in the background.
• The implementation reuses the existing Hocuspocus pipe and the Redis pub/sub bridge pattern from NotificationExtension, so we are not introducing new infrastructure.

Non-goals

• Collaborative editing of structured fields (no Y.Map of ticket fields). Postgres stays authoritative; we are not migrating the save path.
• Live updates for the rich-text description field — already handled by the existing CollaborativeEditor Y.js pipeline; we will not touch it.
• Live updates for comments, tags, resources, teams, time entries as separate channels in this plan. They will fold in later as additional invalidation signals on the same ticket room, but Phase 1–3 scope is the structured fields handled by updateTicketWithCache.
• Live updates for projects. Same architecture later (separate plan), not now.
• Hard locks on fields. The "X is editing" indicator is advisory only.
• Background polling fallback. If Hocuspocus is down, we degrade — we do not periodically refetch via REST as a backstop.
• Operational tooling beyond what's needed to verify the feature (no dashboards, no metrics pipelines, no admin UI).

Users and Primary Flows

Personas: MSP technicians and dispatchers viewing tickets concurrently. The most common collisions are around status, priority, assigned_to, and board.

Primary flows:

1. Two users on one ticket, no conflict. A and B both have the ticket open. B changes status from "New" to "In Progress". A's status field updates silently within ~500 ms. A toast does not appear; the field is briefly highlighted.
2. Presence. A opens the ticket; sees a stack of avatars in the header showing B is viewing. B closes the tab; A's avatar list shrinks within a few seconds.
3. Focus indicator. A focuses the priority dropdown. On B's screen, the priority field is dimmed with a subtle "Alex is editing" caption. A blurs without changing — the indicator clears on B's screen.
4. Same-field conflict. A opens the status dropdown and selects "On Hold" but has not yet committed. Meanwhile B saves status = "Resolved". A's local state still has "On Hold" pending. The field freezes, a banner appears: "Bob just changed status to Resolved (2 sec ago). [Keep yours] [Take theirs]". A clicks Keep yours → A's pending value is sent on next save and may overwrite B; A clicks Take theirs → A's local pending value is dropped, "Resolved" is shown.
5. Hocuspocus down. Server is unreachable. A sees "Live updates offline — reconnecting…" indicator in the header. All saves and reads work normally. When the server comes back, the indicator disappears and the room rejoins.
6. Reconnect. A's connection drops mid-session and reconnects after 30 s. On reconnect, the client refetches the ticket once to catch any updates that landed during the gap.

UX / UI Notes

• Presence bar: lift the existing presence component out of packages/documents/src/components/CollaborativeEditor.tsx into packages/ui so tickets and (later) other entities share one component. Avatars + tooltip with name; visible in the ticket detail header next to the title.
• Field focus indicator: visual differs by control type — dropdowns dim with a caption beneath; text inputs (title) show a small caption pill next to the control without dimming. No hard lock in either case — A can still focus the same field; we only show who else is.
• Silent remote update: the changed field briefly highlights (~600 ms fade) when a remote update is applied. No toast unless the change touches data the user was looking at but hadn't saved.
• Conflict banner: appears inside the field's container, not as a global toast. Two buttons: Keep yours (default focus), Take theirs. Shows author name + relative timestamp.
• Connection status: small text indicator in the header. Three states: connected (no indicator), reconnecting ("Live updates offline — reconnecting…"), permanent failure ("Live updates unavailable" — after N retries, no further auto-retry that session).
• Multi-tab same user: presence dedupes by userId, so A in two tabs shows once.

Requirements

Functional Requirements

FR-1. Server-side broadcast on ticket update. After updateTicketWithCache commits successfully and publishes its existing TICKET_UPDATED event, also publish a Redis message on channel ticket-updates:<tenantId>:<ticketId> with payload {updatedFields: string[], updatedBy: {userId, displayName}, updatedAt: ISO8601}. This must run in the same code path as the existing event publish (packages/tickets/src/actions/optimizedTicketActions.ts ~L2038–2101) so no save can succeed without the broadcast attempt. Broadcast failure is logged but does not fail the update.

FR-2. Hocuspocus extension bridges Redis to room broadcasts. A new TicketUpdatesExtension (modeled on NotificationExtension) subscribes to ticket-updates:*. When a message arrives for ticket-updates:<tenant>:<id>, it broadcasts a stateless message to all clients connected to room ticket:<tenant>:<id>.

FR-3. Per-ticket Hocuspocus room. tenantValidation.js recognizes the ticket: room prefix in addition to document: and notifications:. Authentication is via short-lived signed JWT (see Security).

FR-4. Client subscription on ticket open. When a user opens a ticket detail page, the client joins room ticket:<tenant>:<id> using createYjsProvider. The provider is empty Y.Doc — used only for awareness and stateless messages, not for field state.

FR-5. Presence. Awareness state holds {userId, displayName, avatarUrl, color, editingField?: string}. Presence bar renders all unique users (deduped by userId).

FR-6. Silent refetch on remote update with no local conflict. When the client receives an update message:

• If the user has no pending local edits to any field in updatedFields, refetch the ticket and update component state. Briefly highlight changed fields. No toast.
• Debounce refetches at 200 ms so a burst of changes triggers a single refetch.

FR-7. Conflict banner on same-field collision. When the client receives an update message that includes a field with pending unsaved local state:

• Freeze that specific field.
• Render a banner in the field's container with author + timestamp + remote value.
• Keep yours: keeps local pending value; clears banner; user proceeds normally.
• Take theirs: drops local pending value; refetches; field updates to remote value.

FR-8. Toast on remote update with non-overlapping unsaved local changes. If the user has unsaved changes on field X and a remote update lands on field Y:

• Refetch and update Y silently.
• Show a passing toast: "{Name} updated {field}".
• Local pending changes on X are preserved untouched.

FR-9. Per-field editing indicator. When the user focuses an editable field (title, status, priority, ITIL impact, ITIL urgency, board, category, assignee, client, contact, location), set awareness.editingField = '<field>'. On blur or selection-commit, clear it. On other clients, render a "{Name} is editing" indicator on that field when at least one remote awareness has the same editingField. Visual treatment is per control type:

• Dropdowns/selects: dim the control + caption beneath.
• Text inputs (title): caption pill near the control; do not dim (would interfere with the input affordance).
• No hard lock in either case.

FR-10. Soft dependency on Hocuspocus. All live behavior is layered over the existing REST save path. If the WebSocket fails to connect or disconnects:

• Presence, focus indicator, silent refetch, conflict banner all become no-ops.
• The ticket page renders, reads, writes, optimistic updates, and unsaved-changes warnings exactly as today.
• A header indicator shows "Live updates offline — reconnecting…". Reconnects auto-retry with exponential backoff (start 1 s, cap 30 s). After 5 failed reconnects, switch to "Live updates unavailable" and stop auto-retrying that session (manual reload re-enables).

FR-11. On reconnect, refetch once. When the WebSocket reconnects after a drop, the client refetches the ticket exactly once to catch up on any updates that landed during the gap.

FR-12. Multi-tab dedupe. A single user with the same ticket open in multiple tabs appears once in the presence bar (deduped by userId).

FR-13. Permission revocation mid-session. If the server pushes a message indicating the current user no longer has access (e.g., ticket reassigned to a board they can't see), the client redirects away (or shows a "no access" view) instead of silently 403'ing on the next refetch. (Implementation note: refetch failure with 403 is the trigger; we do not need a separate channel for this in Phase 1–3.)

Non-functional Requirements

• Latency: P95 from save commit to all subscribed clients applying the update ≤ 500 ms on the same data center.
• Throughput: Phase 1–3 design target — up to 50 concurrent viewers per ticket and up to 100 ticket updates / sec / tenant. No formal load test in scope; just don't pick designs that obviously break here.
• Auth: per-ticket JWT, ≤ 5 min expiry, signed with the existing Hocuspocus shared secret. Tenant + ticketId + userId encoded in claims.
• Backward compatibility: zero changes required to existing ticket UI for users on the live layer to see fresh data. A user with Hocuspocus disabled in their environment sees the same UX as today plus the offline indicator.

Data / API / Integrations

Server (Next.js / @alga-psa/tickets):

• New helper publishTicketUpdate({tenantId, ticketId, updatedFields, updatedBy, updatedAt}) in packages/tickets/src/lib/liveUpdates.ts. Uses getRedisClient() from @alga-psa/event-bus.
• Call publishTicketUpdate in updateTicketWithCache (packages/tickets/src/actions/optimizedTicketActions.ts ~L2038–2101 region) after successful commit, alongside the existing publishEvent('TICKET_UPDATED', …) call. Compute updatedFields from the diff between the loaded ticket and the validated update payload (same diff already used implicitly for ITIL recompute / status↔board logic — extract the diff into a helper).
• New endpoint GET /api/tickets/:id/live-token returns a short-lived JWT {tenantId, userId, ticketId, exp}. Wrapped in withAuth; checks assertTicketReadAllowed. Token signed with HOCUSPOCUS_JWT_SECRET (new env var; reuse existing Hocuspocus shared secret if one exists).

Hocuspocus (/hocuspocus):

• New TicketUpdatesExtension.js modeled on NotificationExtension.js. Subscribes to <redisPrefix>ticket-updates:* (pattern subscribe). On message, looks up matching room and broadcasts a stateless message via Hocuspocus' sendStateless API (or sets a transient awareness key the clients listen for).
• Extend tenantValidation.js:
  • Add parseTicketRoom(roomName) for ticket:<tenant>:<ticketId>.
  • Update validateDocumentRoomAccess to handle the ticket: prefix: parse, then verify the JWT in the request (query param token=<jwt>); reject if signature, expiry, tenant, or ticketId mismatch.
• Register TicketUpdatesExtension in server.js extensions list.

Client (@alga-psa/tickets):

• New packages/tickets/src/hooks/useTicketLive.ts: takes {tenantId, ticketId, currentUser, onRemoteUpdate, onPresenceChange}. Internally fetches the live-token, calls createYjsProvider('ticket:<tenant>:<id>', { token }), exposes presence, connectionStatus, setEditingField(field|null). Handles reconnect-then-refetch (FR-11).
• New packages/tickets/src/components/ticket/TicketLiveProvider.tsx: wraps TicketDetails, owns the hook, exposes context.
• Modify packages/tickets/src/components/ticket/TicketDetails.tsx (~L94–171, L870–924):
  • Subscribe to onRemoteUpdate from context.
  • Intersect updatedFields with the current pendingRequestRef queue and component-level dirty state to route to silent refetch / toast / conflict banner.
  • Wire setEditingField on focus/blur of structured field controls.
• Lift presence bar from packages/documents/src/components/CollaborativeEditor.tsx (~L259–305) into packages/ui/src/presence/PresenceBar.tsx. Update CollaborativeEditor to import from there. Tickets imports the same component.
• Conflict banner component: packages/ui/src/presence/FieldConflictBanner.tsx. Used wherever a structured field needs the banner.

Wire format:

• Redis channel: <redisPrefix>ticket-updates:<tenantId>:<ticketId>.
• Redis payload (JSON): { updatedFields: string[], updatedBy: { userId: string, displayName: string }, updatedAt: string /* ISO */ }.
• Hocuspocus stateless message payload from extension to clients: same JSON.
• Awareness shape: { userId, displayName, avatarUrl?, color, editingField?: string }.

Security / Permissions

• Per-ticket auth. tenantValidation.js currently only validates that the room's tenant matches the request's tenant. For tickets we additionally require:
  1. Client requests a JWT from /api/tickets/:id/live-token. Endpoint runs withAuth → assertTicketReadAllowed(user, ticketId) (must check both tenant and ticket-level visibility — bundled-child sync locks, board visibility, client-portal restrictions).
  2. JWT is short-lived (≤ 5 min) and includes {tenantId, userId, ticketId, exp, iat, jti}.
  3. Hocuspocus onAuthenticate (or equivalent in validateDocumentRoomAccess) verifies the JWT, asserts tenantId === room.tenantId and ticketId === room.ticketId.
• Token refresh. Client refreshes the token automatically before expiry (e.g., at 80 % of TTL). Refresh failure → degrade as if Hocuspocus were down.
• Cross-tenant probe. A direct WebSocket connection with a token for tenant X attempting to join ticket:Y:* MUST be rejected by tenantValidation.js.
• No PII in awareness. Awareness fields limited to userId, display name, avatar URL, color. No emails, no permissions snapshots.
• No payload data on the wire. The Redis message and the broadcast carry only updatedFields (field names) and metadata. Clients refetch the ticket via the existing authenticated REST path to obtain values. This means access changes are enforced on every refetch — a user whose access was just revoked will see 403 from the refetch and trigger FR-13.
• JWT signing key. New env var HOCUSPOCUS_JWT_SECRET (or reuse existing Hocuspocus secret if it covers signing). Stored in secrets/. Required in production; in dev, fall back to a fixed dev key with a startup warning.

Observability

Out of scope for this plan beyond what's necessary to verify behavior in development:

• Console logging in TicketUpdatesExtension matching the pattern in NotificationExtension (subscribe/unsubscribe, message receipt) — useful for docker compose logs hocuspocus during dev.
• Console logging on the client when reconnect attempts happen.

If formal metrics are required they will be added in a follow-up plan.

Rollout / Migration

• Feature flag. Gate the live layer behind a PostHog feature flag live-ticket-updates (per project conventions in alga-feature-flags). Off by default. Roll out tenant-by-tenant.
• Backwards compatible. No DB migrations. No schema changes. Existing REST flow is untouched — the new code is purely additive.
• Backout. Disable the flag → all clients revert to today's behavior (REST only, no presence). The Redis publishes still happen but go nowhere; no harm. Optional kill-switch via env var on the server side to skip the publish entirely.

Implementation / Commit Cadence

Tests are listed at fine granularity in tests.json for tracking, but they MUST NOT be committed one-test-per-commit. Bundle commits by feature group within a phase. Specifically:

• Phase 1 commits (target: 3–4 commits total):
  1. Server publish: F001 + F002 + F003 + F004 + F033 (Redis publish helper, diff helper, wire into updateTicketWithCache, bundled-child propagation, env kill-switch). Tests T001–T007 ship in the same commit as the code they cover.
  2. Hocuspocus extension + auth: F005 + F006 + F007 + F008 + F009 + F010. Tests T008–T021 ship in this commit.
  3. Client subscription + silent refetch + offline UX: F011 + F013 + F014 + F015 + F016 + F017 + F018 + F019 + F020 + F021 + F022 + F023 + F024 + F025 + F031 + F032. Tests T022–T036, T044–T046, T051–T056 ship here. (PresenceBar lift in F011 is allowed to be its own commit if the documents-package regression test T024 wants isolation; otherwise fold in.)
• Phase 2 commits (target: 1–2 commits): F029 + F030 + F034 + the editing-indicator wiring, with T040–T043, T048, T058 in the same commits.
• Phase 3 commits (target: 1–2 commits): F012 + F026 + F027 + F028 + the conflict-banner integration, with T037–T039, T049 in the same commits.
• Cross-phase E2E (T046, T047, T049, T050, T051, T052, T053, T059) ship in the commit that completes the relevant phase, not split across many.

Rule of thumb: a commit should leave main in a green state where the implemented features + their tests are both present. Do not split "code" and "tests" commits — they are reviewed together.

Open Questions

1. Editing-indicator field set. Resolved 2026-05-07: title, status, priority, ITIL impact, ITIL urgency, board, category, assignee, client, contact, location. Title uses caption-pill variant; rest use dim+caption.
2. Bundled child tickets. When a parent ticket sync-propagates to children (optimizedTicketActions.ts L2124–2143), should the child rooms also receive a broadcast? Probably yes; deferred to Phase 1 implementation note.
3. Conflict-banner persistence. If the user dismisses a banner with Keep yours and then B saves the same field again, do we re-show the banner (probably yes) and is it cumulative? Decide during Phase 3 design.
4. JWT secret. Reuse Hocuspocus' existing shared secret or introduce a separate one? Defer to security review.

Acceptance Criteria (Definition of Done)

Phase 1 — Server publish + silent client refetch (no presence, no conflict UI yet):

• Two browsers, two users, one ticket: B saves status → A sees status update without reload within ~500 ms; A's other unsaved fields are preserved.
• B saves while Hocuspocus is down: A does not get the live update; A's reads/writes still work; A sees offline indicator.
• Cross-tenant probe: a user from tenant X with valid token-for-X cannot join ticket:Y:* (verified via direct WS probe in test).

Phase 2 — Presence + per-field editing indicator:

• Two users open the same ticket: each sees the other in the presence bar within ~2 s.
• A focuses status; B sees "Alex is editing" indicator on the status field. A blurs; indicator clears on B's screen.
• A and B both focused on status simultaneously: each sees the other's indicator (no hard lock).
• One user open in two tabs: presence shows once, not twice.

Phase 3 — Conflict banner:

• A has unsaved status change pending. B saves a different status. A sees the banner with B's value + author + timestamp; the field is frozen until A clicks Keep yours or Take theirs.
• A has unsaved change on field X; B saves field Y. A sees a passing toast; A's pending change on X is preserved; Y is silently updated.
• Banner Keep yours: A's local pending value remains; A's next save sends it; banner clears.
• Banner Take theirs: A's local pending is dropped; field reflects B's value; banner clears.

Always (regression guards):

• Hocuspocus container killed: ticket page renders, all reads/writes via REST work, optimistic updates and unsaved-changes warning all behave as today; offline indicator shown.
• Hocuspocus restarts: client reconnects within ~30 s, indicator disappears, refetches once on reconnect.
• All existing ticket-related tests pass unchanged.