# Requirements Archive: v1.2 Session Attachments

**Archived:** 2026-02-07
**Status:** SHIPPED

This is the archived requirements specification for v1.2.
For current requirements, see `.planning/REQUIREMENTS.md` (created for next milestone).

---

# Requirements: v1.2 Session Attachments

**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.

**Last Updated:** 2026-02-07

---

## 1. File Upload & Validation

### REQ-1.1: Attach Button in Session Toolbar
**Priority:** P0 (Critical)
**Status:** COMPLETE
**Description:** Add "Attach" button to session toolbar (top navigation) that opens native OS file dialog when clicked.

---

### REQ-1.2: File Type Validation
**Priority:** P0 (Critical)
**Status:** COMPLETE
**Description:** Restrict file uploads to approved file types only (.pdf, .xml, .mxl, .txt, .png, .jpg, .jpeg, .gif, .mp3, .wav).

---

### REQ-1.3: File Size Limit
**Priority:** P0 (Critical)
**Status:** COMPLETE
**Description:** Enforce 10 MB maximum file size for uploads.

---

### REQ-1.4: Upload Progress Indicator
**Priority:** P1 (High)
**Status:** COMPLETE
**Description:** Display upload progress in chat window while file is uploading.

---

## 2. Chat Integration & Display

### REQ-2.1: Attachment Message Format
**Priority:** P0 (Critical)
**Status:** COMPLETE
**Description:** Display file attachments as messages in chat window with format "[UserName] attached [FileName]".

---

### REQ-2.2: Attachment Metadata Display
**Priority:** P1 (High)
**Status:** COMPLETE
**Description:** Show relevant metadata about attached files (filename, size, uploader, timestamp).

---

### REQ-2.3: Attachment Icon/Indicator
**Priority:** P2 (Medium)
**Status:** COMPLETE
**Description:** Visual indicator that distinguishes attachment messages from text messages.

---

### REQ-2.4: Clickable Attachment Links
**Priority:** P0 (Critical)
**Status:** COMPLETE
**Description:** Users can click attachment to view/download file in new browser tab.

---

### REQ-2.5: Chat History Includes Attachments
**Priority:** P0 (Critical)
**Status:** COMPLETE
**Description:** Attachment messages persist in chat history across page refreshes and when joining session.

---

## 3. Real-time Communication

### REQ-3.1: WebSocket Attachment Broadcast
**Priority:** P0 (Critical)
**Status:** COMPLETE
**Description:** New attachments broadcast to all session participants in real-time via WebSocket.

---

### REQ-3.2: Attachment Deduplication
**Priority:** P1 (High)
**Status:** COMPLETE
**Description:** Prevent duplicate attachment messages when receiving via WebSocket.

---

## 4. File Viewing & Download

### REQ-4.1: Open in New Browser Tab
**Priority:** P0 (Critical)
**Status:** COMPLETE
**Description:** Clicking attachment opens file in new browser tab for viewing/downloading.

---

### REQ-4.2: Browser-Native Handling
**Priority:** P0 (Critical)
**Status:** COMPLETE
**Description:** Leverage browser's built-in view/download capabilities for different file types.

---

## 5. Error Handling & User Feedback

### REQ-5.1: File Size Exceeded Error
**Priority:** P0 (Critical)
**Status:** COMPLETE
**Description:** Show clear error toast "File size exceeds 10 MB limit" when user selects oversized file.

---

### REQ-5.2: Invalid File Type Error
**Priority:** P0 (Critical)
**Status:** COMPLETE
**Description:** Show clear error toast with allowed types list when user selects unsupported file type.

---

### REQ-5.3: Upload Network Error
**Priority:** P0 (Critical)
**Status:** COMPLETE
**Description:** Handle network failures with toast "Upload failed. Please try again." and allow retry.

---

### REQ-5.4: Upload Success Feedback
**Priority:** P1 (High)
**Status:** COMPLETE
**Description:** Confirm successful upload with toast "File uploaded successfully" (auto-dismiss).

---

### REQ-5.5: Missing/Deleted File Handling
**Priority:** P2 (Medium)
**Status:** COMPLETE
**Description:** Gracefully handle case where attachment file no longer exists on S3 with toast notification.

---

## 6. Backend Integration

### REQ-6.1: Use Existing MusicNotation API
**Priority:** P0 (Critical)
**Status:** COMPLETE
**Description:** Use existing backend infrastructure for file uploads (no backend changes required).

---

### REQ-6.2: Attachment Type Classification
**Priority:** P1 (High)
**Status:** COMPLETE
**Description:** Set correct attachment_type field (notation/audio) based on file extension.

---

### REQ-6.3: Session Association
**Priority:** P0 (Critical)
**Status:** COMPLETE
**Description:** Associate attachment with correct music_session_id.

---

## 7. Performance & UX

### REQ-7.1: Non-blocking Upload
**Priority:** P1 (High)
**Status:** COMPLETE
**Description:** File upload happens in background without blocking UI.

---

### REQ-7.2: Chat Auto-scroll with Attachments
**Priority:** P1 (High)
**Status:** COMPLETE
**Description:** Chat window auto-scrolls when new attachment appears.

---

### REQ-7.3: Responsive Layout
**Priority:** P2 (Medium)
**Status:** COMPLETE
**Description:** Attachment messages display correctly at different window sizes with filename truncation.

---

## Traceability

| Requirement | Phase | Status |
|-------------|-------|--------|
| REQ-1.1 | Phase 13 | Complete |
| REQ-1.2 | Phase 13 | Complete |
| REQ-1.3 | Phase 13 | Complete |
| REQ-1.4 | Phase 13 | Complete |
| REQ-2.1 | Phase 14 | Complete |
| REQ-2.2 | Phase 14 | Complete |
| REQ-2.3 | Phase 14 | Complete |
| REQ-2.4 | Phase 14 | Complete |
| REQ-2.5 | Phase 14 | Complete |
| REQ-3.1 | Phase 15 | Complete |
| REQ-3.2 | Phase 15 | Complete |
| REQ-4.1 | Phase 14 | Complete |
| REQ-4.2 | Phase 14 | Complete |
| REQ-5.1 | Phase 16 | Complete |
| REQ-5.2 | Phase 16 | Complete |
| REQ-5.3 | Phase 16 | Complete |
| REQ-5.4 | Phase 16 | Complete |
| REQ-5.5 | Phase 16 | Complete |
| REQ-6.1 | Phase 13 | Complete |
| REQ-6.2 | Phase 13 | Complete |
| REQ-6.3 | Phase 13 | Complete |
| REQ-7.1 | Phase 13 | Complete |
| REQ-7.2 | Phase 14 | Complete |
| REQ-7.3 | Phase 14 | Complete |

**Coverage:** 24/24 requirements complete (100%)

---

## Milestone Summary

**Shipped:** 24 of 24 requirements
**Adjusted:** None
**Dropped:** None

---
*Archived: 2026-02-07 as part of v1.2 milestone completion*
