---
phase: 06-session-chat-research-design
plan: 01
type: execute
---

<objective>
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.
</objective>

<execution_context>
@./.claude/get-shit-done/workflows/execute-phase.md
@./.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.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
</context>

<tasks>

<task type="auto">
  <name>Task 1: Research legacy chat implementation and create CHAT_LEGACY.md</name>
  <files>.planning/codebase/CHAT_LEGACY.md</files>
  <action>
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).
  </action>
  <verify>
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.
  </verify>
  <done>
CHAT_LEGACY.md documents how legacy chat works with enough detail to design React equivalent. Contains file paths, patterns, and data flow.
  </done>
</task>

<task type="auto">
  <name>Task 2: Document chat API surface and create CHAT_API.md</name>
  <files>.planning/codebase/CHAT_API.md</files>
  <action>
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).
  </action>
  <verify>
CHAT_API.md exists with sections for: REST endpoints, WebSocket messages, jamClient methods (if any), Database models. Includes example payloads and schemas.
  </verify>
  <done>
Complete chat API surface documented. Any developer can understand how to fetch, send, and receive messages. Missing functionality (read/unread) clearly identified.
  </done>
</task>

<task type="auto">
  <name>Task 3: Analyze React patterns and create CHAT_REACT_PATTERNS.md</name>
  <files>.planning/codebase/CHAT_REACT_PATTERNS.md</files>
  <action>
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.
  </action>
  <verify>
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.
  </verify>
  <done>
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.
  </done>
</task>

</tasks>

<verification>
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
</verification>

<success_criteria>

- 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)
</success_criteria>

<output>
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)
</output>
