mirror of
https://github.com/Monadical-SAS/reflector.git
synced 2025-12-22 21:29:05 +00:00
llm instructions
This commit is contained in:
Igor Loskutov
345
CODER_BRIEFING.md
Normal file
345
CODER_BRIEFING.md
Normal file
@@ -0,0 +1,345 @@
|
||||
# Multi-Provider Video Platform Implementation - Coder Briefing
|
||||
|
||||
## Your Mission
|
||||
|
||||
Implement multi-provider video platform support in Reflector, allowing the system to work with both Whereby and Daily.co video conferencing providers. The goal is to abstract the current Whereby-only implementation and add Daily.co as a second provider, with the ability to switch between them via environment variables.
|
||||
|
||||
**Branch:** `igor/dailico-2` (you're already on it)
|
||||
|
||||
**Estimated Time:** 12-16 hours (senior engineer)
|
||||
|
||||
**Complexity:** Medium-High (requires careful integration with existing codebase)
|
||||
|
||||
---
|
||||
|
||||
## What You Have
|
||||
|
||||
### 1. **PLAN.md** - Your Technical Specification (2,452 lines)
|
||||
- Complete step-by-step implementation guide
|
||||
- All code examples you need
|
||||
- Architecture diagrams and design rationale
|
||||
- Testing strategy and success metrics
|
||||
- **Read this first** to understand the overall approach
|
||||
|
||||
### 2. **IMPLEMENTATION_GUIDE.md** - Your Practical Guide
|
||||
- What to copy vs. adapt vs. rewrite
|
||||
- Common pitfalls and how to avoid them
|
||||
- Verification checklists for each phase
|
||||
- Decision trees for implementation choices
|
||||
- **Use this as your day-to-day reference**
|
||||
|
||||
### 3. **Reference Implementation** - `./reflector-dailyco-reference/`
|
||||
- Working implementation from 2.5 months ago
|
||||
- Good architecture and patterns
|
||||
- **BUT:** 91 commits behind current main, DO NOT merge directly
|
||||
- Use for inspiration and code patterns only
|
||||
|
||||
---
|
||||
|
||||
## Critical Context: Why Not Just Merge?
|
||||
|
||||
The reference branch (`origin/igor/feat-dailyco`) was started on August 1, 2025 and is now severely diverged from main:
|
||||
|
||||
- **91 commits behind main**
|
||||
- Main has 12x more changes (45,840 insertions vs 3,689)
|
||||
- Main added: calendar integration, webhooks, full-text search, React Query migration, security fixes
|
||||
- Reference removed: features that main still has and needs
|
||||
|
||||
**Merging would be a disaster.** We're implementing fresh on current main, using the reference for validated patterns.
|
||||
|
||||
---
|
||||
|
||||
## High-Level Approach
|
||||
|
||||
### Phase 1: Analysis (2 hours)
|
||||
- Study current Whereby integration
|
||||
- Define abstraction requirements
|
||||
- Create standard data models
|
||||
|
||||
### Phase 2: Abstraction Layer (4-5 hours)
|
||||
- Build platform abstraction (base class, registry, factory)
|
||||
- Extract Whereby into the abstraction
|
||||
- Update database schema (add `platform` field)
|
||||
- Integrate into rooms.py **without breaking calendar/webhooks**
|
||||
|
||||
### Phase 3: Daily.co Implementation (4-5 hours)
|
||||
- Implement Daily.co client
|
||||
- Add webhook handler
|
||||
- Create frontend components (rewrite API calls for React Query)
|
||||
- Add recording processing
|
||||
|
||||
### Phase 4: Testing (2-3 hours)
|
||||
- Unit tests for platform abstraction
|
||||
- Integration tests for webhooks
|
||||
- Manual testing with both providers
|
||||
|
||||
---
|
||||
|
||||
## Key Files You'll Touch
|
||||
|
||||
### Backend (New)
|
||||
```
|
||||
server/reflector/video_platforms/
|
||||
├── __init__.py
|
||||
├── base.py ← Abstract base class
|
||||
├── models.py ← Platform, MeetingData, VideoPlatformConfig
|
||||
├── registry.py ← Platform registration system
|
||||
├── factory.py ← Client creation and config
|
||||
├── whereby.py ← Whereby client wrapper
|
||||
├── daily.py ← Daily.co client
|
||||
└── mock.py ← Mock client for testing
|
||||
|
||||
server/reflector/views/daily.py ← Daily.co webhooks
|
||||
server/tests/test_video_platforms.py ← Platform tests
|
||||
server/tests/test_daily_webhook.py ← Webhook tests
|
||||
```
|
||||
|
||||
### Backend (Modified - Careful!)
|
||||
```
|
||||
server/reflector/settings.py ← Add Daily.co settings
|
||||
server/reflector/db/rooms.py ← Add platform field, PRESERVE calendar fields
|
||||
server/reflector/db/meetings.py ← Add platform field
|
||||
server/reflector/views/rooms.py ← Integrate abstraction, PRESERVE calendar/webhooks
|
||||
server/reflector/worker/process.py ← Add process_recording_from_url task
|
||||
server/reflector/app.py ← Register daily router
|
||||
server/env.example ← Document new env vars
|
||||
```
|
||||
|
||||
### Frontend (New)
|
||||
```
|
||||
www/app/[roomName]/components/
|
||||
├── RoomContainer.tsx ← Platform router
|
||||
├── DailyRoom.tsx ← Daily.co component (rewrite API calls!)
|
||||
└── WherebyRoom.tsx ← Extract existing logic
|
||||
```
|
||||
|
||||
### Frontend (Modified)
|
||||
```
|
||||
www/app/[roomName]/page.tsx ← Use RoomContainer
|
||||
www/package.json ← Add @daily-co/daily-js
|
||||
```
|
||||
|
||||
### Database
|
||||
```
|
||||
server/migrations/versions/XXXXXX_add_platform_support.py ← Generate fresh migration
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Critical Warnings ⚠️
|
||||
|
||||
### 1. **DO NOT Copy Database Migrations**
|
||||
The reference migration has the wrong `down_revision` and is based on old schema.
|
||||
```bash
|
||||
# Instead:
|
||||
cd server
|
||||
uv run alembic revision -m "add_platform_support"
|
||||
# Then edit the generated file
|
||||
```
|
||||
|
||||
### 2. **DO NOT Remove Main's Features**
|
||||
Main has calendar integration, webhooks, ICS sync that reference doesn't have.
|
||||
When modifying `rooms.py`, only change meeting creation logic, preserve everything else.
|
||||
|
||||
### 3. **DO NOT Copy Frontend API Calls**
|
||||
Reference uses old OpenAPI client. Main uses React Query.
|
||||
Check how main currently makes API calls and replicate that pattern.
|
||||
|
||||
### 4. **DO NOT Copy package.json/migrations**
|
||||
These files are severely outdated in reference.
|
||||
|
||||
### 5. **Preserve Type Safety**
|
||||
Use `TYPE_CHECKING` imports to avoid circular dependencies:
|
||||
```python
|
||||
from typing import TYPE_CHECKING
|
||||
if TYPE_CHECKING:
|
||||
from reflector.db.rooms import Room
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How to Start
|
||||
|
||||
### Day 1 Morning: Setup & Understanding (2-3 hours)
|
||||
```bash
|
||||
# 1. Verify you're on the right branch
|
||||
git branch
|
||||
# Should show: igor/dailico-2
|
||||
|
||||
# 2. Read the docs (in order)
|
||||
# - PLAN.md (skim to understand scope, read Phase 1 carefully)
|
||||
# - IMPLEMENTATION_GUIDE.md (read fully, bookmark it)
|
||||
|
||||
# 3. Study current Whereby integration
|
||||
cat server/reflector/views/rooms.py | grep -A 20 "whereby"
|
||||
cat www/app/[roomName]/page.tsx
|
||||
|
||||
# 4. Check reference implementation structure
|
||||
ls -la reflector-dailyco-reference/server/reflector/video_platforms/
|
||||
```
|
||||
|
||||
### Day 1 Afternoon: Phase 1 Execution (2-3 hours)
|
||||
```bash
|
||||
# 5. Copy video_platforms directory from reference
|
||||
cp -r reflector-dailyco-reference/server/reflector/video_platforms/ \
|
||||
server/reflector/
|
||||
|
||||
# 6. Review and fix imports
|
||||
cd server
|
||||
uv run ruff check reflector/video_platforms/
|
||||
|
||||
# 7. Add settings to settings.py (see PLAN.md Phase 2.7)
|
||||
|
||||
# 8. Test imports work
|
||||
uv run python -c "from reflector.video_platforms import create_platform_client; print('OK')"
|
||||
```
|
||||
|
||||
### Day 2: Phase 2 - Database & Integration (4-5 hours)
|
||||
```bash
|
||||
# 9. Generate migration
|
||||
uv run alembic revision -m "add_platform_support"
|
||||
# Edit the file following PLAN.md Phase 2.8
|
||||
|
||||
# 10. Update Room/Meeting models
|
||||
# Add platform field, PRESERVE all existing fields
|
||||
|
||||
# 11. Integrate into rooms.py
|
||||
# Carefully modify meeting creation, preserve calendar/webhooks
|
||||
|
||||
# 12. Add Daily.co webhook handler
|
||||
cp reflector-dailyco-reference/server/reflector/views/daily.py \
|
||||
server/reflector/views/
|
||||
# Register in app.py
|
||||
```
|
||||
|
||||
### Day 3: Phase 3 - Frontend & Testing (4-5 hours)
|
||||
```bash
|
||||
# 13. Create frontend components
|
||||
mkdir -p www/app/[roomName]/components
|
||||
|
||||
# 14. Add Daily.co dependency
|
||||
cd www
|
||||
pnpm add @daily-co/daily-js@^0.81.0
|
||||
|
||||
# 15. Create RoomContainer, DailyRoom, WherebyRoom
|
||||
# IMPORTANT: Rewrite API calls using React Query patterns
|
||||
|
||||
# 16. Regenerate types
|
||||
pnpm openapi
|
||||
|
||||
# 17. Copy and adapt tests
|
||||
cp reflector-dailyco-reference/server/tests/test_*.py server/tests/
|
||||
|
||||
# 18. Run tests
|
||||
cd server
|
||||
REDIS_HOST=localhost \
|
||||
CELERY_BROKER_URL=redis://localhost:6379/1 \
|
||||
uv run pytest tests/test_video_platforms.py -v
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
After implementation, all of these must pass:
|
||||
|
||||
**Backend:**
|
||||
- [ ] `cd server && uv run ruff check .` passes
|
||||
- [ ] `uv run alembic upgrade head` works cleanly
|
||||
- [ ] `uv run pytest tests/test_video_platforms.py` passes
|
||||
- [ ] Can import: `from reflector.video_platforms import create_platform_client`
|
||||
- [ ] Settings has all Daily.co variables
|
||||
|
||||
**Frontend:**
|
||||
- [ ] `cd www && pnpm lint` passes
|
||||
- [ ] No TypeScript errors
|
||||
- [ ] `pnpm openapi` generates platform field
|
||||
- [ ] No `@ts-ignore` for platform field
|
||||
|
||||
**Integration:**
|
||||
- [ ] Whereby meetings still work (existing flow unchanged)
|
||||
- [ ] Calendar/webhook features still work in rooms.py
|
||||
- [ ] env.example documents all new variables
|
||||
|
||||
---
|
||||
|
||||
## When You're Stuck
|
||||
|
||||
### Check These Resources:
|
||||
1. **PLAN.md** - Detailed code examples for your exact scenario
|
||||
2. **IMPLEMENTATION_GUIDE.md** - Common pitfalls section
|
||||
3. **Reference code** - See how it was solved before
|
||||
4. **Git diff** - Compare reference to your implementation
|
||||
|
||||
### Compare Files:
|
||||
```bash
|
||||
# See what reference did
|
||||
diff reflector-dailyco-reference/server/reflector/views/rooms.py \
|
||||
server/reflector/views/rooms.py
|
||||
|
||||
# See what changed in main since reference branch
|
||||
git log --oneline --since="2025-08-01" -- server/reflector/views/rooms.py
|
||||
```
|
||||
|
||||
### Common Issues:
|
||||
- **Circular imports:** Use `TYPE_CHECKING` pattern
|
||||
- **Tests fail with postgres error:** Use `REDIS_HOST=localhost` env vars
|
||||
- **Frontend API calls broken:** Check current React Query patterns in main
|
||||
- **Migrations fail:** Ensure you generated fresh, not copied
|
||||
|
||||
---
|
||||
|
||||
## Success Looks Like
|
||||
|
||||
When you're done:
|
||||
- ✅ All tests pass
|
||||
- ✅ Linting passes
|
||||
- ✅ Can create Whereby meetings (unchanged behavior)
|
||||
- ✅ Can create Daily.co meetings (with env vars)
|
||||
- ✅ Calendar/webhooks still work
|
||||
- ✅ Frontend has no TypeScript errors
|
||||
- ✅ Platform selection via environment variables works
|
||||
|
||||
---
|
||||
|
||||
## Communication
|
||||
|
||||
If you need clarification on requirements, have questions about architecture decisions, or find issues with the spec, document them clearly with:
|
||||
- What you expected
|
||||
- What you found
|
||||
- Your proposed solution
|
||||
|
||||
The PLAN.md document is comprehensive but you may find edge cases. Use your engineering judgment and document decisions.
|
||||
|
||||
---
|
||||
|
||||
## Final Notes
|
||||
|
||||
**This is not a simple copy-paste job.** You're doing careful integration work where you need to:
|
||||
- Understand the abstraction pattern (PLAN.md)
|
||||
- Preserve all of main's features
|
||||
- Adapt reference code to current patterns
|
||||
- Think about edge cases and testing
|
||||
|
||||
Take your time with Phase 2 (rooms.py integration) - that's where most bugs will come from if you accidentally break calendar/webhook features.
|
||||
|
||||
**Good luck! You've got comprehensive specs, working reference code, and a clean starting point. You can do this.**
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
```bash
|
||||
# Your workspace
|
||||
├── PLAN.md ← Complete technical spec (read first)
|
||||
├── IMPLEMENTATION_GUIDE.md ← Practical guide (bookmark this)
|
||||
├── CODER_BRIEFING.md ← This file
|
||||
└── reflector-dailyco-reference/ ← Reference implementation (inspiration only)
|
||||
|
||||
# Key commands
|
||||
cd server && uv run ruff check . # Lint backend
|
||||
cd www && pnpm lint # Lint frontend
|
||||
cd server && uv run alembic revision -m "..." # Create migration
|
||||
cd www && pnpm openapi # Regenerate types
|
||||
cd server && uv run pytest -v # Run tests
|
||||
```
|
||||
Reference in New Issue
Block a user