diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 8499c5fa8..9565266cc 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -214,8 +214,8 @@ Plans: 5. Integration points identified (chat window, WebSocket, Redux) Plans: -- [ ] 12-01: Document legacy attachment implementation and backend API surface -- [ ] 12-02: Validate backend infrastructure and design React integration strategy +- [ ] 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 @@ -318,7 +318,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → | 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 | 0/2 | Not started | - | +| 12. Attachment Research & Backend Validation | v1.2 | 0/2 | Planned | - | | 13. File Upload Infrastructure | v1.2 | 0/3 | Not started | - | | 14. Chat Integration & Display | v1.2 | 0/2 | Not started | - | | 15. Real-time Synchronization | v1.2 | 0/1 | Not started | - | diff --git a/.planning/phases/12-attachment-research-&-backend-validation/12-01-PLAN.md b/.planning/phases/12-attachment-research-&-backend-validation/12-01-PLAN.md new file mode 100644 index 000000000..493abdbf6 --- /dev/null +++ b/.planning/phases/12-attachment-research-&-backend-validation/12-01-PLAN.md @@ -0,0 +1,186 @@ +--- +phase: 12-attachment-research-&-backend-validation +plan: 01 +type: execute +wave: 1 +depends_on: [] +files_modified: + - .planning/phases/12-attachment-research-&-backend-validation/docs/ATTACHMENT_LEGACY.md + - .planning/phases/12-attachment-research-&-backend-validation/docs/ATTACHMENT_API.md +autonomous: true + +must_haves: + truths: + - "Legacy AttachmentStore upload flow is documented with code examples" + - "Backend API contract is documented with endpoints, payloads, and responses" + - "File validation rules are documented (types, sizes, error responses)" + artifacts: + - path: ".planning/phases/12-attachment-research-&-backend-validation/docs/ATTACHMENT_LEGACY.md" + provides: "Legacy implementation patterns and CoffeeScript code analysis" + min_lines: 150 + - path: ".planning/phases/12-attachment-research-&-backend-validation/docs/ATTACHMENT_API.md" + provides: "Backend API contract documentation" + min_lines: 200 + key_links: + - from: "ATTACHMENT_LEGACY.md" + to: "ATTACHMENT_API.md" + via: "API calls reference" + pattern: "POST.*music_notations" +--- + + +Document legacy attachment implementation patterns and backend API surface for file uploads. + +Purpose: Provide comprehensive reference documentation for Phase 13-16 implementation. This ensures the React port accurately replicates working patterns from the legacy CoffeeScript implementation. + +Output: Two documentation files (ATTACHMENT_LEGACY.md, ATTACHMENT_API.md) that serve as the definitive reference for attachment functionality. + + + +@/Users/nuwan/.claude/get-shit-done/workflows/execute-plan.md +@/Users/nuwan/.claude/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md +@.planning/phases/12-attachment-research-&-backend-validation/12-RESEARCH.md + +# Source files to analyze +@web/app/assets/javascripts/react-components/stores/AttachmentStore.js.coffee +@web/app/controllers/api_music_notations_controller.rb +@ruby/lib/jam_ruby/models/music_notation.rb +@ruby/lib/jam_ruby/uploaders/music_notation_uploader.rb + + + + + + Task 1: Document Legacy AttachmentStore Implementation + .planning/phases/12-attachment-research-&-backend-validation/docs/ATTACHMENT_LEGACY.md + +Create comprehensive documentation of the legacy CoffeeScript AttachmentStore: + +1. **File Structure Section:** + - Document file location and purpose + - List all public methods and their signatures + - Document Reflux store pattern used + +2. **Upload Flow Section:** + - Step-by-step breakdown of uploadFiles() method + - FormData construction (files[], session_id, attachment_type) + - Ajax request configuration (processData: false, contentType: false) + - Success/error callback handling + +3. **Client-Side Validation Section:** + - File size check implementation (10 MB limit) + - File type validation (extension whitelist) + - Error message generation + - How validation errors are surfaced to UI + +4. **Attachment Type Detection Section:** + - How 'notation' vs 'audio' type is determined + - File extension to type mapping logic + +5. **Integration Points Section:** + - How AttachmentStore connects to ChatStore + - Event emission patterns (trigger) + - How UI components consume attachment state + +Include actual CoffeeScript code snippets translated to JavaScript for clarity. + + +File exists and contains: +- grep "Upload Flow" ATTACHMENT_LEGACY.md +- grep "FormData" ATTACHMENT_LEGACY.md +- grep "10.*MB" ATTACHMENT_LEGACY.md +- grep -c "```" ATTACHMENT_LEGACY.md shows 5+ code blocks + + +ATTACHMENT_LEGACY.md exists with 150+ lines covering all five sections, including translated code examples. + + + + + Task 2: Document Backend API Contract + .planning/phases/12-attachment-research-&-backend-validation/docs/ATTACHMENT_API.md + +Create comprehensive API documentation for the attachment endpoints: + +1. **Endpoint Overview Table:** + - POST /api/music_notations (upload) + - GET /api/music_notations/:id (signed URL) + - DELETE /api/music_notations/:id (remove) + - Include HTTP methods, auth requirements, response codes + +2. **POST /api/music_notations - Upload:** + - Request format: multipart/form-data + - Required fields: files[], session_id, attachment_type + - Optional fields: any additional params + - Response 201: JSON array of created attachments [{id, file_name, file_url}] + - Response 413: File too large + - Response 422: Validation errors + - Include curl example command + +3. **GET /api/music_notations/:id - Download URL:** + - Request: Just the ID in path + - Response 200: JSON with signed S3 URL + - URL expiration time (from CarrierWave config) + - Include curl example + +4. **DELETE /api/music_notations/:id - Remove:** + - Request: ID in path + - Response 204: Success (no content) + - Response 403: Not authorized + - Response 404: Not found + +5. **File Validation Rules:** + - Server-side extension whitelist (from MusicNotationUploader) + - Size limits (server-side vs client-side) + - Content-type handling + +6. **Chat Message Integration:** + - How upload automatically creates ChatMessage + - ChatMessage fields populated (purpose, attachment_id, attachment_type, attachment_name) + - WebSocket broadcast triggered after upload + +Include actual code references from api_music_notations_controller.rb. + + +File exists and contains: +- grep "POST /api/music_notations" ATTACHMENT_API.md +- grep "GET /api/music_notations" ATTACHMENT_API.md +- grep "DELETE /api/music_notations" ATTACHMENT_API.md +- grep "curl" ATTACHMENT_API.md +- grep "ChatMessage" ATTACHMENT_API.md + + +ATTACHMENT_API.md exists with 200+ lines covering all six sections, including curl examples and code references. + + + + + + +Both documentation files created in docs/ subdirectory: +- ls .planning/phases/12-attachment-research-&-backend-validation/docs/ +Should show: ATTACHMENT_LEGACY.md, ATTACHMENT_API.md + +Content verification: +- wc -l docs/*.md shows 150+ lines for LEGACY, 200+ lines for API +- Both files contain working code examples +- API documentation includes all three endpoints + + + +1. ATTACHMENT_LEGACY.md documents complete upload flow from legacy CoffeeScript +2. ATTACHMENT_API.md documents all three endpoints with request/response formats +3. File validation rules (types, sizes) are clearly specified in both documents +4. Code examples are included and accurate +5. Documentation is sufficient for implementing React port without referencing legacy code directly + + + +After completion, create `.planning/phases/12-attachment-research-&-backend-validation/12-01-SUMMARY.md` + diff --git a/.planning/phases/12-attachment-research-&-backend-validation/12-02-PLAN.md b/.planning/phases/12-attachment-research-&-backend-validation/12-02-PLAN.md new file mode 100644 index 000000000..518fed23f --- /dev/null +++ b/.planning/phases/12-attachment-research-&-backend-validation/12-02-PLAN.md @@ -0,0 +1,219 @@ +--- +phase: 12-attachment-research-&-backend-validation +plan: 02 +type: execute +wave: 1 +depends_on: [] +files_modified: + - .planning/phases/12-attachment-research-&-backend-validation/docs/BACKEND_VALIDATION.md + - .planning/phases/12-attachment-research-&-backend-validation/docs/REACT_INTEGRATION_DESIGN.md +autonomous: true + +must_haves: + truths: + - "MusicNotation model S3 integration is validated (CarrierWave, signed URLs)" + - "WebSocket attachment metadata fields are documented (attachment_id, attachment_type, attachment_name)" + - "React integration points are identified with specific file paths and modifications" + artifacts: + - path: ".planning/phases/12-attachment-research-&-backend-validation/docs/BACKEND_VALIDATION.md" + provides: "Backend infrastructure validation report" + min_lines: 150 + - path: ".planning/phases/12-attachment-research-&-backend-validation/docs/REACT_INTEGRATION_DESIGN.md" + provides: "React integration strategy and component design" + min_lines: 200 + key_links: + - from: "REACT_INTEGRATION_DESIGN.md" + to: "sessionChatSlice.js" + via: "Redux state extensions" + pattern: "upload.*state" + - from: "REACT_INTEGRATION_DESIGN.md" + to: "JKChatComposer.js" + via: "Attach button integration" + pattern: "attach.*button" +--- + + +Validate backend infrastructure capabilities and design the React integration strategy for attachments. + +Purpose: Confirm zero backend changes are needed and create a concrete integration plan that maps exactly how attachment functionality will be added to existing jam-ui components. + +Output: Two documentation files (BACKEND_VALIDATION.md, REACT_INTEGRATION_DESIGN.md) that validate infrastructure readiness and provide implementation blueprints. + + + +@/Users/nuwan/.claude/get-shit-done/workflows/execute-plan.md +@/Users/nuwan/.claude/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md +@.planning/phases/12-attachment-research-&-backend-validation/12-RESEARCH.md + +# Backend validation sources +@ruby/lib/jam_ruby/models/music_notation.rb +@ruby/lib/jam_ruby/models/chat_message.rb +@ruby/lib/jam_ruby/uploaders/music_notation_uploader.rb +@ruby/lib/jam_ruby/message_factory.rb + +# React integration targets +@jam-ui/src/components/client/chat/JKChatComposer.js +@jam-ui/src/components/client/chat/JKChatMessage.js +@jam-ui/src/components/client/JKSessionScreen.js +@jam-ui/src/store/features/sessionChatSlice.js +@jam-ui/src/services/rest.js + + + + + + Task 1: Validate Backend Infrastructure + .planning/phases/12-attachment-research-&-backend-validation/docs/BACKEND_VALIDATION.md + +Create a validation report confirming backend readiness: + +1. **MusicNotation Model Validation:** + - Confirm CarrierWave mount_uploader configuration + - Verify S3 storage configuration (fog_credentials pattern) + - Document signed URL generation method + - Confirm file_name and file attributes exist + - Include actual code snippets from music_notation.rb + +2. **MusicNotationUploader Validation:** + - Document extension_white_list (exact list) + - Confirm store_dir configuration + - Note any size limits at uploader level + - Compare against requirements whitelist: + Requirements: .pdf, .xml, .mxl, .txt, .png, .jpg, .jpeg, .gif, .mp3, .wav + Backend: pdf png jpg jpeg gif xml mxl txt wav flac ogg aiff aifc au + - FLAG MISMATCH: .mp3 in requirements but NOT in backend + - Recommendation: Backend update needed OR requirements clarification + +3. **ChatMessage Attachment Integration:** + - Confirm attachment_id, attachment_type, attachment_name fields exist + - Document how ChatMessage is created after MusicNotation upload + - Verify send_chat_msg includes attachment fields in WebSocket broadcast + - Include code snippet from chat_message.rb showing field usage + +4. **WebSocket Message Structure:** + - Document chat_message Protocol Buffer fields for attachments + - Show exact field names: purpose, attachment_id, attachment_type, attachment_name + - Confirm these are populated in message_factory.rb + - Include the chat_message method signature and attachment params + +5. **Validation Summary:** + - Checklist of all validated capabilities + - List of any gaps or issues found + - Recommendation: "Zero backend changes needed" OR list required changes + + +File exists and contains: +- grep "CarrierWave" BACKEND_VALIDATION.md +- grep "extension_white_list" BACKEND_VALIDATION.md +- grep "attachment_id" BACKEND_VALIDATION.md +- grep "WebSocket" BACKEND_VALIDATION.md +- grep -i "validation summary" BACKEND_VALIDATION.md + + +BACKEND_VALIDATION.md exists with 150+ lines, confirms backend infrastructure status, and clearly states whether backend changes are needed. + + + + + Task 2: Design React Integration Strategy + .planning/phases/12-attachment-research-&-backend-validation/docs/REACT_INTEGRATION_DESIGN.md + +Create detailed integration design for React implementation: + +1. **Component Modifications Overview Table:** + | Component | Current State | Modifications Needed | Phase | + | JKChatComposer.js | Text + Send | Add attach button | 13 | + | JKChatMessage.js | Text display | Handle attachment messages | 14 | + | JKSessionScreen.js | WebSocket handler | Add attachment fields | 14-15 | + | sessionChatSlice.js | Chat state | Add upload state | 13 | + | rest.js | API helpers | Add upload function | 13 | + +2. **New Component: JKChatAttachButton** + - Purpose: Hidden file input + visible button trigger + - Props: onFileSelect(file), disabled, isUploading + - File input accept attribute value (from requirements) + - Reset input value after selection (allow re-selecting same file) + - Include component skeleton code + +3. **Redux State Extensions (sessionChatSlice.js):** + - New state: uploadState { status: 'idle'|'uploading'|'error', progress: number, error: string|null } + - New reducer: setUploadStatus(status, progress, error) + - New reducer: clearUploadError() + - New async thunk: uploadAttachment(file, sessionId) + - Include state shape and reducer signatures + +4. **REST Helper Addition (rest.js):** + - uploadMusicNotation(formData): Uses native fetch, NOT apiFetch (FormData needs browser headers) + - getMusicNotationUrl(id): Uses apiFetch for signed URL + - Include function signatures with JSDoc comments + +5. **WebSocket Handler Updates (JKSessionScreen.js):** + - Current handleChatMessage transformation + - Additional fields to extract: purpose, attachment_id, attachment_type, attachment_name + - Updated message object shape + - Include code diff showing additions + +6. **JKChatMessage Attachment Display:** + - Condition: message.attachmentId exists + - Render: "[UserName] attached: [FileName]" with link + - Click handler: Fetch signed URL, open in new tab + - Include component modification sketch + +7. **File Validation Service:** + - New file: services/attachmentValidation.js (optional - could be inline) + - validateFileSize(file, maxSizeBytes): returns { valid, error } + - validateFileType(file, allowedTypes): returns { valid, error } + - getAttachmentType(filename): returns 'notation' | 'audio' + - Include function implementations + +8. **Implementation Sequence:** + - Phase 13: Attach button, validation, upload, progress (REQ-1.*, REQ-6.*, REQ-7.1) + - Phase 14: Message display, download links, history (REQ-2.*, REQ-4.*, REQ-7.2-3) + - Phase 15: WebSocket sync, deduplication (REQ-3.*) + - Phase 16: Error handling, edge cases, UAT (REQ-5.*) + + +File exists and contains: +- grep "JKChatAttachButton" REACT_INTEGRATION_DESIGN.md +- grep "sessionChatSlice" REACT_INTEGRATION_DESIGN.md +- grep "uploadMusicNotation" REACT_INTEGRATION_DESIGN.md +- grep "handleChatMessage" REACT_INTEGRATION_DESIGN.md +- grep "Phase 13" REACT_INTEGRATION_DESIGN.md + + +REACT_INTEGRATION_DESIGN.md exists with 200+ lines, provides concrete component designs, Redux state shape, and clear implementation sequence for Phases 13-16. + + + + + + +Both documentation files created in docs/ subdirectory: +- ls .planning/phases/12-attachment-research-&-backend-validation/docs/ +Should show: BACKEND_VALIDATION.md, REACT_INTEGRATION_DESIGN.md (plus files from Plan 01) + +Content verification: +- wc -l docs/*.md shows 150+ lines for VALIDATION, 200+ lines for DESIGN +- Backend validation includes clear "changes needed" or "no changes needed" statement +- React design includes code examples for all integration points + + + +1. BACKEND_VALIDATION.md confirms MusicNotation model works with S3 (CarrierWave validated) +2. BACKEND_VALIDATION.md documents WebSocket attachment metadata fields +3. BACKEND_VALIDATION.md clearly states backend change requirements (if any) +4. REACT_INTEGRATION_DESIGN.md identifies all 5 integration points with file paths +5. REACT_INTEGRATION_DESIGN.md includes component/Redux code sketches +6. REACT_INTEGRATION_DESIGN.md maps requirements to implementation phases +7. Documentation is sufficient to begin Phase 13 implementation without additional research + + + +After completion, create `.planning/phases/12-attachment-research-&-backend-validation/12-02-SUMMARY.md` +