B-4: WebSocket gateway for real-time escrow updates

[KuchiMercy]

Summary

All escrow state changes currently require polling to detect. A WebSocket gateway will enable real-time push notifications to connected clients, improving UX for all parties involved in an escrow.

Requirements

• Implement a NestJS WebSocket gateway using @nestjs/websockets with Socket.IO
• Authenticate WebSocket connections using the existing JWT system (token passed on handshake)
• Create rooms per escrow ID so only relevant parties receive updates
• Broadcast events on all escrow state transitions:
  • escrow:status_changed — status transitions
  • escrow:milestone_released — fund release events
  • escrow:dispute_filed — new disputes
  • escrow:dispute_resolved — resolution outcomes
  • escrow:party_joined — new party acceptance
  • notification:new — in-app notifications
• Emit events from the escrow service (or via NestJS EventEmitter) on every state change
• Handle connection/disconnection gracefully with proper cleanup
• Support reconnection with missed event replay (last event ID)

Acceptance Criteria

• WebSocket gateway accepts authenticated connections
• Unauthenticated connections are rejected
• Clients can subscribe to specific escrow rooms
• All listed event types are broadcast in real-time
• Disconnected clients are cleaned up from rooms
• Gateway handles concurrent connections (100+ without degradation)
• Integration test verifies event broadcast on escrow state change

Context

• NestJS supports @nestjs/platform-socket.io for WebSocket
• Auth guard: apps/backend/src/modules/auth/middleware/auth.guard.ts
• Escrow service emits events to: apps/backend/src/modules/escrow/entities/escrow-event.entity.ts
• Frontend will consume via Socket.IO client (F-6 notification center)

Rollout Phase

Phase 3 — Real-time & Disputes

Points: 200 (Difficult)