From eca7f95c23df81fed912fefbbab90a33160e6634 Mon Sep 17 00:00:00 2001 From: Nuwan Date: Mon, 26 Jan 2026 15:04:31 +0530 Subject: [PATCH] docs(6): create phase plan Phase 6: Session Chat Research & Design - 2 plans created - 6 total tasks defined (3 per plan) - Ready for execution Plan 1: Legacy Chat Analysis & API Documentation Plan 2: React Architecture & Implementation Roadmap --- .../06-01-PLAN.md | 251 +++++++++++++ .../06-02-PLAN.md | 340 ++++++++++++++++++ 2 files changed, 591 insertions(+) create mode 100644 .planning/phases/06-session-chat-research-design/06-01-PLAN.md create mode 100644 .planning/phases/06-session-chat-research-design/06-02-PLAN.md diff --git a/.planning/phases/06-session-chat-research-design/06-01-PLAN.md b/.planning/phases/06-session-chat-research-design/06-01-PLAN.md new file mode 100644 index 000000000..062624c22 --- /dev/null +++ b/.planning/phases/06-session-chat-research-design/06-01-PLAN.md @@ -0,0 +1,251 @@ +--- +phase: 06-session-chat-research-design +plan: 01 +type: execute +--- + + +Understand legacy chat implementation and document all APIs, WebSocket messages, and patterns. + +Purpose: Build comprehensive understanding of how session chat works in the legacy jQuery/CoffeeScript codebase before designing React version. This research phase mirrors Phase 4 Plan 1 (JamTrack Legacy Analysis). + +Output: Three documentation files capturing legacy patterns, chat API surface, and React integration approach. + + + +@./.claude/get-shit-done/workflows/execute-phase.md +@./.claude/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md +@.planning/phases/06-session-chat-research-design/06-CONTEXT.md + +# Phase 4 pattern reference (JamTrack research) +@.planning/phases/04-jamtrack-research-design/04-01-SUMMARY.md + +# Codebase understanding +@.planning/codebase/ARCHITECTURE.md +@.planning/codebase/CONVENTIONS.md + +# Screenshots for reference +@/Users/nuwan/Desktop/chat-window.png +@/Users/nuwan/Desktop/chat-button-unread.png + +**Key context from Phase 6 CONTEXT.md:** +- Deep dive into legacy code: jQuery/CoffeeScript chat, APIs, WebSocket messages +- Focus on happy path (not edge cases yet) +- Read/unread tracking is NEW functionality not in legacy +- File attachments out of scope (next milestone) + +**Established patterns from prior phases:** +- jamClient API integration patterns (Phase 2,3: Backing Track, Phase 5: JamTrack) +- Redux state management (Phase 5: mediaSlice extensions) +- WebSocket message handling (Phase 5: MIXER_CHANGES, JAM_TRACK_CHANGES) +- Modal/dialog patterns in jam-ui + + + + + + Task 1: Research legacy chat implementation and create CHAT_LEGACY.md + .planning/codebase/CHAT_LEGACY.md + +Search the legacy codebase (web/, coffee/, app/) for jQuery/CoffeeScript chat implementation: + +1. **Find chat dialog code:** + - Search for chat dialog/modal patterns in CoffeeScript + - Look for jQuery UI dialogs with "chat" in names + - Examine how modeless dialogs are implemented + - Document how repositioning works + +2. **Message display patterns:** + - How are messages rendered (templates, loops)? + - Where do user photos come from? + - How are timestamps formatted? + - How does auto-scroll work? + +3. **Message composition:** + - How is text entry handled? + - How is send button wired up? + - What validation exists? + +4. **State management:** + - Where is chat state stored (Reflux stores, jQuery data, global vars)? + - How are messages cached? + - What data structures are used? + +5. **Integration points:** + - How does chat integrate with session UI? + - How is the chat button managed? + - When is chat initialized? + +Document findings in CHAT_LEGACY.md with: +- File paths to key components +- Code patterns used (jQuery plugins, CoffeeScript classes, Reflux stores) +- Data flow diagrams (where possible) +- Key observations and quirks + +**What to avoid:** Don't try to understand EVERYTHING - focus on happy path patterns. Skip error handling details (that's for Phase 11). + + +CHAT_LEGACY.md exists with sections for: Dialog implementation, Message display, Composition, State management, Integration points. File includes actual file paths and code pattern descriptions. + + +CHAT_LEGACY.md documents how legacy chat works with enough detail to design React equivalent. Contains file paths, patterns, and data flow. + + + + + Task 2: Document chat API surface and create CHAT_API.md + .planning/codebase/CHAT_API.md + +Map all chat-related API endpoints and jamClient methods (if any): + +1. **REST API endpoints (search web/config/routes.rb, web/app/controllers/):** + - GET endpoints for fetching messages + - POST endpoint for sending messages + - PUT/PATCH endpoints for marking as read + - Data structures (request/response format) + - Authentication/authorization + +2. **WebSocket messages (search websocket-gateway/, pb/src/):** + - Chat message broadcast format + - Real-time message delivery patterns + - Protocol buffer definitions (if chat uses pb) + - Message types and payloads + +3. **jamClient methods (if any - search for SessionChat* or Chat* methods):** + - Any native client chat methods + - OR confirm chat is purely web-based + +4. **Database models (search web/app/models/):** + - Message model fields + - Session associations + - User associations + - Any read/unread tracking fields (likely don't exist yet) + +Document in CHAT_API.md with: +- Complete API reference (endpoints, methods, params, responses) +- WebSocket message catalog (types, payloads, when sent) +- Data model ERD or schema snippet +- Example requests/responses +- Notes on what's missing (like read/unread tracking) + +**What to avoid:** Don't implement anything - this is documentation only. Don't worry about error responses yet (happy path focus). + + +CHAT_API.md exists with sections for: REST endpoints, WebSocket messages, jamClient methods (if any), Database models. Includes example payloads and schemas. + + +Complete chat API surface documented. Any developer can understand how to fetch, send, and receive messages. Missing functionality (read/unread) clearly identified. + + + + + Task 3: Analyze React patterns and create CHAT_REACT_PATTERNS.md + .planning/codebase/CHAT_REACT_PATTERNS.md + +Analyze existing jam-ui patterns and identify what's available vs what needs building: + +1. **Existing modal/dialog components (search jam-ui/src/components/):** + - Find WindowPortal (used by JamTrack, Metronome) + - Check JKModal, JKDialog patterns + - Understand modeless dialog patterns + - Document reusable components + +2. **Redux state patterns (search jam-ui/src/store/):** + - Review mediaSlice (Backing Track, JamTrack patterns) + - Review activeSessionSlice (session state) + - Review sessionUISlice (UI state patterns) + - Identify where chat state should live + +3. **WebSocket integration (search jam-ui/src/):** + - Review existing WebSocket handler patterns + - Check how MIXER_CHANGES, JAM_TRACK_CHANGES work + - Understand message routing + +4. **API integration (search jam-ui/src/services/, jam-ui/src/api/):** + - Review existing API client patterns + - Check async thunk patterns from Phase 5 + - Understand error handling patterns + +5. **Component patterns (search jam-ui/src/components/):** + - Look at JKSessionJamTrackPlayer structure (Phase 5) + - Look at JKSessionBackingTrackPlayer structure (Phase 3) + - Identify reusable sub-component patterns (buttons, inputs, lists) + +Document in CHAT_REACT_PATTERNS.md with: +- **Available Components:** What can be reused (WindowPortal, buttons, etc.) +- **Redux State Patterns:** Where chat fits in Redux architecture +- **WebSocket Integration:** How chat messages will be received +- **API Integration:** How to call chat endpoints (following established patterns) +- **Gap Analysis:** What's missing and needs to be created +- **TDD Candidates:** Which parts should follow TDD (API calls, message parsing, read/unread logic) + +**What to avoid:** Don't design components yet (that's Plan 2). Don't write code. Just document what exists and identify gaps. + + +CHAT_REACT_PATTERNS.md exists with sections for: Available components, Redux patterns, WebSocket integration, API integration, Gap analysis, TDD candidates. Includes file paths and pattern descriptions. + + +Clear picture of what jam-ui provides for chat and what needs building. Gap analysis shows exactly what Phases 7-11 will implement. TDD candidates identified per CLAUDE.md requirements. + + + + + + +Before declaring plan complete: +- [ ] All 3 documentation files exist in .planning/codebase/ +- [ ] CHAT_LEGACY.md documents how legacy chat works (file paths, patterns, data flow) +- [ ] CHAT_API.md documents complete API surface (REST, WebSocket, models) +- [ ] CHAT_REACT_PATTERNS.md shows available patterns and gaps +- [ ] Read/unread tracking identified as NEW functionality (not in legacy) +- [ ] TDD candidates identified for implementation phases + + + + +- All tasks completed +- Three documentation files created +- Legacy patterns thoroughly documented +- API surface completely mapped +- React integration approach identified +- Gaps clearly documented +- Ready for Plan 2 (React architecture design) + + + +After completion, create `.planning/phases/06-session-chat-research-design/06-01-SUMMARY.md`: + +# Phase 6 Plan 1: Legacy Chat Analysis & API Documentation Summary + +**Documented legacy chat implementation, APIs, and React integration patterns** + +## Accomplishments + +- Created CHAT_LEGACY.md documenting jQuery/CoffeeScript implementation +- Created CHAT_API.md mapping REST endpoints, WebSocket messages, database models +- Created CHAT_REACT_PATTERNS.md analyzing jam-ui patterns and gaps + +## Files Created/Modified + +- `.planning/codebase/CHAT_LEGACY.md` - Legacy implementation analysis +- `.planning/codebase/CHAT_API.md` - Complete API reference +- `.planning/codebase/CHAT_REACT_PATTERNS.md` - React pattern analysis and gaps + +## Decisions Made + +[Document key findings: What patterns are used? What APIs exist? What's missing?] + +## Issues Encountered + +[Any surprises or complications discovered, or "None"] + +## Next Phase Readiness + +Ready for Plan 2 (React Architecture & Implementation Roadmap) + diff --git a/.planning/phases/06-session-chat-research-design/06-02-PLAN.md b/.planning/phases/06-session-chat-research-design/06-02-PLAN.md new file mode 100644 index 000000000..247de7232 --- /dev/null +++ b/.planning/phases/06-session-chat-research-design/06-02-PLAN.md @@ -0,0 +1,340 @@ +--- +phase: 06-session-chat-research-design +plan: 02 +type: execute +--- + + +Design React architecture for session chat including components, Redux state, WebSocket integration, and read/unread tracking system. + +Purpose: Create comprehensive design for Phases 7-11 implementation, following established jam-ui patterns. This design phase mirrors Phase 4 Plan 2 (JamTrack Component & Redux Design). + +Output: Component design, Redux design, and implementation roadmap for chat feature. + + + +@./.claude/get-shit-done/workflows/execute-phase.md +@./.claude/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md +@.planning/phases/06-session-chat-research-design/06-CONTEXT.md + +# Plan 1 research outputs +@.planning/codebase/CHAT_LEGACY.md +@.planning/codebase/CHAT_API.md +@.planning/codebase/CHAT_REACT_PATTERNS.md + +# Phase 4 pattern reference (JamTrack design) +@.planning/phases/04-jamtrack-research-design/04-02-SUMMARY.md + +# Prior design patterns +@.planning/phases/05-jamtrack-implementation/05-01-SUMMARY.md + +# Codebase understanding +@.planning/codebase/ARCHITECTURE.md +@.planning/codebase/CONVENTIONS.md + +**Key context from Phase 6:** +- Read/unread tracking is NEW functionality not in legacy +- Modeless dialog (WindowPortal) can be kept open and repositioned +- Follow Backing Track and JamTrack patterns +- TDD required for jam-ui implementation (CLAUDE.md) + +**Established patterns from prior phases:** +- Component architecture: Player component with sub-components (Phase 5) +- Redux state extensions: Multiple slices for different concerns (Phase 5) +- WebSocket handlers: Message type routing and state updates (Phase 5) +- Async thunks: API integration with error handling (Phase 3,5) + + + + + + Task 1: Design component architecture and create CHAT_COMPONENT_DESIGN.md + .planning/phases/06-session-chat-research-design/CHAT_COMPONENT_DESIGN.md + +Design JKSessionChatWindow component architecture following Phase 5 (JamTrack) patterns: + +1. **Main component: JKSessionChatWindow** + - Uses WindowPortal for modeless dialog (like Metronome) + - Manages window state (open/closed, position) + - Connects to Redux for messages and state + - Handles WebSocket integration + +2. **Sub-components to design:** + - **ChatMessageList** - Scrollable message container with auto-scroll + - **ChatMessage** - Single message item (photo, name, text, timestamp) + - **ChatComposer** - Text input + send button + - **ChatHeader** - Window title bar (with close, maybe minimize) + - **ChatEmptyState** - Shown when no messages + - **ChatLoadingSpinner** - While fetching message history + +3. **Props vs Redux decision:** + - Which data comes from props vs Redux? + - Which callbacks are props vs dispatch? + - Follow Phase 5 patterns (JamTrack used minimal props, heavy Redux) + +4. **Component hierarchy:** + ``` + JKSessionChatWindow (WindowPortal) + ├── ChatHeader + ├── ChatMessageList + │ ├── ChatLoadingSpinner (conditional) + │ ├── ChatEmptyState (conditional) + │ └── ChatMessage (repeated) + └── ChatComposer + ``` + +5. **Reusable components:** + - Can reuse JKButton, JKAvatar, JKTimeDisplay? + - Document what's available vs what needs creating + +6. **Integration with session screen:** + - Chat button in JKSessionScreen top nav + - Badge/indicator for unread count + - Click handler to toggle window + +Document in CHAT_COMPONENT_DESIGN.md with: +- Component tree diagram +- Props interface for each component +- State ownership (props vs Redux) +- Reusable components identified +- File structure (where components live) +- Integration points with existing UI + +**What to avoid:** Don't write actual React code. Don't implement - just design the architecture. Keep it similar to JamTrack structure for consistency. + + +CHAT_COMPONENT_DESIGN.md exists with component tree, props interfaces, state ownership decisions, and integration approach documented. + + +Complete component architecture designed. Developers can understand the component structure, data flow, and how to build each piece in Phases 7-11. + + + + + Task 2: Design Redux state and WebSocket integration, create CHAT_REDUX_DESIGN.md + .planning/phases/06-session-chat-research-design/CHAT_REDUX_DESIGN.md + +Design Redux state extensions and WebSocket integration following Phase 5 patterns: + +1. **Redux state structure:** + +Decide which slice(s) to extend: +- **sessionChatSlice** (new) - messages, read/unread state +- **activeSessionSlice** extensions - current session's chat state +- **sessionUISlice** extensions - window open/closed, position + +Design state shape: +```javascript +// Example structure (refine based on research) +sessionChat: { + messages: { + [sessionId]: { + byId: { [messageId]: {id, userId, text, timestamp, isRead} }, + allIds: [messageIds], + isLoading: boolean, + error: string | null + } + }, + unreadCounts: { + [sessionId]: number + } +} + +sessionUI: { + chatWindow: { + isOpen: boolean, + position: {x, y} | null + } +} +``` + +2. **Async thunks to create:** + - **fetchChatMessages** - Load message history for session + - **sendChatMessage** - Post new message + - **markMessagesAsRead** - Mark messages read (new functionality) + - **openChatWindow** - Open window + mark as read + - **closeChatWindow** - Close window + - Each thunk should follow Phase 5 patterns (error handling, loading states) + +3. **Selectors to create:** + - selectChatMessages(sessionId) + - selectUnreadCount(sessionId) + - selectIsChatOpen + - selectChatWindowPosition + - Memoized selectors using Reselect (like Phase 5) + +4. **WebSocket message handlers:** + - **NEW_CHAT_MESSAGE** - Real-time message received + - **CHAT_MESSAGE_READ** - Message marked read by another user + - Extend existing WebSocket reducer patterns (see Phase 5: MIXER_CHANGES, JAM_TRACK_CHANGES) + - Handle message routing and state updates + +5. **Read/unread tracking logic:** + - When is a message marked read? (window open, user views) + - How does unread count update? (WebSocket + local state) + - How to handle multiple tabs/windows? (server as source of truth) + - Design API calls needed (may need new endpoint: PUT /api/sessions/:id/messages/mark_read) + +Document in CHAT_REDUX_DESIGN.md with: +- State shape with TypeScript interfaces +- Async thunk signatures and behavior +- Selector implementations (signatures) +- WebSocket message format and handlers +- Read/unread tracking state machine +- API integration approach + +**What to avoid:** Don't implement Redux code. Design the structure, but implementation is for Phases 7-11. Ensure consistency with existing Redux patterns. + + +CHAT_REDUX_DESIGN.md exists with state shape, async thunks, selectors, WebSocket handlers, and read/unread logic documented. + + +Complete Redux architecture designed. Clear plan for state management, async operations, real-time updates, and read/unread tracking. Follows established jam-ui Redux patterns. + + + + + Task 3: Create implementation roadmap for Phases 7-11 + .planning/phases/06-session-chat-research-design/IMPLEMENTATION_ROADMAP.md + +Create detailed roadmap for Phases 7-11 following Phase 4 Plan 2 pattern (which created Phase 5 roadmap): + +1. **Break down remaining phases into specific plans:** + + **Phase 7: Chat Infrastructure & State Management** (suggest 2-3 plans) + - Redux slice creation and selectors + - Async thunks for API calls + - WebSocket message handlers + + **Phase 8: Chat Window UI & Message Display** (suggest 2-3 plans) + - JKSessionChatWindow component with WindowPortal + - ChatMessageList and ChatMessage components + - Chat button integration in session screen + + **Phase 9: Message Composition & Sending** (suggest 2 plans) + - ChatComposer component + - Send message functionality + - Real-time message delivery + + **Phase 10: Read/Unread Status Management** (suggest 2 plans) + - Read/unread tracking logic + - Unread badge indicator + - Mark-as-read on window open + + **Phase 11: Chat Finalization** (suggest 2-3 plans) + - Error handling and edge cases + - Performance optimization + - UAT and polish + +2. **For each plan, estimate:** + - Number of tasks (target 2-3 per plan) + - Complexity (simple/medium/complex) + - Dependencies on prior plans + - TDD candidates (per CLAUDE.md requirements) + +3. **Risk analysis:** + - What are the HIGH risk areas? (read/unread tracking, WebSocket reliability) + - What are the MEDIUM risk areas? (modeless dialog positioning) + - What are the LOW risk areas? (message display) + +4. **TDD strategy:** + - Which features warrant TDD plans? (API thunks, message parsing, read/unread logic) + - Which use standard plans? (UI components, layout) + - Reference CLAUDE.md TDD requirements + +5. **Testing approach:** + - Unit tests (Jest): Redux thunks, selectors, utility functions + - Integration tests (Playwright): API calls, message flow, read/unread behavior + - E2E tests: Complete chat workflow + +6. **Deferred decisions for Phase 7-11:** + - Attachment display (next milestone) + - Message search/filtering (future) + - Message editing/deletion (future) + - Typing indicators (future) + +Document in IMPLEMENTATION_ROADMAP.md with: +- Phase-by-phase breakdown (Phases 7-11) +- Plan-level detail with task estimates +- Risk analysis with mitigation strategies +- TDD strategy per CLAUDE.md +- Testing approach +- Deferred features list + +**What to avoid:** Don't create the actual PLAN.md files for Phases 7-11 - that happens during their planning. This is high-level roadmap only. + + +IMPLEMENTATION_ROADMAP.md exists with detailed breakdown of Phases 7-11, risk analysis, TDD strategy, and testing approach documented. + + +Clear roadmap for implementing chat feature. Phases 7-11 have structured breakdown ready for plan-phase commands. TDD requirements identified. Risks documented with mitigation strategies. + + + + + + +Before declaring phase complete: +- [ ] CHAT_COMPONENT_DESIGN.md exists with complete component architecture +- [ ] CHAT_REDUX_DESIGN.md exists with state design and WebSocket integration +- [ ] IMPLEMENTATION_ROADMAP.md exists with Phases 7-11 breakdown +- [ ] Read/unread tracking design is comprehensive (NEW functionality) +- [ ] TDD strategy documented per CLAUDE.md requirements +- [ ] All designs follow established jam-ui patterns (Backing Track, JamTrack) +- [ ] Phase 6 complete - ready for Phase 7 implementation + + + + +- All tasks completed +- Three design documents created +- Component architecture designed (following Phase 5 patterns) +- Redux state designed (following established patterns) +- Read/unread tracking system designed (NEW) +- WebSocket integration designed +- Implementation roadmap created for Phases 7-11 +- TDD strategy documented +- Phase 6 complete - ready to begin implementation + + + +After completion, create `.planning/phases/06-session-chat-research-design/06-02-SUMMARY.md`: + +# Phase 6 Plan 2: React Architecture & Implementation Roadmap Summary + +**Designed React architecture, Redux state, and created implementation roadmap for Phases 7-11** + +## Accomplishments + +- Created CHAT_COMPONENT_DESIGN.md with component tree and integration approach +- Created CHAT_REDUX_DESIGN.md with state shape, async thunks, WebSocket handlers +- Created IMPLEMENTATION_ROADMAP.md with detailed Phase 7-11 breakdown +- Designed read/unread tracking system (NEW functionality) +- Identified TDD candidates per CLAUDE.md requirements + +## Files Created/Modified + +- `.planning/phases/06-session-chat-research-design/CHAT_COMPONENT_DESIGN.md` - Component architecture +- `.planning/phases/06-session-chat-research-design/CHAT_REDUX_DESIGN.md` - Redux design +- `.planning/phases/06-session-chat-research-design/IMPLEMENTATION_ROADMAP.md` - Phases 7-11 roadmap + +## Decisions Made + +[Document key architectural decisions: Redux state structure? Component hierarchy? WebSocket integration approach? Read/unread tracking design?] + +## Issues Encountered + +[Any challenges in the design process, or "None"] + +## Next Phase Readiness + +**Phase 6 complete!** Ready for Phase 7 (Chat Infrastructure & State Management). + +Use `/gsd:plan-phase 7` to break down Phase 7 into executable plans. +