From 3f9602346c63d8f6cb87a51353ab40996ac1f04d Mon Sep 17 00:00:00 2001 From: Nuwan Date: Mon, 26 Jan 2026 14:58:07 +0530 Subject: [PATCH] docs(6): capture phase context Phase 6: Session Chat Research & Design - Vision and goals documented - Essential requirements identified - Scope boundaries defined --- .../06-CONTEXT.md | 102 ++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 .planning/phases/06-session-chat-research-design/06-CONTEXT.md diff --git a/.planning/phases/06-session-chat-research-design/06-CONTEXT.md b/.planning/phases/06-session-chat-research-design/06-CONTEXT.md new file mode 100644 index 000000000..4b7c869fd --- /dev/null +++ b/.planning/phases/06-session-chat-research-design/06-CONTEXT.md @@ -0,0 +1,102 @@ +# Phase 6: Session Chat Research & Design - Context + +**Gathered:** 2026-01-26 +**Status:** Ready for research + + +## 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. + + + + +## 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. + + + + +## 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. + + + + +## 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 + + + + +## 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. + + + +--- + +*Phase: 06-session-chat-research-design* +*Context gathered: 2026-01-26*