---
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"
---

<objective>
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.
</objective>

<execution_context>
@/Users/nuwan/.claude/get-shit-done/workflows/execute-plan.md
@/Users/nuwan/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.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
</context>

<tasks>

<task type="auto">
  <name>Task 1: Validate Backend Infrastructure</name>
  <files>.planning/phases/12-attachment-research-&-backend-validation/docs/BACKEND_VALIDATION.md</files>
  <action>
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
  </action>
  <verify>
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
  </verify>
  <done>
BACKEND_VALIDATION.md exists with 150+ lines, confirms backend infrastructure status, and clearly states whether backend changes are needed.
  </done>
</task>

<task type="auto">
  <name>Task 2: Design React Integration Strategy</name>
  <files>.planning/phases/12-attachment-research-&-backend-validation/docs/REACT_INTEGRATION_DESIGN.md</files>
  <action>
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.*)
  </action>
  <verify>
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
  </verify>
  <done>
REACT_INTEGRATION_DESIGN.md exists with 200+ lines, provides concrete component designs, Redux state shape, and clear implementation sequence for Phases 13-16.
  </done>
</task>

</tasks>

<verification>
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
</verification>

<success_criteria>
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
</success_criteria>

<output>
After completion, create `.planning/phases/12-attachment-research-&-backend-validation/12-02-SUMMARY.md`
</output>
