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

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

# 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)
</context>

<tasks>

<task type="auto">
  <name>Task 1: Design component architecture and create CHAT_COMPONENT_DESIGN.md</name>
  <files>.planning/phases/06-session-chat-research-design/CHAT_COMPONENT_DESIGN.md</files>
  <action>
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.
  </action>
  <verify>
CHAT_COMPONENT_DESIGN.md exists with component tree, props interfaces, state ownership decisions, and integration approach documented.
  </verify>
  <done>
Complete component architecture designed. Developers can understand the component structure, data flow, and how to build each piece in Phases 7-11.
  </done>
</task>

<task type="auto">
  <name>Task 2: Design Redux state and WebSocket integration, create CHAT_REDUX_DESIGN.md</name>
  <files>.planning/phases/06-session-chat-research-design/CHAT_REDUX_DESIGN.md</files>
  <action>
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.
  </action>
  <verify>
CHAT_REDUX_DESIGN.md exists with state shape, async thunks, selectors, WebSocket handlers, and read/unread logic documented.
  </verify>
  <done>
Complete Redux architecture designed. Clear plan for state management, async operations, real-time updates, and read/unread tracking. Follows established jam-ui Redux patterns.
  </done>
</task>

<task type="auto">
  <name>Task 3: Create implementation roadmap for Phases 7-11</name>
  <files>.planning/phases/06-session-chat-research-design/IMPLEMENTATION_ROADMAP.md</files>
  <action>
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.
  </action>
  <verify>
IMPLEMENTATION_ROADMAP.md exists with detailed breakdown of Phases 7-11, risk analysis, TDD strategy, and testing approach documented.
  </verify>
  <done>
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.
  </done>
</task>

</tasks>

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

<success_criteria>

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

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