# Phase 6: Session Chat Research & Design - Context

**Gathered:** 2026-01-26
**Status:** Ready for research

<vision>
## How This Should Work

This is a research and design phase - a deep dive into the legacy chat implementation to understand everything before building the React version.

The research should thoroughly explore:
- **Legacy jQuery/CoffeeScript chat code** - How does the existing chat work? What patterns are used?
- **Chat APIs and endpoints** - Document all API methods for fetching messages, posting messages, marking as read
- **WebSocket message handling** - How do real-time chat messages flow through the system?
- **Read/unread tracking** - How will we track which messages are unread for each user? (This is NEW functionality)
- **Modeless dialog patterns** - How does the existing dialog work? How to make it repositionable?

The outcome should be a comprehensive understanding of the legacy system PLUS a clear React architecture design showing:
- Component structure (chat window, message list, message item, composer)
- Redux state shape (messages, unread counts, window state)
- WebSocket integration patterns
- API integration approach
- How read/unread tracking will work

This follows the same pattern as Phase 4 (JamTrack Research & Design) - understand the legacy, then design the modern version.

</vision>

<essential>
## What Must Be Nailed

All three aspects are equally critical for this phase:

- **Complete API documentation** - Full understanding of every chat-related API, WebSocket message, and data structure
- **Legacy pattern understanding** - Deep knowledge of how the existing chat works - message flow, read/unread logic, real-time updates
- **Clear React architecture** - Concrete plan for how chat will work in React - components, Redux state, hooks, patterns following established jam-ui patterns from Backing Track and JamTrack

Success means the implementation phases (7-11) can proceed with confidence, knowing exactly what to build and how to build it.

</essential>

<boundaries>
## What's Out of Scope

- **No implementation code** - This phase is research and design only. No React components, Redux state implementation, or actual working code. That comes in Phases 7-11.
- **File attachments** - Attachment display is a separate feature in the next milestone. Don't research or design attachment functionality yet - just understand how messages reference them.
- **Edge cases and error handling** - Focus on happy path understanding. Error handling comes in Phase 11 (Finalization).

This phase delivers documentation and design artifacts, not working code.

</boundaries>

<specifics>
## Specific Ideas

**Chat window design (from screenshots):**
- Modeless dialog that can be repositioned on screen
- User can keep window open while using other session features
- Message display shows: user photo, user name (as link), message text (gray), timestamp
- Text entry box at bottom with send icon on the right

**Read/unread functionality (NEW):**
- Red dot indicator on chat button when there are unread messages
- When user opens chat window, all messages marked as read
- While chat window is open, new messages immediately marked as read
- This is driven by new UI not having chat constantly visible like legacy UI

**Research approach:**
- Study legacy jQuery/CoffeeScript implementation thoroughly
- Document all APIs, WebSocket messages, data structures
- Understand how existing system works before designing React version
- Follow similar pattern to Phase 4 (JamTrack Research & Design)

**TDD requirement:**
- All jam-ui implementation code (Phases 7-11) will follow TDD methodology per CLAUDE.md
- Research phase should note where tests will be needed

</specifics>

<notes>
## Additional Context

This research phase mirrors the approach used in Phase 4 (JamTrack Research & Design), where we:
1. Explored legacy jQuery/CoffeeScript code
2. Documented APIs and patterns
3. Designed React architecture
4. Created implementation roadmap

The read/unread tracking is new functionality not present in the legacy UI, so we'll need to design this from scratch while understanding how it integrates with the existing message system.

User provided screenshots showing:
- `/Users/nuwan/Desktop/chat-window.png` - Chat window with messages and text entry
- `/Users/nuwan/Desktop/chat-button-unread.png` - Chat button with red dot indicator

File attachment display is acknowledged but deferred to next milestone - this milestone focuses on text messages and read/unread tracking only.

</notes>

---

*Phase: 06-session-chat-research-design*
*Context gathered: 2026-01-26*
