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

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

# 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
</context>

<tasks>

<task type="auto">
  <name>Task 1: Document Legacy AttachmentStore Implementation</name>
  <files>.planning/phases/12-attachment-research-&-backend-validation/docs/ATTACHMENT_LEGACY.md</files>
  <action>
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.
  </action>
  <verify>
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
  </verify>
  <done>
ATTACHMENT_LEGACY.md exists with 150+ lines covering all five sections, including translated code examples.
  </done>
</task>

<task type="auto">
  <name>Task 2: Document Backend API Contract</name>
  <files>.planning/phases/12-attachment-research-&-backend-validation/docs/ATTACHMENT_API.md</files>
  <action>
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.
  </action>
  <verify>
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
  </verify>
  <done>
ATTACHMENT_API.md exists with 200+ lines covering all six sections, including curl examples and code references.
  </done>
</task>

</tasks>

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

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

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