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

19 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 (in progress)

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) - IN PROGRESS

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

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) - IN PROGRESS

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)

Progress

Execution Order: Phases execute in numeric order: 1 → 2 → ... → 16 → 17 → 18

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 0/1 Pending —