sp3-test-1770368381/.sdlc/features/websocket-chat/design.md

WebSocket Chat - Technical Design

Architecture

Leverages the existing pkg/realtime package which provides:

• LocalHub: In-memory connection registry with room support
• WSClient: WebSocket connection with heartbeat (ping/pong)
• Handler: HTTP upgrade and connection lifecycle management
• RedisBroadcaster: Cross-pod message distribution via Redis Pub/Sub

Message Flow

Client → WebSocket → WSClient.readPump → Handler.OnMessage callback
  → RedisBroadcaster.Publish → Redis Pub/Sub channel
  → RedisBroadcaster.Run (subscriber) → LocalHub.Broadcast
  → WSClient.writePump → All connected WebSocket clients

Changes Required

1. Configuration (internal/config/config.go)

Add RedisURL field to Config struct, loaded from REDIS_URL environment variable.

2. Main Entry Point (cmd/server/main.go)

• Create Redis client from REDIS_URL
• Create LocalHub and start its event loop
• Create RedisBroadcaster and start its subscriber loop
• Pass hub and broadcaster to RegisterRoutes
• Register shutdown hooks for hub cancellation and Redis client cleanup

3. Route Registration (internal/api/routes.go)

• Accept realtime.Handler as a parameter
• Mount WebSocket handler routes at /api/chat-api/ws

4. OpenAPI Spec (internal/api/spec.go)

• Add WebSocket tag and endpoint documentation

5. Tests

• Unit test for WebSocket handler wiring
• Integration test for WebSocket connection upgrade and message echo

Dependencies

• pkg/realtime (already exists, no changes needed)
• github.com/redis/go-redis/v9 (already in pkg/go.mod)
• github.com/gorilla/websocket (already in pkg/go.mod)