docs: add persistent chat widget implementation plan

- Database schema with ChatConversation + ChatMessage models - Transition contract for backward-compatible chat API - Redis lifecycle mapping and rehydration strategy - Security test matrix and performance SLOs - Rate limiting and failure mode specifications - 3-phase implementation (backend → service → UI) - Estimated timeline: 5 weeks
1 month ago · 7e0172efa6
1 changed files with 601 additions and 0 deletions
--- a/thoughts/shared/plans/persistent-chat-widget-history.md
+++ b/thoughts/shared/plans/persistent-chat-widget-history.md
@ -0,0 +1,601 @@
 # Persistent Chat Widget with History Sidebar - Implementation Plan
 ## Problem Statement
 Current AI chat implementation loses conversation history on page refresh and is only accessible from the portfolio/analysis page. Users need:
 1. Persistent conversation history across sessions
 2. Ability to switch between past conversations
 3. Global access from any page (floating widget)
 4. Similar UX to OpenAI's ChatGPT interface
 ## Current Architecture
 **Frontend:** `apps/client/src/app/pages/portfolio/analysis/ai-chat-panel/`
 - Embedded in portfolio analysis page only
 - Component state for messages (lost on refresh)
 - localStorage: `gf_ai_chat_messages`, `gf_ai_chat_session_id`
 - Max 200 messages in localStorage (recently added)
 **Backend:** `apps/api/src/app/endpoints/ai/ai.controller.ts`
 - `POST /ai/chat` - single conversation endpoint
 - `POST /ai/chat/feedback` - feedback submission
 - Redis memory: 10 turns, 24h TTL per session
 **Limitations:**
 - No cross-session persistence
 - No database storage
 - Single conversation only
 - Page-scoped (not global)
 ## Solution Architecture
 ### Ticket-Ready Deliverables (Must Close Before Build)
 - [ ] Define `POST /ai/chat` transition contract: request/response schema, compatibility window, and deprecation path.
 - [ ] Harden Prisma design: role enum, composite conversation list index, and conversation-to-memory session mapping field.
 - [ ] Define Redis lifecycle policy: keying, TTL behavior, memory rehydration behavior, and delete semantics.
 - [ ] Add security test matrix: cross-user conversation access, ownership checks, and expected status codes (`403`/`404`).
 - [ ] Define measurable performance SLOs and regression gates (p95 latency + pagination/query budgets).
 - [ ] Define failure-mode behavior for DB/Redis outages, retry policy, and UI degraded-state signaling.
 - [ ] Define API rate limits and `429` response contract for chat and conversation endpoints.
 - [ ] Define search implementation details (fields, indexing strategy, query behavior).
 - [ ] Define responsive UX specifications (desktop/tablet/mobile layout and collision behavior).
 ### Phase 1: Database Schema & Backend
 #### 1.1 Prisma Schema Extensions
 ```prisma
 // prisma/schema.prisma
 model ChatConversation {
  id              String   @id @default(cuid())
  userId          String
  memorySessionId String   @unique
  title           String?
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
  messages        ChatMessage[]
  user            User     @relation(fields: [userId], references: [id])
  @@index([userId, updatedAt])
  @@index([userId, createdAt])
 }
 model ChatMessage {
  id             String   @id @default(cuid())
  conversationId String
  role           ChatMessageRole
  content        String   @db.Text
  metadata       Json?    // Store response data (toolCalls, verification, etc.)
  createdAt      DateTime @default(now())
  conversation   ChatConversation @relation(fields: [conversationId], references: [id], onDelete: Cascade)
  @@index([conversationId, createdAt])
 }
 enum ChatMessageRole {
  USER
  ASSISTANT
 }
 ```
 #### 1.2 Backend Changes
 **New DTOs:** `apps/api/src/app/endpoints/ai/ai-chat-conversation.dto.ts`
 ```typescript
 export class CreateConversationDto {
  title?: string;
 }
 export class UpdateConversationDto {
  title?: string;
 }
 export class ListConversationsQueryDto {
  limit?: number = 20;
  offset?: number = 0;
  search?: string;
 }
 ```
 **New Service:** `apps/api/src/app/endpoints/ai/ai-chat-conversation.service.ts`
 - `createConversation(userId, title?)`
 - `listConversations(userId, pagination)`
 - `getConversation(id, userId)`
 - `listMessages(conversationId, userId, pagination)`
 - `deleteConversation(id, userId)`
 - `updateConversation(id, data, userId)`
 **Updated Controller:** `apps/api/src/app/endpoints/ai/ai.controller.ts`
 ```typescript
@Post('conversations')
 createConversation(@Body() dto: CreateConversationDto)
@Get('conversations')
 listConversations(@Query() query: ListConversationsQueryDto)
@Get('conversations/:id')
 getConversation(@Param('id') id: string)
@Get('conversations/:id/messages')
 listMessages(@Param('id') id: string, @Query() query: ListMessagesQueryDto)
@Delete('conversations/:id')
 deleteConversation(@Param('id') id: string)
@Patch('conversations/:id')
 updateConversation(@Param('id') id: string, @Body() dto: UpdateConversationDto)
 ```
 **Transition Contract (Backward-Compatible):**
 ```typescript
 // Existing endpoint stays active during migration window
@Post('chat')
 chat(@Body() dto: AiChatDto & { conversationId?: string })
 ```
 - Request accepts both `conversationId` and legacy `sessionId`.
 - Resolution order: `conversationId` first, `sessionId` fallback, then create new conversation.
 - Response includes `conversationId` and keeps `memory.sessionId` for compatibility with existing clients.
 - Deprecation: `sessionId` request usage marked deprecated after widget rollout + one release cycle.
 **Updated AI Service:** `apps/api/src/app/endpoints/ai/ai.service.ts`
 - Resolve active conversation using transition contract (`conversationId` / `sessionId`)
 - Auto-create conversation on first message if no conversation mapping exists
 - Save all user/assistant messages to database after response completes
 - Load recent conversation messages when resuming and rehydrate memory when Redis session expires
 - Keep Redis memory isolated by user + memorySessionId to support safe conversation switching
 #### 1.3 Redis Lifecycle Mapping
 - Memory key format remains: `ai-agent-memory-${userId}-${memorySessionId}`
 - `ChatConversation.memorySessionId` is the canonical mapping from conversation to Redis memory.
 - Conversation delete flow removes:
  - `ChatConversation` row (cascade `ChatMessage`)
  - Redis key for `memorySessionId`
 - Expired Redis memory triggers rehydration from last `N` persisted messages for that conversation.
 - Redis TTL remains 24h for memory state; persisted DB history remains source of truth.
 #### 1.4 Error Handling and Degraded Modes
 - **DB unavailable on `POST /ai/chat`:**
  - Continue assistant response using Redis memory when available.
  - Return `historyPersistence: 'degraded'` in response metadata.
  - Queue unsaved message pair for retry with exponential backoff (`1s, 2s, 4s, 8s, 16s`, max 5 attempts).
  - Client shows non-blocking banner: `History sync delayed. Retrying.`
 - **Redis unavailable on `POST /ai/chat`:**
  - Rebuild prompt context from last 10 persisted conversation messages in DB.
  - Return `memorySource: 'database_fallback'` in response metadata.
 - **DB and Redis unavailable:**
  - Return `503 Service Unavailable` with `Retry-After`.
  - Keep current input in client draft box for user retry.
 - **Network timeout from client to API:**
  - Show pending state (`Sending...`) for request timeout window.
  - Retry once automatically in background, then surface actionable error.
 #### 1.5 Rate Limiting
 - `POST /ai/conversations`: max **50 conversations per user/day**.
 - `POST /ai/chat`: max **100 messages per conversation/hour** and **300 messages per user/hour**.
 - `POST /ai/chat/feedback`: max **30 feedback events per user/hour**.
 - Enforce at API layer and return `429` with payload:
  - `code: 'RATE_LIMIT_EXCEEDED'`
  - `scope: 'conversation' | 'user' | 'feedback'`
  - `retryAfterSeconds: number`
 ### Phase 2: Frontend Service
 #### 2.1 New AI Chat Service
 **File:** `apps/client/src/app/services/ai-chat.service.ts`
 ```typescript
@Injectable({ providedIn: 'root' })
 export class AiChatService {
  private currentConversation$ = new BehaviorSubject<ChatConversation | null>(null);
  private conversations$ = new BehaviorSubject<ChatConversation[]>([]);
  // Conversation CRUD
  createConversation(title?: string): Observable<ChatConversation>
  loadConversations(pagination?: ListConversationsQuery): Observable<ChatConversation[]>
  loadConversation(id: string): Observable<ChatConversation>
  deleteConversation(id: string): Observable<void>
  updateConversation(id: string, data: UpdateConversationDto): Observable<ChatConversation>
  // Messages
  sendMessage(conversationId: string, query: string): Observable<AiAgentChatResponse>
  loadMessages(conversationId: string): Observable<AiChatMessage[]>
  // State
  getCurrentConversation(): Observable<ChatConversation | null>
  getConversations(): Observable<ChatConversation[]>
 }
 ```
 #### 2.2 Enhanced localStorage Structure
 ```typescript
 interface ChatStorageState {
  currentConversationId: string;
  conversations: Array<{
    id: string;
    title?: string;
    lastUpdated: Date;
    messageCount: number;
  }>;
 }
 ```
 #### 2.3 Search Specification
 - Search scope: conversation `title` + rolling preview text built from the first 3 user messages.
 - Data model support:
  - Add `searchText` field on `ChatConversation`.
  - Update `searchText` when title changes or one of first 3 user messages changes.
 - Query strategy:
  - PostgreSQL full-text search: `to_tsvector('english', searchText)` + `plainto_tsquery`.
  - Add `GIN` index via SQL migration for `searchText` vector expression.
 - API behavior:
  - Debounce 300ms on client before query.
  - Return top 20 matches ordered by rank, then by `updatedAt DESC`.
 ### Phase 3: UI Components
 #### 3.1 Global Chat Widget
 **Location:** `apps/client/src/app/components/global/ai-chat-widget/`
 **Files:**
 - `ai-chat-widget.component.ts` - Main widget controller
 - `ai-chat-widget.component.scss` - Fixed positioning styles
 - `ai-chat-widget.component.html` - Template
 **Key Features:**
 ```typescript
@Component({
  selector: 'gf-ai-chat-widget',
  template: `
    <button class="chat-toggle" (click)="toggleChat()">
      <mat-icon>chat</mat-icon>
    </button>
    <div class="chat-container" *ngIf="isOpen">
      <gf-ai-chat-sidebar
        [conversations]="conversations"
        (conversationSelected)="loadConversation($event)"
        (newChat)="startNewChat()"
      ></gf-ai-chat-sidebar>
      <gf-ai-chat-panel
        [conversationId]="currentConversationId"
        [messages]="messages"
        (messageSent)="handleMessage($event)"
      ></gf-ai-chat-panel>
    </div>
  `,
  styles: [`
    .chat-toggle {
      position: fixed;
      bottom: 24px;
      right: 24px;
      z-index: 1000;
    }
    .chat-container {
      position: fixed;
      bottom: 80px;
      right: 24px;
      width: 800px;
      height: 600px;
      z-index: 1000;
    }
  `]
 })
 export class GfAiChatWidgetComponent {
  isOpen = false;
  conversations$ = this.aiChatService.getConversations();
  // ...
 }
 ```
 #### 3.2 Chat History Sidebar
 **Location:** `apps/client/src/app/components/global/ai-chat-widget/ai-chat-sidebar/`
 **Files:**
 - `ai-chat-sidebar.component.ts`
 - `ai-chat-sidebar.component.scss`
 - `ai-chat-sidebar.component.html`
 **Features:**
 - List of conversations with titles
 - Search/filter
 - New chat button
 - Delete conversation option
 - Auto-generate titles from first message
 #### 3.3 Responsive UX Specification
 - **Desktop (`>= 1200px`)**:
  - Floating widget anchored bottom-right.
  - Container target width `800px`, height `600px`.
  - Sidebar default open.
 - **Tablet (`768px - 1199px`)**:
  - Floating widget anchored bottom-right.
  - Container target width `600px`, height `70vh`.
  - Sidebar collapsible and closed by default.
 - **Mobile (`< 768px`)**:
  - Full-screen modal overlay.
  - Slide-out sidebar with explicit back button.
  - Input composer fixed to bottom safe area.
 - **Collision behavior**:
  - Widget offsets from existing floating action buttons.
  - Highest overlay z-index in app shell layer.
  - Escape key and backdrop click close behavior defined consistently.
 ### Phase 4: Migration & Integration
 #### 4.1 Refactor Existing Chat Panel
 **Current:** `apps/client/src/app/pages/portfolio/analysis/ai-chat-panel/ai-chat-panel.component.ts`
 **Changes:**
 - Remove localStorage logic (move to service)
 - Use `AiChatService` for all operations
 - Keep as embedded option in portfolio page
 - Share service with global widget
 #### 4.2 Global Integration
 **File:** `apps/client/src/app/app.component.ts`
 ```typescript
@Component({
  selector: 'gf-root',
  template: `
    <router-outlet></router-outlet>
    <gf-ai-chat-widget></gf-ai-chat-widget>
  `
 })
 export class AppComponent {}
 ```
 #### 4.3 Permission & Feature Flag
 **Service:** Check user permissions before showing widget
 ```typescript
 if (this.user.hasPermissionToReadAiPrompt) {
  showChatWidget = true;
 }
 ```
 ## Implementation Order
 ### Week 0: Contract + Safety Baseline
 1. Finalize `POST /ai/chat` compatibility contract (`conversationId`, legacy `sessionId`, response fields).
 2. Finalize Redis lifecycle mapping and delete semantics.
 3. Finalize Prisma enums/indexes and migration plan.
 4. Finalize degraded-mode behavior for DB/Redis/network failure paths.
 5. Finalize API rate-limit policy and `429` response payload contract.
 6. Finalize search implementation spec and indexing plan.
 7. Finalize responsive UX specs for desktop/tablet/mobile.
 8. Define measurable SLOs and add regression gate placeholders.
 9. Define security test matrix for ownership and cross-user access.
 ### Week 1: Backend Foundation
 1. Add Prisma models + migration
 2. Create conversation service
 3. Add controller endpoints
 4. Update AI service to persist messages
 5. Write tests for conversation CRUD
 ### Week 2: Frontend Service
 1. Create `AiChatService` with API integration
 2. Migrate existing chat panel to use service
 3. Add conversation loading/saving logic
 4. Update localStorage structure
 5. Test service in isolation
 ### Week 3: UI Components
 1. Build chat sidebar component
 2. Extract chat panel logic to shared component
 3. Create global chat widget wrapper
 4. Add to app component
 5. Implement conversation switching
 6. Polish UI (animations, responsive design)
 ## Acceptance Criteria
 - [ ] Widget toggle button visible on all pages (with permission)
 - [ ] Clicking toggle opens/closes floating chat window
 - [ ] Sidebar shows list of past conversations (title + timestamp)
 - [ ] Clicking conversation loads it from database
 - [ ] "New chat" button clears and starts fresh conversation
 - [ ] All conversations persist across page refreshes
 - [ ] All conversations persist across browser sessions
 - [ ] Conversations sync across devices (database-backed)
 - [ ] Search/filter conversations by title
 - [ ] Delete individual conversations
 - [ ] Rename conversations
 - [ ] Existing portfolio chat still works embedded
 - [ ] `POST /ai/chat` remains backward-compatible for existing `sessionId` clients during transition
 - [ ] Conversation endpoints enforce ownership checks (cross-user IDs blocked with `403`/`404`)
 - [ ] Conversation list query uses indexed path and meets p95 target
 - [ ] Conversation message load is paginated and meets p95 target
 - [ ] Redis delete + rehydration behavior is deterministic and covered by tests
 - [ ] DB and Redis failure modes follow documented degraded behavior and user-facing status messaging
 - [ ] API rate limits enforced with deterministic `429` contract for each scoped limit
 - [ ] Search returns ranked matches over title + first-message preview text
 - [ ] Widget behavior matches desktop/tablet/mobile UX specification
 ## Testing Strategy
 ### Backend Tests
 ```typescript
 // ai-chat-conversation.service.spec.ts
 describe('AiChatConversationService', () => {
  it('should create conversation with auto-generated title');
  it('should list conversations for user');
  it('should paginate results');
  it('should delete conversation and cascade messages');
  it('should reject cross-user conversation access');
  it('should use memorySessionId mapping for Redis lifecycle');
 });
 // ai.controller.spec.ts
 describe('AiController chat transition contract', () => {
  it('should accept conversationId on POST /ai/chat');
  it('should accept legacy sessionId on POST /ai/chat');
  it('should return conversationId and memory.sessionId in response');
  it('should return deterministic 429 payload when rate limits are exceeded');
 });
 ```
 ### Frontend Tests
 ```typescript
 // ai-chat.service.spec.ts
 describe('AiChatService', () => {
  it('should sync with localStorage');
  it('should handle network errors gracefully');
  it('should cache conversations locally');
 });
 // ai-chat-widget.component.spec.ts
 describe('GfAiChatWidgetComponent', () => {
  it('should toggle open/closed');
  it('should load conversation from service');
  it('should create new conversation');
 });
 ```
 ### E2E Tests
 - Create conversation → refresh → verify persists
 - Switch between conversations → verify correct context
 - Delete conversation → verify removed from list
 - Search conversations → verify filtering
 - Attempt to load another user's conversation ID → verify `403`/`404`
 - Continue old `sessionId` chat flow after deploy → verify compatibility
 - Expire Redis key for active conversation → verify memory rehydration from persisted messages
 - Simulate DB write outage on send → verify degraded status + retry behavior
 - Simulate Redis outage on send → verify DB-context fallback path
 - Exceed per-conversation and per-user limits → verify `429` payload and retry timing
 - Validate search ranking over title + first-message preview text
 - Validate desktop/tablet/mobile widget layouts and sidebar behavior
 ### Manual Verification
 - Send message in widget and embedded panel → latest message renders first (reverse chronological UI behavior).
 - Rate assistant response after list reordering → feedback applies to the correct assistant message.
 - Delete conversation and refresh page → conversation remains deleted and does not reappear.
 - Force API timeout from browser devtools and verify pending + retry + actionable error messaging.
 ## Performance Targets (SLOs)
 - Conversation list (`GET /ai/conversations`, limit 50): p95 API latency < 250ms (excluding network RTT).
 - Message page load (`GET /ai/conversations/:id/messages`, limit 100): p95 API latency < 350ms.
 - Chat send overhead from persistence layer (`POST /ai/chat`): additional p95 < 120ms over current baseline.
 - Widget open to first message paint (cached list path): p95 < 400ms on desktop local benchmark.
 - DB query budget:
  - List conversations: max 2 queries/request
  - Load messages page: max 2 queries/request
  - Send message persist path: max 4 queries/request
 ## Performance Strategies
 - **localStorage caching**: Keep lightweight conversation summary cache locally.
 - **Lazy loading**: Load messages on demand by conversation.
 - **Pagination defaults**: 50 conversations, 100 messages per page.
 - **Debounced search**: 300ms debounce before API search.
 - **Optimistic UI**: Update local list immediately, reconcile with server response.
 - **Backpressure**: Rate-limit enforcement protects API and LLM spend under burst traffic.
 - **Degraded mode retries**: Background sync retries prevent data loss on transient failures.
 ## Migration Strategy
 ### Database Migration
 ```bash
 # Create new tables
 pnpm nx run api:prisma:migrate
 # Backfill existing Redis sessions (optional)
 # Script to load active Redis sessions into database
 ```
 ### Zero-Downtime Deployment
 1. Deploy backend contract changes first (`conversationId` + legacy `sessionId` support).
 2. Keep existing frontend on legacy `sessionId` flow.
 3. Deploy frontend widget/service using conversation APIs.
 4. Enable feature flag for a subset of users and monitor latency/error/security metrics.
 5. Remove legacy `sessionId` client usage after one stable release cycle.
 ## Rollback Plan
 If critical issues arise:
 1. Frontend: Fall back to localStorage-only mode
 2. Backend: Keep old endpoints functional
 3. Feature flag: Disable global widget
 4. Database: Keep existing data, revert schema changes
 ## Open Questions
 1. Should we store message metadata (toolCalls, verification) in JSON or separate tables?
   - **Decision**: JSON for simplicity (RDBMS not optimal for sparse data)
 2. Should we auto-generate conversation titles?
   - **Decision**: Yes, use first 50 chars of first user message
 3. Should conversations be shareable (like ChatGPT)?
   - **Decision**: No, private-only for MVP
 4. Max messages per conversation?
   - **Decision**: No limit (database), but lazy load last 100
 5. Should we export conversations?
   - **Decision**: Future enhancement, not MVP
 ## Files to Create
 1. `apps/api/src/app/endpoints/ai/ai-chat-conversation.dto.ts`
 2. `apps/api/src/app/endpoints/ai/ai-chat-conversation.service.ts`
 3. `apps/api/src/app/endpoints/ai/ai-chat-conversation.controller.ts`
 4. `apps/client/src/app/services/ai-chat.service.ts`
 5. `apps/client/src/app/components/global/ai-chat-widget/`
 6. `apps/client/src/app/components/global/ai-chat-widget/ai-chat-widget.component.ts`
 7. `apps/client/src/app/components/global/ai-chat-widget/ai-chat-sidebar/`
 ## Files to Modify
 1. `prisma/schema.prisma`
 2. `apps/api/src/app/endpoints/ai/ai.service.ts`
 3. `apps/api/src/app/endpoints/ai/ai.controller.ts`
 4. `apps/client/src/app/pages/portfolio/analysis/ai-chat-panel/ai-chat-panel.component.ts`
 5. `apps/client/src/app/app.component.ts`
 ## Estimated Effort
 - **Week 0 hardening**: 3-4 days
 - **Backend implementation**: 4-6 days
 - **Frontend service + search**: 4-5 days
 - **UI components + responsive UX**: 4-6 days
 - **Testing + stabilization**: 4-5 days
 **Total**: ~19-26 days (4-5 weeks)
 ### Scope Control Option (If 3 Weeks Is Required)
 - Keep transition contract, Redis mapping, security tests, and core SLOs.
 - Defer full-text search to title-only search for MVP.
 - Defer tablet-specific layout polish to post-MVP.
 ## Plan Confidence
 - **Architecture confidence**: Medium-high (strong phase structure, explicit rollout, measurable SLOs).
 - **Primary risks**: Transition contract drift and Redis lifecycle edge cases.
 - **Risk control basis**: Ownership tests, compatibility tests, and perf/security gates in CI.
 ## Next Steps
 1. Convert the five ticket-ready deliverables into Linear sub-tasks with owners.
 2. Approve transition contract and Redis lifecycle spec before schema migration.
 3. Implement Week 0 hardening items and merge behind feature flag.
 4. Execute Week 1-3 phases with SLO/security gates active in CI.
 5. Run rollout checklist and remove legacy `sessionId` path after stability window.