dubs-server 1.0.0

package/refactor/Chat.md

@@ -0,0 +1,252 @@
+# Chat System Refactor
+
+## Overview
+This document tracks the optimization work for the Dubs chat system across frontend and backend.
+
+**Date**: 2025-02-01
+**Status**: Complete - Ready for Production
+
+---
+
+## Architecture
+
+### Frontend (`dubs-jackpot-spa`)
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| `ChatWidget.tsx` | `app/v2/components/chat/` | Main orchestrator |
+| `MessageList.tsx` | same | Scrollable container with pagination |
+| `MessageRow.tsx` | same | Individual message with GIF onLoad |
+| `ChatInput.tsx` | same | Input + GIF picker |
+| `ChatContext.tsx` | `app/v2/contexts/` | State management + deduplication |
+| `chatSocket.ts` | `app/v2/services/` | Socket.io singleton |
+
+### Backend (`dubs-server`)
+
+| File | Purpose |
+|------|---------|
+| `server.js:4005-4758` | Socket.io `/chat` namespace handlers |
+| `services/chatService.js` | Database operations with cursor pagination |
+| `routes/chatRoutes.js` | HTTP endpoints with pagination support |
+| `services/notificationCacheService.js` | Redis caching layer |
+
+### Data Flow (Updated)
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                          FRONTEND                                 │
+├──────────────────────────────────────────────────────────────────┤
+│  ChatWidget                                                       │
+│    ├── ChatContext (state: messages[], pagination, dedup)        │
+│    │     ├── chatSocket.ts (singleton Socket.io client)          │
+│    │     └── useToast (rate limit errors)                        │
+│    ├── MessageList                                                │
+│    │     ├── "Load older messages" button (if hasMore)           │
+│    │     ├── Smart scroll (new msgs only, not load more)         │
+│    │     └── MessageRow × N                                       │
+│    │           └── <img onLoad={handleImageLoad}> (GIF scroll)   │
+│    └── ChatInput → sendMessage()                                 │
+└───────────────────────────┬──────────────────────────────────────┘
+                            │ Socket.io /chat namespace
+                            ▼
+┌──────────────────────────────────────────────────────────────────┐
+│                          BACKEND                                  │
+├──────────────────────────────────────────────────────────────────┤
+│  server.js                                                        │
+│    └── chatNamespace.on('send_message')                          │
+│          ├── Rate limit check (5/min) → "Woah, slow down 🤣"     │
+│          ├── chatService.addMessage() → PostgreSQL               │
+│          └── chatNamespace.emit('new_message') → ALL clients     │
+│                                                                   │
+│  GET /chat/messages?limit=20&before={id}                         │
+│    └── chatService.getRecentMessages(limit, userId, before)      │
+│          └── SELECT ... WHERE id < {before} LIMIT {limit+1}      │
+│          └── Returns { messages, hasMore, oldestId }             │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Issues Fixed
+
+### Issue #1: Scroll-to-Bottom with GIFs ✅
+
+**Problem**: GIFs load asynchronously, scroll happens before GIF height is known.
+
+**Solution**:
+- Added `onImageLoad` prop to MessageRow
+- GIF `<img>` has `onLoad={onImageLoad}` handler
+- MessageList checks if user is within 150px of bottom
+- If near bottom, scrolls after GIF loads
+
+---
+
+### Issue #2: Double/Triple Posting ✅
+
+**Problem**: Users see duplicate messages (2-3x of same message).
+
+**Solution**: Added deduplication in ChatContext:
+```javascript
+setMessages((prev) => {
+  if (prev.some(m => m.id === message.id)) {
+    console.log('[Chat] Duplicate message ignored:', message.id);
+    return prev;
+  }
+  return [...prev, message];
+});
+```
+
+---
+
+### Issue #3: Loading Too Many Messages ✅
+
+**Problem**: Always loaded 100 messages with no pagination.
+
+**Solution**:
+- Reduced initial load to 20 messages
+- Added cursor-based pagination (`before` param)
+- "Load older messages" button at top of chat
+- Smart scroll: only scrolls to bottom for new messages, not when loading older
+
+---
+
+### Issue #4: Rate Limit Error Not Shown ✅
+
+**Problem**: Users spam chat, get socket error but no UI feedback.
+
+**Solution**:
+- Added `useToast` hook to ChatContext
+- Listen for `chat:error` window events
+- Shows friendly toast: "Woah, slow down there 🤣"
+
+---
+
+## Files Modified
+
+| File | Repo | Changes |
+|------|------|---------|
+| `routes/chatRoutes.js` | dubs-server | `before` cursor, `hasMore`/`oldestId` response |
+| `services/chatService.js` | dubs-server | Cursor pagination in `getRecentMessages()` |
+| `server.js` | dubs-server | Friendly rate limit message |
+| `app/v2/contexts/ChatContext.tsx` | dubs-jackpot-spa | Pagination, deduplication, rate limit toast |
+| `app/v2/components/chat/MessageList.tsx` | dubs-jackpot-spa | Load more button, smart scroll, GIF handler |
+| `app/v2/components/chat/MessageRow.tsx` | dubs-jackpot-spa | `onImageLoad` prop for GIFs |
+| `app/v2/components/chat/ChatWidget.tsx` | dubs-jackpot-spa | Pagination props, auto-refresh on panel open |
+
+---
+
+## Deployment
+
+### Order: Backend First, Then Frontend
+
+**Why**: Backend changes are backwards compatible. Old frontend works with new backend.
+
+### Backend Deploy
+```bash
+cd ~/Developer/iheartsolana/solana-programs/dubs-server
+git add routes/chatRoutes.js services/chatService.js server.js refactor/
+git commit -m "Chat optimization: pagination, rate limit UX"
+git push
+# Deploy to production
+```
+
+### Verify Backend
+```bash
+curl https://api.dubs.gg/chat/messages?limit=5
+# Should return: { hasMore: true, oldestId: X, messages: [...] }
+```
+
+### Frontend Deploy
+```bash
+cd ~/Developer/iheartsolana/dubs-jackpot-spa
+git add app/v2/contexts/ChatContext.tsx app/v2/components/chat/
+git commit -m "Chat optimization: pagination, deduplication, GIF scroll, rate limit toast"
+git push
+# Deploy frontend
+```
+
+---
+
+## Backwards Compatibility
+
+**Backend**:
+- `before` parameter is optional - old clients work without it
+- New response fields (`hasMore`, `oldestId`) are additive
+- Old clients ignore new fields
+
+**Frontend**:
+- Has fallbacks: `data.hasMore ?? false`
+- Old v1 `DegenChat.tsx` still works (uses `limit=50`)
+- New v2 uses `limit=20` with pagination
+
+---
+
+## Rollback Plan
+
+| Scenario | Action |
+|----------|--------|
+| Frontend issues | Revert frontend commit - old frontend works with new backend |
+| Backend issues | Revert backend commit - new frontend has fallbacks |
+| Both | Revert both - system returns to previous state |
+
+---
+
+## Future Improvements
+
+- [ ] Virtual scrolling for very long chat histories
+- [ ] Preload GIF dimensions from GIPHY API metadata
+- [ ] Message search/filter
+- [ ] Lazy load game invite cards for old messages
+
+---
+
+## Additional Optimizations
+
+### React.memo for MessageRow ✅
+
+**Added memoization to prevent unnecessary re-renders:**
+
+**MessageRow** (`MessageRow.tsx`):
+```javascript
+export const MessageRow = memo(MessageRowComponent, (prevProps, nextProps) => {
+  return (
+    prevProps.message.id === nextProps.message.id &&
+    prevProps.message.edited === nextProps.message.edited &&
+    prevProps.message.reactions === nextProps.message.reactions &&
+    prevProps.isHighlighted === nextProps.isHighlighted
+  );
+});
+```
+
+**Note:** GameInviteCard is NOT memoized because it uses `useChat()` context internally for real-time game state updates. Memoizing components that depend heavily on context can cause stale data issues.
+
+**Impact:** With 20 messages, new message arrival goes from 20 component re-renders → 1 re-render.
+
+---
+
+### Auto-Refresh on Panel Open ✅
+
+**Problem**: Users had to manually pull-to-refresh or reconnect to see new messages when reopening chat.
+
+**Solution**: ChatWidget now watches `leadingPanel.isOpen` from ThreePanelLayout:
+
+```javascript
+// ChatWidget.tsx
+const { leadingPanel } = useLayout();
+const wasOpenRef = useRef(leadingPanel.isOpen);
+
+useEffect(() => {
+  // Only refresh when panel transitions from closed to open
+  if (leadingPanel.isOpen && !wasOpenRef.current) {
+    console.log('[Chat] Panel opened - refreshing messages');
+    refreshMessages();
+  }
+  wasOpenRef.current = leadingPanel.isOpen;
+}, [leadingPanel.isOpen, refreshMessages]);
+```
+
+**Behavior**:
+- When user taps chat FAB button to open chat panel
+- Chat automatically fetches fresh messages from API
+- Old messages are replaced with new ones
+- No manual refresh needed