seth
/
jam-cloud
mirror of https://bitbucket.org/jamkazam/jam-cloud.git
1
0
Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity
jam-cloud/.planning/ROADMAP.md

24 KiB
Raw Blame History

Roadmap: JamKazam Media Features Modernization

Overview

Transform the media opening workflow (Backing Track, JamTrack, Session Chat, Session Attachments) from legacy jQuery/CoffeeScript/Rails patterns into modern React patterns in jam-ui. Starting with completing the partially-implemented Backing Track player, we'll establish patterns that carry forward to JamTrack, Session Chat, and Session Attachments implementations. Each feature involves research phases to understand legacy CoffeeScript patterns, followed by React implementation phases.

Domain Expertise

None

Milestones

  • v1.0 Media Players - Phases 1-5 (shipped 2026-01-14)
  • v1.1 Music Session Chat - Phases 6-11 (shipped 2026-01-31)
  • v1.2 Session Attachments - Phases 12-16 (shipped 2026-02-07)
  • v1.3 Session Settings Tests - Phases 17-18 (shipped 2026-02-08)
  • v1.4 Memory Leak Prevention - Phases 19-23 (shipped 2026-02-10)

Phases

Phase Numbering:

  • Integer phases (1, 2, 3): Planned milestone work
  • Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

v1.0 Media Players (Phases 1-5) - SHIPPED 2026-01-14

Show completed phases
  • Phase 1: Backing Track Playback Monitoring - Implement 500ms polling, display duration and current time in MM:SS format
  • Phase 2: Backing Track Seek Controls - Functional seek bar with drag-to-position capability
  • Phase 3: Backing Track Finalization - Error handling, edge cases, performance optimization
  • Phase 4: JamTrack Research & Design - Explore legacy jQuery/CoffeeScript implementation, design React patterns
  • Phase 5: JamTrack Implementation - Build JamTrack player with mixdown selection and controls

v1.1 Music Session Chat (Phases 6-11) - SHIPPED 2026-01-31

Show completed phases

Milestone Goal: Add real-time chat functionality to music sessions with modeless window, message history, read/unread tracking, and file attachment display.

  • Phase 6: Session Chat Research & Design - Explore legacy chat implementation, design React patterns
  • Phase 7: Chat Infrastructure & State Management - Redux state, WebSocket handlers, API integration
  • Phase 8: Chat Window UI & Message Display - Modeless dialog, message list with user info
  • Phase 9: Message Composition & Sending - Text input, send functionality, real-time delivery
  • Phase 10: Read/Unread Status Management - Unread tracking, indicator badge, mark-as-read logic
  • Phase 11: Chat Finalization - Error handling, edge cases, performance optimization, UAT

v1.2 Session Attachments (Phases 12-16) - SHIPPED 2026-02-07

Show completed phases

Milestone Goal: Add file attachment capability to music sessions, allowing users to upload files from their computer and view them in the chat window with real-time synchronization across all session participants.

  • Phase 12: Attachment Research & Backend Validation - Explore legacy attachment implementation, validate existing backend infrastructure
  • Phase 13: File Upload Infrastructure - Attach button, file dialog, validation, S3 upload with progress
  • Phase 14: Chat Integration & Display - Display attachments as messages in chat window
  • Phase 15: Real-time Synchronization - WebSocket broadcast and attachment history
  • Phase 16: Attachment Finalization - Error handling, edge cases, UAT

v1.3 Session Settings Tests (Phases 17-18) - SHIPPED 2026-02-08

Show completed phases

Milestone Goal: Add test coverage for the Session Settings modal component (JKSessionSettingsModal) to enable confident changes.

  • Phase 17: Unit Tests (Jest) - Component rendering, save payload, loading state
  • Phase 18: Integration Tests (Playwright) - Settings button, save API call, cancel behavior

v1.4 Memory Leak Prevention (Phases 19-23) - SHIPPED 2026-02-10

Show completed phases

Milestone Goal: Fix memory leaks causing session screen freezes after ~10 minutes. Audit and fix cleanup patterns in VU meters, chat window, and session screen components.

  • Phase 19: Audit and Discovery - Investigate all three areas, identify actual memory leaks with evidence
  • Phase 20: VU Meter Fixes - Fix identified VU meter interval/animation cleanup issues
  • Phase 21: Chat Window Fixes - Fix identified chat WebSocket listener and state cleanup issues
  • Phase 22: Session Screen Fixes - Fix identified session screen useEffect and polling cleanup issues
  • Phase 23: Verification - Validate session stability after fixes

Phase Details

v1.0 Media Players - SHIPPED 2026-01-14

Show completed phase details

Phase 1: Backing Track Playback Monitoring

Goal: Complete the player's time display by implementing real-time monitoring of playback position and duration Depends on: Nothing (first phase) Research: Unlikely (internal patterns using established jamClient API) Plans: 1 plan

Plans:

  • 01-01: Implement 500ms polling with formatTime utility and duration initialization

Phase 2: Backing Track Seek Controls

Goal: Make the seek bar functional with drag-to-position capability Depends on: Phase 1 Research: Unlikely (building on Phase 1, same API patterns) Plans: 1 plan

Plans:

  • 02-01: Wire slider to position state, implement drag-to-seek with SessionTrackSeekMs()

Phase 3: Backing Track Finalization

Goal: Complete Backing Track with error handling, edge cases, and performance optimization Depends on: Phase 2 Research: Unlikely (error handling and optimization of established code) Plans: 3 plans

Plans:

  • 03-01: Finalize volume/loop controls and resolve UAT-003
  • 03-02: Add comprehensive error handling and loading states
  • 03-03: Performance optimization and final UAT

Phase 4: JamTrack Research & Design

Goal: Understand legacy JamTrack implementation (jQuery/CoffeeScript) and design React migration strategy Depends on: Phase 3 Research: Likely (exploring legacy jQuery/CoffeeScript implementation) Research topics: Legacy JamTrack dialog patterns, mixdown selection UI, CoffeeScript React integration patterns, jamClient JamTrack API methods Plans: 2 plans

Plans:

  • 04-01: Document legacy implementation, jamClient API, and React patterns
  • 04-02: Design React architecture, Redux state, and Phase 5 roadmap

Phase 5: JamTrack Implementation

Goal: Build JamTrack player with file opening, mixdown selection, and playback controls Depends on: Phase 4 Research: Unlikely (following patterns established in Phase 4) Plans: 5 plans

Plans:

  • 05-01: Redux infrastructure & bug fixes
  • 05-02: Async thunks & component core
  • 05-03: Playback controls & polling
  • 05-04: Mixdown selection & download UI
  • 05-05: Error handling & final UAT

v1.1 Music Session Chat (Phases 6-11) - SHIPPED 2026-01-31

Show completed phase details

Milestone Goal: Add real-time chat functionality to music sessions with modeless window, message history, read/unread tracking, and file attachment display.

Phase 6: Session Chat Research & Design

Goal: Understand legacy chat implementation and design React migration strategy Depends on: Phase 5 (previous milestone complete) Research: Likely (exploring legacy jQuery/CoffeeScript chat implementation) Research topics: Legacy chat dialog patterns, message display UI, WebSocket message handling, chat API methods, read/unread tracking patterns Plans: 2 plans

Plans:

  • 06-01: Document legacy implementation, API surface, and React patterns (3 docs: CHAT_LEGACY.md, CHAT_API.md, CHAT_REACT_PATTERNS.md)
  • 06-02: Design React architecture, Redux state, WebSocket integration, and Phases 7-11 roadmap (3 docs: CHAT_COMPONENT_DESIGN.md, CHAT_REDUX_DESIGN.md, IMPLEMENTATION_ROADMAP.md)

Phase 7: Chat Infrastructure & State Management

Goal: Build Redux state management and API integration for chat Depends on: Phase 6 Research: Unlikely (following established Redux/WebSocket patterns from JamTrack) Plans: 3 plans (TDD)

Plans:

  • 07-01: Redux Slice & Core Reducers (TDD) - sessionChatSlice with 7 reducers, message deduplication, unread tracking
  • 07-02: Async Thunks & API Integration (TDD) - REST methods, fetchChatHistory, sendMessage with optimistic updates
  • 07-03: WebSocket Integration & Selectors (TDD) - CHAT_MESSAGE handler, 8 memoized selectors, localStorage persistence

Phase 8: Chat Window UI & Message Display

Goal: Build modeless chat dialog with message list and user information display Depends on: Phase 7 Research: Unlikely (following established modal/dialog patterns) Plans: 3 plans

Plans:

  • 08-01: Chat Window Shell & WindowPortal Integration (4 tasks) - COMPLETE 2026-01-27
  • 08-02: Message List & Auto-Scroll (5 tasks, mixed TDD) - COMPLETE 2026-01-27
  • 08-03: Chat Button & Unread Badge (3-4 tasks) - COMPLETE 2026-01-27

Phase 9: Message Composition & Sending

Goal: Implement text input, send functionality, and real-time message delivery Depends on: Phase 8 Research: Unlikely (standard form patterns) Plans: 2 plans

Plans:

  • 09-01: Message Composer UI & Validation (3 tasks) - COMPLETE 2026-01-27
  • 09-02: Send Message Integration & Real-Time Delivery (3 tasks) - COMPLETE 2026-01-27

Phase 10: Read/Unread Status Management

Goal: Track unread messages and display indicator badge on chat button Depends on: Phase 9 Research: Unlikely (internal state management) Plans: 1+ plans

Plans:

  • 10-01: Read/Unread Status Validation & Testing (3 tasks) - COMPLETE 2026-01-27

Phase 11: Chat Finalization

Goal: Complete chat with error handling, edge cases, and performance optimization Depends on: Phase 10 Research: Unlikely (error handling and optimization of established code) Plans: 2 plans

Plans:

  • 11-01: Error Handling, Accessibility & Polish (3 tasks) - COMPLETE 2026-01-27
  • 11-02: UAT & Final Integration Testing - COMPLETE 2026-01-31

v1.2 Session Attachments (Phases 12-16) - SHIPPED 2026-02-07

Show completed phase details

Milestone Goal: Add file attachment capability to music sessions, allowing users to upload files from their computer and view them in the chat window with real-time synchronization across all session participants.

Phase 12: Attachment Research & Backend Validation

Goal: Validate existing backend infrastructure and understand legacy attachment patterns Depends on: Phase 11 (previous milestone complete) Research: Likely (exploring legacy attachment implementation and backend API) Research topics: Legacy AttachmentStore patterns, MusicNotation model and API, S3 upload flow, file type/size validation, attachment-chat integration Requirements: None (research phase) Plans: 2 plans

Success Criteria:

  1. Backend API contract documented (endpoints, payloads, responses)
  2. MusicNotation model capabilities validated (no code changes needed)
  3. S3 upload flow understood (signed URLs, multipart form data)
  4. Legacy file validation patterns documented (type whitelist, 10 MB limit)
  5. Integration points identified (chat window, WebSocket, Redux)

Plans:

  • 12-01-PLAN.md — Document legacy AttachmentStore and backend API contract
  • 12-02-PLAN.md — Validate backend infrastructure and design React integration strategy

Phase 13: File Upload Infrastructure

Goal: Users can select files from OS dialog and upload to S3 with validation and progress feedback Depends on: Phase 12 Research: Unlikely (following established patterns from research phase) Requirements: REQ-1.1, REQ-1.2, REQ-1.3, REQ-1.4, REQ-6.1, REQ-6.2, REQ-6.3, REQ-7.1 Plans: 3 plans

Success Criteria:

  1. User clicks Attach button in session toolbar → OS file dialog opens
  2. File selection validates type (.pdf, .xml, .mxl, .txt, .png, .jpg, .jpeg, .gif, .mp3, .wav) and size (≤ 10 MB)
  3. Invalid files show immediate error toast (type or size) without starting upload
  4. Valid files upload to S3 via MusicNotation API with multipart form data
  5. Upload progress indicator displays in chat window (percentage or spinner)
  6. Upload completes → API returns attachment metadata (id, file_name, file_url, size)
  7. Correct attachment_type set (notation/audio) based on file extension
  8. Attachment associated with correct music_session_id
  9. User can continue using app while upload is in progress (non-blocking)

Plans:

  • 13-01-PLAN.md — TDD: Attachment validation service (validateFileSize, validateFileType, getAttachmentType)
  • 13-02-PLAN.md — TDD: Redux upload state and REST helpers (uploadAttachment thunk, uploadMusicNotation)
  • 13-03-PLAN.md — Attach button integration (JKChatAttachButton + JKChatComposer integration)

Phase 14: Chat Integration & Display

Goal: Attachments display as messages in chat window with metadata and clickable links Depends on: Phase 13 Research: Unlikely (extending existing chat message display) Requirements: REQ-2.1, REQ-2.2, REQ-2.3, REQ-2.4, REQ-2.5, REQ-4.1, REQ-4.2, REQ-7.2, REQ-7.3 Plans: 3 plans

Success Criteria:

  1. Attachment appears in chat as message: "[UserName] attached [FileName]"
  2. Attachment message includes metadata: filename, file size (KB/MB), uploader, timestamp
  3. Attachment has visual indicator (icon, styling) to distinguish from text messages
  4. Filename is clickable link that opens file in new browser tab (target="_blank")
  5. Browser handles view/download based on file type (PDF viewer, image display, audio player, XML download)
  6. Attachment messages sort chronologically with regular chat messages
  7. Chat auto-scrolls when new attachment appears (reuses existing logic)
  8. Chat history includes attachments (persist across page refresh, visible when joining session)
  9. Attachment messages display correctly at different window sizes (responsive layout, long filename truncation)

Plans:

  • 14-01-PLAN.md — Attachment message display with metadata and styling
  • 14-02-PLAN.md — Clickable links and responsive layout
  • 14-03-PLAN.md — Gap closure: REST API attachment transformation (fixes REQ-2.5)

Phase 15: Real-time Synchronization

Goal: New attachments broadcast to all session participants in real-time via WebSocket Depends on: Phase 14 Research: Unlikely (extending existing WebSocket handlers) Requirements: REQ-3.1, REQ-3.2 Plans: 1 plan

Success Criteria:

  1. User uploads file → WebSocket message broadcasts to all session participants
  2. Attachment appears immediately in all users' chat windows (no manual refresh)
  3. WebSocket message includes: music_session_id, file_name, file_url, user_name, size, timestamp
  4. Optimistic update prevents duplicate messages for uploader (deduplication by msg_id)
  5. Multiple users in same session all see attachment in real-time
  6. User joining session after upload sees attachment in chat history

Plans:

  • 15-01-PLAN.md — Verify real-time sync and create integration tests

Phase 16: Attachment Finalization

Goal: Complete attachment feature with comprehensive error handling, edge cases, and UAT validation Depends on: Phase 15 Research: Unlikely (error handling and validation of established code) Requirements: REQ-5.1, REQ-5.2, REQ-5.3, REQ-5.4, REQ-5.5 Plans: 2 plans

Success Criteria:

  1. File size exceeded (>10 MB) → toast "File size exceeds 10 MB limit", upload blocked
  2. Invalid file type → toast with allowed types list, upload blocked
  3. Network error during upload → toast "Upload failed. Please try again.", optimistic message removed, retry possible
  4. Upload success → toast "File uploaded successfully" (auto-dismiss), attachment in chat
  5. Missing/deleted file on S3 → browser 404 page (no app crash)
  6. All edge cases handled: rapid clicks, disconnection, empty states, long filenames
  7. Comprehensive UAT checklist validates all 26 requirements

Plans:

  • 16-01-PLAN.md — Error handling, success toast, and S3 404 handling
  • 16-02-PLAN.md — UAT checklist and final integration testing

v1.3 Session Settings Tests (Phases 17-18) - SHIPPED 2026-02-08

Show completed phase details

Milestone Goal: Add test coverage for the Session Settings modal component (JKSessionSettingsModal) to enable confident changes.

Phase 17: Unit Tests (Jest)

Goal: Create Jest unit tests for JKSessionSettingsModal component covering critical paths Depends on: Phase 16 (previous milestone complete) Research: Unlikely (testing patterns established in codebase) Requirements: UNIT-01, UNIT-02, UNIT-03 Plans: 1 plan

Success Criteria:

  1. Test file created at jam-ui/src/components/client/__tests__/JKSessionSettingsModal.test.js
  2. UNIT-01: Test verifies modal renders with currentSession props (privacy, description values displayed)
  3. UNIT-02: Test verifies save button calls onSave with correctly transformed payload (privacy number, description)
  4. UNIT-03: Test verifies loading state disables form interactions (save button disabled, inputs disabled)
  5. All tests pass with npm run test:unit

Plans:

  • 17-01-PLAN.md — Jest unit tests for JKSessionSettingsModal - COMPLETE 2026-02-08

Phase 18: Integration Tests (Playwright)

Goal: Create Playwright integration tests for Session Settings modal user flows Depends on: Phase 17 Research: Unlikely (Playwright patterns established in codebase) Requirements: INT-01, INT-02, INT-03 Plans: 1 plan

Success Criteria:

  1. Test file created at jam-ui/test/session-settings/session-settings.spec.ts
  2. INT-01: Test verifies Settings button in session toolbar opens modal
  3. INT-02: Test verifies save settings makes PUT /sessions/{id} API call with correct data
  4. INT-03: Test verifies cancel closes modal without making API call
  5. All tests pass with npx playwright test session-settings

Plans:

  • 18-01-PLAN.md — Playwright integration tests for Session Settings modal (INT-01, INT-02, INT-03) - COMPLETE 2026-02-08

v1.4 Memory Leak Prevention (Phases 19-23) - IN PROGRESS

Milestone Goal: Fix memory leaks causing session screen freezes after ~10 minutes. Audit and fix cleanup patterns in VU meters, chat window, and session screen components.

Phase 19: Audit and Discovery

Goal: Investigate all three areas (VU meters, chat, session screen) and identify actual memory leaks with evidence Depends on: Phase 18 (previous milestone complete) Research: Complete (19-RESEARCH.md) Requirements: None (discovery phase - informs subsequent phases) Plans: 1 plan

Success Criteria:

  1. VU meter components audited - all setInterval, setTimeout, and requestAnimationFrame calls documented
  2. Chat window components audited - all WebSocket listeners and state growth patterns documented
  3. Session screen components audited - all useEffect hooks and cleanup functions documented
  4. Leak sources identified with evidence (missing cleanup, unbounded growth, etc.)
  5. Priority ranking of fixes based on severity (which leaks cause the 10-minute freeze)

Plans:

  • 19-01-PLAN.md — Comprehensive memory leak audit (VU meters, chat, session screen) - COMPLETE 2026-02-08

Phase 20: VU Meter Fixes

Goal: Fix unbounded vuStates growth by adding removeVuState cleanup function and integrating with track lifecycle Depends on: Phase 19 Research: Unlikely (fixing issues identified in Phase 19) Requirements: VUMTR-02, VUMTR-03 (VUMTR-01 deferred - throttling is performance, not memory leak) Plans: 1 plan

Success Criteria:

  1. VU meter state for a specific mixer can be removed when track leaves
  2. vuStates object stays bounded as tracks join/leave the session
  3. VU meters continue to work correctly after cleanup function is added
  4. No orphaned VU state entries accumulate over time
  5. VU meters can be shown/hidden repeatedly without memory growth

Plans:

  • 20-01-PLAN.md — Add removeVuState function and integrate with mixer lifecycle - COMPLETE 2026-02-08

Phase 21: Chat Window Fixes

Goal: Fix unbounded message accumulation and add session leave cleanup Depends on: Phase 19 Research: Unlikely (fixing issues identified in Phase 19) Requirements: CHAT-01, CHAT-02, CHAT-03 Plans: 1 plan

Success Criteria:

  1. WebSocket listeners are properly removed when chat window closes
  2. Message list has bounded growth (e.g., max messages, pagination, or virtualization)
  3. Chat window can be opened/closed repeatedly without memory growth
  4. No duplicate WebSocket listeners accumulate over time
  5. Redux state cleanup happens when session ends or user leaves

Plans:

  • 21-01-PLAN.md — Bounded message storage and session leave cleanup (CHAT-02, CHAT-03) - COMPLETE 2026-02-08

Phase 22: Session Screen Fixes

Goal: Fix identified session screen useEffect and polling cleanup issues Depends on: Phase 19 Research: Unlikely (fixing issues identified in Phase 19) Requirements: SESS-01, SESS-02, SESS-03 Plans: 1 plan

Success Criteria:

  1. All useEffect hooks that set up subscriptions/intervals have cleanup return functions
  2. All polling intervals are cleared on component unmount
  3. All event listeners have corresponding removal on cleanup
  4. Session screen can be mounted/unmounted without memory growth
  5. No orphaned polling or listeners accumulate during normal session use

Plans:

  • 22-01-PLAN.md - Callback cleanup hardening with useRef pattern (SESS-01) - COMPLETE 2026-02-08

Phase 23: Verification

Goal: Validate session stability after all fixes are applied Depends on: Phase 20, Phase 21, Phase 22 Research: Unlikely (verification of completed fixes) Requirements: VRFY-01, VRFY-02 Plans: 1 plan

Success Criteria:

  1. Session remains stable and responsive for 15+ minutes of continuous use
  2. Memory usage in browser dev tools remains stable (no unbounded growth)
  3. Multiple session join/leave cycles don't accumulate memory
  4. Chat window open/close cycles don't accumulate memory
  5. VU meter show/hide cycles don't accumulate memory
  6. All existing Playwright tests still pass (no regressions)

Plans:

  • 23-01-PLAN.md — Regression tests and manual memory verification UAT - COMPLETE 2026-02-10

Progress

Execution Order: Phases execute in numeric order: 1 → 2 → ... → 18 → 19 → 20 → 21 → 22 → 23

Phase Milestone Plans Complete Status Completed
1. Backing Track Playback Monitoring v1.0 1/1 Complete 2026-01-13
2. Backing Track Seek Controls v1.0 1/1 Complete 2026-01-14
3. Backing Track Finalization v1.0 3/3 Complete 2026-01-14
4. JamTrack Research & Design v1.0 2/2 Complete 2026-01-14
5. JamTrack Implementation v1.0 5/5 Complete 2026-01-14
6. Session Chat Research & Design v1.1 2/2 Complete 2026-01-26
7. Chat Infrastructure & State Management v1.1 3/3 Complete 2026-01-27
8. Chat Window UI & Message Display v1.1 3/3 Complete 2026-01-27
9. Message Composition & Sending v1.1 2/2 Complete 2026-01-27
10. Read/Unread Status Management v1.1 1/1 Complete 2026-01-27
11. Chat Finalization v1.1 2/2 Complete 2026-01-31
12. Attachment Research & Backend Validation v1.2 2/2 Complete 2026-02-02
13. File Upload Infrastructure v1.2 3/3 Complete 2026-02-05
14. Chat Integration & Display v1.2 3/3 Complete 2026-02-06
15. Real-time Synchronization v1.2 1/1 Complete 2026-02-06
16. Attachment Finalization v1.2 2/2 Complete 2026-02-07
17. Unit Tests (Jest) v1.3 1/1 Complete 2026-02-08
18. Integration Tests (Playwright) v1.3 1/1 Complete 2026-02-08
19. Audit and Discovery v1.4 1/1 Complete 2026-02-08
20. VU Meter Fixes v1.4 1/1 Complete 2026-02-08
21. Chat Window Fixes v1.4 1/1 Complete 2026-02-08
22. Session Screen Fixes v1.4 1/1 Complete 2026-02-08
23. Verification v1.4 1/1 Complete 2026-02-10