rondevu-server/CLAUDE.md

Rondevu Server Development Guidelines

WebRTC Signaling Best Practices

ICE Candidate Storage

IMPORTANT: Store ICE candidates as raw JSON without enforcing structure.

When handling ICE candidates in the signaling server:

• ✅ DO store candidates as JSON.stringify(candidate) in the database
• ✅ DO retrieve candidates as JSON.parse(candidate) from the database
• ✅ DO use generic types like any in TypeScript for candidate data
• ❌ DON'T define strict types for ICE candidate structure
• ❌ DON'T validate or modify candidate properties
• ❌ DON'T assume you know what properties clients will send

Why? The server is just a relay - it doesn't need to understand the candidate structure. Different browsers and future WebRTC versions may include different properties. By keeping the server agnostic, we maintain maximum compatibility.

Server Role Filtering

The server MUST filter ICE candidates by role:

• Offerers receive only answerer candidates (WHERE role = 'answerer')
• Answerers receive only offerer candidates (WHERE role = 'offerer')

This prevents peers from receiving their own candidates, which would cause connection failures.

Security

• Always validate authentication tokens before allowing operations
• Verify ownership before allowing modifications
• Rate limit API endpoints to prevent abuse
• Clean up expired offers regularly

Performance

• Use transactions for batch operations (SQLite)
• Index frequently queried columns (offer_id, role, created_at)
• Set appropriate TTLs for offers
• Implement pagination for large result sets

Code Quality

• Handle errors gracefully with informative HTTP status codes
• Log important events for debugging
• Use TypeScript types for API contracts, but keep data types generic
• Write tests for critical paths