rehearshalhub/DEBUGGING_GUIDE.md

# Debugging Guide for Comment Waveform Integration

## Current Status

The code changes have been implemented, but the functionality may not be working as expected. This guide will help identify and fix the issues.

## Debugging Steps

### 1. Check Browser Console

Open the browser developer tools (F12) and check the Console tab:

**What to look for:**
- TypeScript errors (red text)
- API request failures
- JavaScript errors
- Debug logs from our console.log statements

**Expected debug output:**
```
Creating comment with timestamp: 45.678
Comment created successfully
Comments data: [ {...}, {...} ]
Processing comment: abc-123 timestamp: 45.678 avatar: https://example.com/avatar.jpg
Adding marker at time: 45.678
```

### 2. Check Network Requests

In browser developer tools, go to the Network tab:

**Requests to check:**
1. `POST /api/v1/songs/{song_id}/comments` - Comment creation
   - Check request payload includes `timestamp`
   - Check response status is 201 Created
   - Check response includes `author_avatar_url`

2. `GET /api/v1/songs/{song_id}/comments` - Comment listing
   - Check response includes `author_avatar_url` for each comment
   - Check response includes `timestamp` for new comments
   - Check old comments have `timestamp: null`

### 3. Verify Database Schema

Check if the timestamp column exists in the database:

```sql
SELECT column_name, data_type
FROM information_schema.columns 
WHERE table_name = 'song_comments';
```

**Expected columns:**
- `id` (uuid)
- `song_id` (uuid)
- `author_id` (uuid)
- `body` (text)
- `timestamp` (float) ← **This is critical**
- `created_at` (timestamp)

**If timestamp column is missing:**
```sql
ALTER TABLE song_comments ADD COLUMN timestamp FLOAT;
```

### 4. Check API Schema Compatibility

Verify that the API schema matches what the frontend expects:

**API Schema** (`api/src/rehearsalhub/schemas/comment.py`):
```python
class SongCommentRead(BaseModel):
    id: uuid.UUID
    song_id: uuid.UUID
    body: str
    author_id: uuid.UUID
    author_name: str
    author_avatar_url: str | None  # ← Must be present
    timestamp: float | None         # ← Must be present
    created_at: datetime
```

**Frontend Interface** (`web/src/pages/SongPage.tsx`):
```typescript
interface SongComment {
  id: string;
  song_id: string;
  body: string;
  author_id: string;
  author_name: string;
  author_avatar_url: string | null;  # ← Must match API
  created_at: string;
  timestamp: number | null;           # ← Must match API
}
```

### 5. Test Comment Creation Flow

**Step-by-step test:**

1. **Play audio**: Start playing a song and let it progress to a specific time (e.g., 30 seconds)
2. **Create comment**: Type a comment and click "Post"
3. **Check console**: Should see `Creating comment with timestamp: 30.123`
4. **Check network**: POST request should include `{"body": "test", "timestamp": 30.123}`
5. **Check response**: Should be 201 Created with comment data including timestamp
6. **Check markers**: Should see debug log `Adding marker at time: 30.123`
7. **Visual check**: Marker should appear on waveform at correct position

### 6. Common Issues and Fixes

#### Issue: No markers appear on waveform
**Possible causes:**
1. **Timestamp is null**: Old comments don't have timestamps
2. **API not returning avatar_url**: Check network response
3. **TypeScript error**: Check browser console
4. **Waveform not ready**: Check if `isReady` is true in useWaveform

**Fixes:**
- Ensure new comments are created with timestamps
- Verify API returns `author_avatar_url`
- Check TypeScript interface matches API response

#### Issue: Markers appear but no avatars
**Possible causes:**
1. **API not returning avatar_url**: Check network response
2. **User has no avatar**: Falls back to placeholder (expected)
3. **Invalid avatar URL**: Check network tab for 404 errors

**Fixes:**
- Verify `author_avatar_url` is included in API response
- Check user records have valid avatar URLs
- Ensure fallback placeholder works

#### Issue: Markers in wrong position
**Possible causes:**
1. **Incorrect timestamp**: Check what timestamp is sent to API
2. **Waveform duration mismatch**: Check `wavesurfer.getDuration()`
3. **Position calculation error**: Check `useWaveform.ts`

**Fixes:**
- Verify timestamp matches playhead position
- Check waveform duration is correct
- Debug position calculation

### 7. Database Migration Check

If comments fail to create with timestamps:

1. **Check migration status:**
```bash
# Check alembic version
docker-compose exec api alembic current

# Check if timestamp column exists
psql -U rehearsalhub -d rehearsalhub -c "\d song_comments"
```

2. **Apply migration if needed:**
```bash
# Run all pending migrations
docker-compose exec api alembic upgrade head

# Or apply specific migration
docker-compose exec api alembic upgrade 0004
```

3. **Manual fix if migration fails:**
```sql
ALTER TABLE song_comments ADD COLUMN timestamp FLOAT;
```

### 8. Verify Backend Code

Check that the backend properly handles the timestamp:

**Router** (`api/src/rehearsalhub/routers/songs.py`):
```python
@router.post("/songs/{song_id}/comments")
async def create_comment(
    song_id: uuid.UUID,
    data: SongCommentCreate,  # ← Should include timestamp
    # ...
):
    comment = await repo.create(
        song_id=song_id, 
        author_id=current_member.id, 
        body=data.body, 
        timestamp=data.timestamp  # ← Should be passed
    )
```

**Schema** (`api/src/rehearsalhub/schemas/comment.py`):
```python
class SongCommentCreate(BaseModel):
    body: str
    timestamp: float | None = None  # ← Must allow None for backward compatibility
```

## Expected Behavior After Fix

1. ✅ **New comments capture timestamp**: When creating a comment while audio is playing, the current playhead position is captured
2. ✅ **Markers show user avatars**: Waveform markers display the comment author's avatar when available
3. ✅ **Markers at correct position**: Markers appear on waveform at the exact time the comment was created
4. ✅ **Marker interaction works**: Clicking markers scrolls comment section to corresponding comment
5. ✅ **Backward compatibility**: Old comments without timestamps still work (no markers shown)

## Troubleshooting Checklist

- [ ] Check browser console for errors
- [ ] Verify network requests/response structure
- [ ] Confirm database has timestamp column
- [ ] Check API schema matches frontend interface
- [ ] Test comment creation with debug logs
- [ ] Verify marker positioning calculation
- [ ] Check avatar URL handling

## Additional Debugging Tips

1. **Add more debug logs**: Temporarily add console.log statements to track data flow
2. **Test with Postman**: Manually test API endpoints to isolate frontend/backend issues
3. **Check CORS**: Ensure no CORS issues are preventing requests
4. **Verify authentication**: Ensure user is properly authenticated
5. **Check waveform initialization**: Ensure waveform is properly initialized before adding markers