websocket-architecture

Emit the event from the NestJS gateway using server.to(room).emit(), then register a listener on the React client inside an RTK Query onCacheEntryAdded hook. Always call socket.off(event, listener) after cacheEntryRemoved to prevent duplicate listeners.

The client passes the token via handshake auth as Bearer <token>, and the server reads client.handshake.auth.token in the gateway. A helper verifies it with JwtService and the app secret, extracting the userId or setting it to null if invalid.

Duplicate messages usually come from missing listener cleanup. Always pair socket.on with socket.off(event, listener) after await cacheEntryRemoved in RTK Query or in a useEffect cleanup, and use the shared socket singleton instead of creating new io() connections.

Use forwardRef(() => Module) on both module imports and forwardRef(() => Service) on both injected providers. In this app, ChatModule and NotificationModule reference each other and require forwardRef on both sides.

This codebase intentionally avoids React Context for sockets; the ScoketContext file is empty. Use the module-level singleton in utils/socket.ts via initializeSocket(), which returns the same socket instance across the app.