reflector/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Reflector is an AI-powered audio transcription and meeting analysis platform with real-time processing capabilities. The system consists of:

• Frontend: Next.js 14 React application (www/) with Chakra UI, real-time WebSocket integration
• Backend: Python FastAPI server (server/) with async database operations and background processing
• Processing: GPU-accelerated ML pipeline for transcription, diarization, summarization via Modal.com
• Infrastructure: Redis, PostgreSQL/SQLite, Celery workers, WebRTC streaming

Development Commands

Backend (Python) - cd server/

Setup and Dependencies:

# Install dependencies
uv sync

# Database migrations (first run or schema changes)
uv run alembic upgrade head

# Start services
docker compose up -d redis

Development:

# Start FastAPI server
uv run -m reflector.app --reload

# Start Celery worker for background tasks
uv run celery -A reflector.worker.app worker --loglevel=info

# Start Celery beat scheduler (optional, for cron jobs)
uv run celery -A reflector.worker.app beat

Testing:

# Run all tests with coverage
uv run pytest

# Run specific test file
uv run pytest tests/test_transcripts.py

# Run tests with verbose output
uv run pytest -v

Process Audio Files:

# Process local audio file manually
uv run python -m reflector.tools.process path/to/audio.wav

Frontend (Next.js) - cd www/

Setup:

# Install dependencies
yarn install

# Copy configuration templates
cp .env_template .env
cp config-template.ts config.ts

Development:

# Start development server
yarn dev

# Generate TypeScript API client from OpenAPI spec
yarn openapi

# Lint code
yarn lint

# Format code
yarn format

# Build for production
yarn build

Docker Compose (Full Stack)

# Start all services
docker compose up -d

# Start specific services
docker compose up -d redis server worker

Architecture Overview

Backend Processing Pipeline

The audio processing follows a modular pipeline architecture:

1. Audio Input: WebRTC streaming, file upload, or cloud recording ingestion
2. Chunking: Audio split into processable segments (AudioChunkerProcessor)
3. Transcription: Whisper or Modal.com GPU processing (AudioTranscriptAutoProcessor)
4. Diarization: Speaker identification (AudioDiarizationAutoProcessor)
5. Text Processing: Formatting, translation, topic detection
6. Summarization: AI-powered summaries and title generation
7. Storage: Database persistence with optional S3 backend

Database Models

Core entities:

• transcript: Main table with processing results, summaries, topics, participants
• meeting: Live meeting sessions with consent management
• room: Virtual meeting spaces with configuration
• recording: Audio/video file metadata and processing status

API Structure

All endpoints prefixed /v1/:

• transcripts/ - CRUD operations for transcripts
• transcripts_audio/ - Audio streaming and download
• transcripts_webrtc/ - Real-time WebRTC endpoints
• transcripts_websocket/ - WebSocket for live updates
• meetings/ - Meeting lifecycle management
• rooms/ - Virtual room management

Frontend Architecture

• App Router: Next.js 14 with route groups for organization
• State: React Context pattern, no Redux
• Real-time: WebSocket integration for live transcription updates
• Auth: NextAuth.js with Authentik OAuth/OIDC provider
• UI: Chakra UI components with Tailwind CSS utilities

Key Configuration

Environment Variables

Backend (server/.env):

• DATABASE_URL - Database connection string
• REDIS_URL - Redis broker for Celery
• MODAL_TOKEN_ID, MODAL_TOKEN_SECRET - Modal.com GPU processing
• WHEREBY_API_KEY - Video platform integration
• REFLECTOR_AUTH_BACKEND - Authentication method (none, jwt)

Frontend (www/.env):

• NEXTAUTH_URL, NEXTAUTH_SECRET - Authentication configuration
• NEXT_PUBLIC_REFLECTOR_API_URL - Backend API endpoint
• REFLECTOR_DOMAIN_CONFIG - Feature flags and domain settings

Testing Strategy

• Backend: pytest with async support, HTTP client mocking, audio processing tests
• Frontend: No current test suite - opportunities for Jest/React Testing Library
• Coverage: Backend maintains test coverage reports in htmlcov/

GPU Processing

Modal.com integration for scalable ML processing:

• Deploy changes: modal run server/gpu/path/to/model.py
• Requires Modal account with REFLECTOR_GPU_APIKEY secret
• Fallback to local processing when Modal unavailable

Common Issues

• Permissions: Browser microphone access required in System Preferences
• Audio Routing: Use BlackHole (Mac) for merging multiple audio sources
• WebRTC: Ensure proper CORS configuration for cross-origin streaming
• Database: Run uv run alembic upgrade head after pulling schema changes