# CLAUDE.md

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

**📌 PRIMARY WORKFLOW**: @.cursor/rules/agent_workflow.mdc - Single source of truth for all development patterns

## Project Context

Trax is a production-ready media transcription platform within the my-ai-projects ecosystem. It uses Whisper for transcription with domain-specific AI enhancement, optimized for M3 MacBook performance.

**Core Architecture**: Download-first media processing → Whisper transcription → DeepSeek enhancement → Multi-format export

## Core Development Principles

From @.cursor/rules/agent_workflow.mdc:
- **Keep It Simple**: One workflow, clear patterns, no complex hierarchies
- **Context First**: Always understand what you're building before coding
- **Test First**: Write tests before implementation
- **Quality Built-In**: Enforce standards as you go, not as separate phases
- **Progressive Enhancement**: Start simple, add complexity only when needed

## Quick Decision Tree

### Request Type → Action
- **Question/How-to**: Answer directly with code examples
- **Implementation Request**: Follow TDD workflow below
- **Server/Command**: Execute appropriate command
- **Analysis/Review**: Examine code and provide feedback

## Enhanced TDD Workflow with Planning

From @.cursor/rules/agent_workflow.mdc with spec-driven development:
```
1. Plan (Spec-First) → 2. Understand Requirements → 3. Write Tests → 4. Implement → 5. Validate → 6. Done
```

### MANDATORY: Plan Mode First
- **Always enter plan mode** before implementing any feature
- Create detailed plan in `.claude/tasks/<feature-name>.md`
- Break down into phases with clear deliverables
- Update plan as you progress
- Plan should include: requirements, architecture, test strategy, implementation phases

## Essential Commands

### Environment Setup
```bash
# Navigate to project and activate environment
cd /Users/enias/projects/my-ai-projects/apps/trax
source .venv/bin/activate

# Install/update dependencies with uv (10-100x faster than pip)
uv pip install -e ".[dev]"
```

### Step 1: Plan Mode (Spec-First)
```bash
# Enter plan mode and create detailed spec
# In Claude Code: Shift+Tab twice to enter plan mode
# Create plan at: .claude/tasks/<feature-name>.md
# Include: requirements, phases, architecture, test strategy
```

### Step 2: Understand Requirements
```bash
# Get task details and context
task-master show <task-id>                      # Get task details
./scripts/tm_context.sh get <task-id>          # Get cached context
```

### Step 3: Write Tests First  
```bash
# Run tests with coverage
uv run pytest                                    # All tests
uv run pytest tests/test_transcription_service.py -v  # Specific test file
uv run pytest -k "test_multi_pass" -v           # Tests matching pattern
uv run pytest -m unit                           # Unit tests only
```

### Step 4: Implement Minimal Code
```bash
# Development server
uv run python src/main.py                       # Start development server
```

### Step 5: Validate Quality
```bash
# Code quality
uv run black src/ tests/                        # Format code
uv run ruff check --fix src/ tests/            # Lint and auto-fix
uv run mypy src/                               # Type checking
./scripts/validate_loc.sh                       # Check file sizes

# Database operations
uv run alembic upgrade head                     # Apply migrations
uv run alembic revision --autogenerate -m "description"  # Create migration
```

### Step 6: Complete Task & Update Plan
```bash
# Update plan with results
# Document in .claude/tasks/<feature-name>.md what was completed
task-master set-status --id=<task-id> --status=done
./scripts/tm_cache.sh update <task-id>
./scripts/update_changelog.sh <task-id> --type=task
```

### CLI Commands
```bash
# Standard transcription
uv run python -m src.cli.main transcribe audio.mp3         # Basic transcription
uv run python -m src.cli.main transcribe audio.mp3 --v2    # AI-enhanced (99% accuracy)

# Enhanced CLI (recommended for production)
uv run python -m src.cli.enhanced_cli transcribe audio.mp3 --multi-pass --confidence-threshold 0.9
uv run python -m src.cli.enhanced_cli transcribe lecture.mp3 --domain academic --diarize
uv run python -m src.cli.enhanced_cli batch /path/to/files --parallel 8

# YouTube processing
uv run python -m src.cli.main youtube https://youtube.com/watch?v=VIDEO_ID
uv run python -m src.cli.main batch-urls urls.txt --output-dir transcripts/
```

## Project Structure

```
trax/
├── src/                    # Main application code
│   ├── services/          # Core business logic (protocol-based)
│   │   ├── protocols.py  # Service interfaces
│   │   ├── transcription_service.py
│   │   ├── multi_pass_transcription.py
│   │   ├── domain_enhancement.py
│   │   ├── batch_processor.py
│   │   └── export_service.py
│   ├── database/          # Data layer
│   │   ├── models.py     # Core SQLAlchemy models
│   │   ├── v2_models.py  # Extended v2 features
│   │   └── repositories/ # Data access patterns
│   ├── cli/              # Command-line interfaces
│   │   ├── main.py       # Standard CLI
│   │   └── enhanced_cli.py # Advanced CLI with progress
│   ├── api/              # REST API endpoints (future)
│   ├── utils/            # Shared utilities
│   └── config.py         # Configuration (inherits from ../../.env)
├── tests/                 # Test suite
│   ├── fixtures/         # Real test media files
│   │   ├── audio/       # Sample audio files
│   │   └── video/       # Sample video files
│   ├── conftest.py      # Pytest configuration
│   └── test_*.py        # Test files
├── scripts/              # Utility scripts
│   ├── validate_loc.sh  # File size validation
│   ├── tm_context.sh    # Task context caching
│   └── update_changelog.sh
├── .cursor/rules/        # Cursor AI rules
│   ├── agent_workflow.mdc # Main workflow (single source)
│   └── *.mdc            # Supporting rules
├── .taskmaster/          # Task Master configuration
│   ├── tasks/           # Task files
│   ├── docs/           # PRD and documentation
│   └── config.json     # AI model configuration
├── .venv/               # Virtual environment (gitignored)
├── pyproject.toml       # Package configuration (uv)
├── CLAUDE.md           # This file
└── AGENTS.md           # Development rules
```

## High-Level Architecture

### Service Layer (`src/services/`)
The core processing logic uses **protocol-based design** for modularity:

```python
# All services implement protocols for clean interfaces
from src.services.protocols import TranscriptionProtocol, EnhancementProtocol

# Key services:
- transcription_service.py     # Whisper integration (20-70x faster on M3)
- multi_pass_transcription.py  # Iterative refinement for 99.5% accuracy
- domain_enhancement.py         # AI enhancement with domain adaptation
- batch_processor.py           # Parallel processing (8 workers optimal)
- export_service.py            # Multi-format export (TXT, SRT, VTT, JSON)
```

### Performance Optimizations
- **Memory Management**: `memory_optimization.py` - Automatic cleanup, chunked processing
- **Speed**: `speed_optimization.py` - M3-specific optimizations, distil-large-v3 model
- **Domain Adaptation**: `domain_adaptation.py` - Technical/academic/medical terminology
- **Caching**: Multi-layer caching with different TTLs per data type

### Database Layer (`src/database/`)
PostgreSQL with SQLAlchemy ORM:
- `models.py` - Core models (MediaFile, Transcript, Enhancement)
- `v2_models.py` - Extended models for v2 features
- `repositories/` - Data access patterns with protocol compliance

### Testing Strategy (`tests/`)
**Real-file testing** - No mocks, actual media files:
```python
# tests/conftest.py provides real test fixtures
@pytest.fixture
def sample_audio_5s():
    return Path("tests/fixtures/audio/sample_5s.wav")
```

## Configuration System

Inherits from root project `.env` at `../../.env`:
```python
from src.config import config

# All API keys available as attributes
api_key = config.DEEPSEEK_API_KEY
services = config.get_available_ai_services()
```

## File Organization Rules

### File Size Limits
- **Code Files** (.py, .ts, .js):
  - Target: Under 300 lines
  - Maximum: 350 lines (only with clear justification)
  - Exceptions: Complex algorithms, comprehensive test suites
- **Documentation** (.md, .txt):
  - Target: Under 550 lines
  - Maximum: 600 lines for essential docs (CLAUDE.md, README.md)
- **Single Responsibility**: One service/component per file
- **Protocol-Based**: Use typing.Protocol for service interfaces

### Example Structure
```python
# transcription_service.py - Only transcription logic (50-100 lines)
class TranscriptionService(TranscriptionProtocol):
    async def transcribe(self, file_path: Path) -> TranscriptResult:
        # Focused implementation
        pass

# audio_processor.py - Only audio processing logic (50-100 lines)
class AudioProcessor(AudioProtocol):
    def process_audio(self, audio_data) -> ProcessedAudio:
        # Focused implementation
        pass
```

## Key Implementation Patterns

### 1. Download-First Architecture
```python
# Always download media before processing
downloader = MediaDownloadService()
local_path = await downloader.download(url)
result = await transcriber.transcribe(local_path)
```

### 2. Test-First Development
```python
# Write test that defines the interface
def test_transcription_service():
    service = TranscriptionService()
    result = service.transcribe_audio("test.wav")
    assert result.text is not None
    assert result.confidence > 0.8
# THEN implement to make test pass
```

### 3. Multi-Pass Refinement (v2)
```python
# Iterative improvement for 99.5% accuracy
service = MultiPassTranscriptionService()
result = await service.transcribe_with_passes(
    file_path, 
    min_confidence=0.9,
    max_passes=3
)
```

### 4. Batch Processing
```python
# Optimized for M3 with 8 parallel workers
processor = BatchProcessor(max_workers=8)
results = await processor.process_batch(file_paths)
```

## Performance Targets
- 5-minute audio: <30 seconds processing
- 95% accuracy (v1), 99% accuracy (v2)
- <1 second CLI response time
- Support files up to 500MB
- 8 parallel workers on M3

## Current Implementation Status

### ✅ Completed
- Whisper transcription with distil-large-v3
- DeepSeek AI enhancement
- Multi-pass refinement system
- Domain adaptation (technical/academic/medical)
- Speaker diarization
- Batch processing with parallel workers
- Export to TXT/SRT/VTT/JSON
- PostgreSQL database with migrations
- Comprehensive test suite
- Enhanced CLI with progress tracking

### 🚧 In Progress
- Research agent UI (Streamlit)
- Vector search integration (ChromaDB/FAISS)
- Advanced speaker profiles

## Task Master Integration

Task Master commands for project management:
```bash
# View current tasks
task-master list
task-master next
task-master show <id>

# Update task status
task-master set-status --id=<id> --status=done
task-master update-subtask --id=<id> --prompt="implementation notes"
```

See `.taskmaster/CLAUDE.md` for full Task Master workflow integration.

## Common Workflows

### Adding New Feature
```bash
# 1. Get task details
task-master show <task-id>

# 2. Write tests first
# Create test file with comprehensive test cases

# 3. Implement minimal code
# Write code to pass tests

# 4. Validate quality
uv run pytest && uv run black src/ tests/ && uv run ruff check --fix

# 5. Complete
task-master set-status --id=<task-id> --status=done
```

### Fixing Bug
```bash
# 1. Reproduce the bug with a failing test

# 2. Fix the code to make test pass

# 3. Validate
uv run pytest && quality checks

# 4. Update status
task-master set-status --id=<task-id> --status=done
```

## Common Issues & Solutions

### Database Connection
```bash
# Check PostgreSQL status
pg_ctl status -D /usr/local/var/postgres
# Start if needed
pg_ctl start -D /usr/local/var/postgres
```

### FFmpeg Missing
```bash
# Install via Homebrew
brew install ffmpeg
```

### API Key Issues
```bash
# Verify keys loaded
uv run python -c "from src.config import config; config.display_config_status()"
```

### Missing .env
Check `../../.env` exists in root project

### Import Errors
Run `uv pip install -e ".[dev]"`

### Type Errors
Run `uv run mypy src/`

### Formatting Issues
Run `uv run black src/ tests/`

## Anti-Patterns to Avoid

### ❌ DON'T: Skip Understanding
- Jumping straight to coding without requirements
- Not reading task details or context
- Ignoring existing code patterns

### ❌ DON'T: Skip Testing
- Writing code before tests
- Incomplete test coverage
- Not testing edge cases

### ❌ DON'T: Ignore Quality
- Large, monolithic code files (>350 lines without justification)
- Documentation files exceeding 600 lines
- Poor formatting or linting errors
- Not following project patterns

### ❌ DON'T: Over-Engineer
- Complex abstractions when simple works
- Multiple layers when one suffices
- Premature optimization

## Success Metrics

### Code Quality
- All tests pass
- Code files under LOC limits (300 lines target, 350 max)
- Documentation under 550 lines (600 max for essentials)
- No linting errors
- Consistent formatting

### Development Speed
- Clear understanding of requirements
- Tests written first
- Minimal viable implementation
- Quick validation cycles

### Maintainability
- Small, focused files
- Clear separation of concerns
- Consistent patterns
- Good test coverage

## Memory Management

### Claude Code Memory (# shortcut)
Use `#` to save important context:
```
#remember Using distil-large-v3 for M3 optimization
#remember PostgreSQL 15+ with JSONB for flexible storage
#remember 8 parallel workers optimal for batch processing
```

### Memory Levels
- **Project-level**: Saved to `.claude.md` in project root
- **User-level**: Saved globally across all projects
- **Session-level**: Saved to `.claude/context/session.md`

### What to Remember
- **Architecture decisions**: Model choices, database patterns
- **Performance targets**: Processing times, accuracy goals
- **Configuration**: API keys, service endpoints
- **Conventions**: Naming patterns, file organization
- **Dependencies**: Required packages, versions

## Cursor Rules

Key rules from `.cursor/rules/`:
- **agent_workflow.mdc** - Simplified TDD workflow (single source of truth)
- **progressive-enhancement.mdc** - Iterative refinement approach
- **utc-timestamps.mdc** - Timestamp handling standards
- **low-loc.mdc** - Low Line of Code patterns (300 line target for code, 550 for docs)

## Parallel Development

Git worktrees enable parallel development across features:
- **Setup**: Run `.claude/scripts/setup_worktrees.sh` 
- **5 Default Worktrees**: features, testing, docs, performance, bugfix
- **Switch**: Use `/Users/enias/projects/my-ai-projects/apps/trax-worktrees/switch.sh`
- **Status**: Check all with `trax-worktrees/status.sh`
- **Full Guide**: [Parallel Development Workflow](.claude/docs/parallel-development-workflow.md)

---
*Architecture Version: 2.0 | Python 3.11+ | PostgreSQL 15+ | FFmpeg 6.0+*

**Remember**: Keep it simple. Follow @.cursor/rules/agent_workflow.mdc: Understand → Test → Implement → Validate → Complete.