real-time-and-state

name	real-time-and-state
description	Work with Socket.IO collaboration and Zustand state in Zelaxy. Use for: socket token auth, workflow/workspace rooms, operation queue retries, presence/cursor sync, workflow rehydration, history middleware, and SSR-safe persisted stores.

Real-time and State Skill - Zelaxy

Purpose

Build, extend, and debug collaborative editing and execution streaming with Socket.IO plus Zustand across apps/zelaxy.

When to Use

• Adding or changing socket handlers, event payloads, or room behavior
• Building canvas collaboration features (blocks, edges, subblocks, variables)
• Fixing reconnect, auth, presence, or stale-state synchronization issues
• Modifying the operation queue, acknowledgement flow, or retry behavior
• Creating or refactoring Zustand stores and cross-store coordination

Read These Files First

• apps/zelaxy/socket-server/index.ts - Socket server bootstrap and middleware wiring
• apps/zelaxy/socket-server/config/socket.ts - Socket.IO transport/CORS/cookie config
• apps/zelaxy/socket-server/middleware/auth.ts - Better Auth one-time token verification
• apps/zelaxy/socket-server/middleware/permissions.ts - workflow/workspace permission checks
• apps/zelaxy/socket-server/handlers/*.ts - all real-time event handlers
• apps/zelaxy/socket-server/rooms/manager.ts - workflow room state and presence source of truth
• apps/zelaxy/socket-server/database/operations.ts - normalized table persistence for operations
• apps/zelaxy/socket-server/routes/http.ts - server-to-server notification endpoints
• apps/zelaxy/contexts/socket-context.tsx - client Socket.IO lifecycle + emit/listen API
• apps/zelaxy/hooks/use-collaborative-workflow.ts - local-first collaborative workflow behavior
• apps/zelaxy/stores/operation-queue/store.ts - sequential queue, retry, timeout, debounce
• apps/zelaxy/stores/workflows/workflow/store.ts - workflow graph state + history hooks
• apps/zelaxy/stores/workflows/middleware.ts - undo/redo with subblock snapshots
• apps/zelaxy/stores/workflows/registry/store.ts - workflow loading and workspace transition reset
• apps/zelaxy/stores/workflows/subblock/store.ts - per-workflow subblock value layer
• apps/zelaxy/stores/safe-storage.ts - SSR-safe persist storage fallback

Runtime Architecture

Socket Server

apps/zelaxy/socket-server runs as a dedicated process.

• Port: PORT || SOCKET_PORT || 3002
• Host: 0.0.0.0 by default
• Transports: websocket with polling fallback
• Auth: Better Auth one-time token from socket.handshake.auth.token
• CORS origins: NEXT_PUBLIC_APP_URL, NEXT_PUBLIC_VERCEL_URL, http://localhost:3000, plus ALLOWED_ORIGINS

Room Model

• Workflow room: collaborative canvas state and presence
• Workspace room: execution log streaming across workflows (workspace:<workspaceId>)
• One socket can only be in one workflow room at a time
• Presence list is authoritative via presence-update from RoomManager

Client Model

• SocketProvider creates a single client session socket
• One-time socket token is regenerated for every connection and reconnection attempt
• Workflow join is URL-driven (workflowId route param) and auto-rejoined after reconnect
• Workspace join is explicit for logs/execution listeners

End-to-End Operation Flow

UI action
  -> useCollaborativeWorkflow local update
  -> add operation to operation queue
  -> SocketContext emits operation with operationId
  -> server validates + authorizes + persists/broadcasts
  -> server emits operation-confirmed or operation-failed
  -> queue confirmOperation/failOperation updates reliability state

Important server behavior

• Position updates (update-position on block) are broadcast first, then persisted async for low latency.
• Most other operations are persisted first, then broadcast.
• Client operationId is used only for ack/fail semantics and queue reliability.

Event Contract Map

Primary collaboration events

• Client -> server: join-workflow, leave-workflow, request-sync
• Client -> server: workflow-operation, subblock-update, variable-update
• Client -> server: cursor-update, selection-update
• Client <- server: workflow-state, workflow-operation, subblock-update, variable-update
• Client <- server: operation-confirmed, operation-failed, operation-error, operation-forbidden
• Client <- server: presence-update, cursor-update, selection-update

External workflow lifecycle events (HTTP -> socket broadcast)

• workflow-deleted
• workflow-reverted
• workflow-updated
• copilot-workflow-edit

Execution streaming events

• execution:started
• execution:block-complete
• execution:complete

Server Handler Responsibilities

handlers/workflow.ts

• Handles join-workflow, access checks, room switch, presence updates, initial workflow-state
• Handles request-sync for explicit state refresh
• Handles leave-workflow

handlers/operations.ts

• Validates payload via WorkflowOperationSchema
• Checks permissions using verifyOperationPermission
• Persists/broadcasts operations and emits ack/fail
• Uses retryable flags for queue behavior on failures

handlers/subblocks.ts and handlers/variables.ts

• Persist subblock/variable updates in transactions
• Skip or fail gracefully when workflow/block/variable no longer exists
• Emit operation-confirmed or operation-failed when operationId is present

handlers/presence.ts

• Updates cursor/selection in room presence state
• Broadcasts deltas to other sockets in the room

handlers/workspace.ts

• Joins/leaves workspace-prefixed rooms for execution log streaming

Client Socket Context Patterns

contexts/socket-context.tsx

• Fetches one-time token from /api/auth/socket-token
• Uses auth: (cb) => ... to regenerate token for each connection attempt
• Maintains isConnected, isConnecting, currentWorkflowId, currentWorkspaceId, presenceUsers
• Throttles high-frequency emits:
  • block position updates batched at ~33ms
  • cursor emits throttled at ~33ms
• Handles rehydration flows:
  • workflow-state updates workflow + subblock stores
  • workflow-updated triggers request-sync
  • copilot-workflow-edit fetches fresh workflow from API and rehydrates stores

Collaborative Hook Rules

hooks/use-collaborative-workflow.ts

• Uses local-first updates for responsive UI
• Registers emitters into operation queue with registerEmitFunctions
• Uses isApplyingRemoteChange guard to prevent feedback loops
• Applies out-of-order protection for block position updates using server/client timestamps
• Skips socket emissions in diff mode (useWorkflowDiffStore().isShowingDiff)
• Handles queue acknowledgement through onOperationConfirmed and onOperationFailed

Zustand State Architecture

Core stores for collaboration

• workflow/store.ts: canonical in-memory graph (blocks, edges, loops, parallels) plus deployment flags
• workflows/middleware.ts: undo/redo history with subblock snapshot capture
• workflows/registry/store.ts: workflow metadata loading, active workflow, workspace transition reset guards
• workflows/subblock/store.ts: value layer keyed by workflow -> block -> subblock
• panel/variables/store.ts: workflow variable map and reference update logic
• operation-queue/store.ts: FIFO processing, timeout, retries, debounced updates, offline failover

Queue semantics (operation-queue/store.ts)

• Sequential FIFO processing (single in-flight operation)
• Debounce windows:
  • subblock updates: 25ms keyed by blockId-subblockId
  • variable updates: 25ms keyed by variableId-field
• Timeout: 5s per in-flight operation
• Retry policy: exponential backoff (2s, 4s, 8s), max 3 retries
• On terminal failure: triggerOfflineMode() clears queue and sets hasOperationError
• Supports targeted cancellation for block/variable scoped operations

Workflow history semantics

• History present/past/future snapshots include subblock values
• Undo/redo restores both graph state and subblock store values
• Sync control methods are intentionally no-ops in socket-first architecture

SSR-safe persistence

• Use createSafeStorage() in persisted stores
• Falls back to no-op storage when window.localStorage is unavailable
• Prevents server-side storage.setItem crashes in non-browser runtimes

Implementation Rules

When adding or changing collaboration operations

1. Update validation schema in socket-server/validation/schemas.ts if payload shape changes.
2. Update server persistence logic in socket-server/database/operations.ts.
3. Update relevant handlers in socket-server/handlers.
4. Update client emit and listener logic in contexts/socket-context.tsx.
5. Update queue routing logic in stores/operation-queue/store.ts if target/type changed.
6. Update collaborative hook logic in hooks/use-collaborative-workflow.ts.

When adding or changing stores

1. Keep one clear domain per store.
2. Prefer selectors over full-store subscriptions in React components.
3. Use OtherStore.getState() for non-reactive cross-store reads to avoid circular render coupling.
4. Add explicit reset logic when switching workspace/user context.

Mandatory Sync for User-Facing Changes

Any user-visible collaboration or state behavior change must include sync updates in the same task unless explicitly waived by the user:

1. Update affected tests (queue behavior, handler behavior, workflow synchronization).
2. Update documentation when event names, payloads, permissions, or UX behavior change.
3. Update changelog/release notes when real-time behavior changes materially.

Debug Checklist

1. Confirm token generation endpoint works: /api/auth/socket-token.
2. Confirm socket auth middleware accepts token and attaches user context.
3. Confirm correct room membership (join-workflow or join-workspace).
4. Check for operation-failed vs operation-forbidden vs operation-error event type.
5. Validate queue state: pending/processing counts, timeout/retry activity.
6. Verify workflow sync path (request-sync, workflow-state, copilot-workflow-edit).
7. Check permission role behavior (admin, write, read) for target operation.

Common Pitfalls

1. Emitting events without currentWorkflowId causes silent no-op on client.
2. Forgetting operationId breaks queue acknowledgement and retry handling.
3. Skipping schema updates when payloads change causes Zod validation failures.
4. Updating workflow graph without subblock synchronization causes stale field values.
5. Treating user-joined/user-left as primary presence source instead of presence-update.
6. Using persisted storage directly in server contexts instead of createSafeStorage().