# OpenCode.md - Chatterbox UI Development Guide

## Build & Run Commands
```bash
# Backend (FastAPI)
pip install -r backend/requirements.txt
uvicorn backend.app.main:app --reload --host 0.0.0.0 --port 8000

# Frontend
python frontend/start_dev_server.py  # Serves on port 8001

# Run backend tests
python backend/run_api_test.py

# Run frontend tests
npm test

# Run specific frontend test
npx jest frontend/tests/api.test.js

# Run Gradio interface
python gradio_app.py

# Run utility scripts
python cbx-audiobook.py --list-speakers  # List available speakers
python cbx-audiobook.py sample-audiobook.txt --speaker <speaker_id>  # Generate audiobook
python cbx-dialog-generate.py sample-dialog.md  # Generate dialog
```

## Code Style Guidelines

### Python
- Use type hints (from typing import Optional, List, Dict, etc.)
- Error handling: Use try/except with specific exceptions
- Async/await for I/O operations
- Docstrings for functions and classes
- PEP 8 naming: snake_case for functions/variables, PascalCase for classes

### JavaScript
- ES6 modules with import/export
- Async/await for API calls
- JSDoc comments for functions
- Error handling: try/catch with detailed error messages
- Camel case for variables/functions (camelCase)

## Import Structure
- When importing from scripts, use `import import_helper` first to fix Python path
- Backend modules use relative imports within the app package
- Services are in `backend.app.services`
- Models are in `backend.app.models`
- Configuration is in `backend.app.config`

## Project Structure
- Backend: FastAPI with service-oriented architecture
- Frontend: Vanilla JS with modular design (api.js, app.js, config.js)
- Speaker data in YAML format with WAV samples
- Output directories: dialog_output/, single_output/, tts_outputs/

## Common Issues
- Import errors: Make sure to use `import import_helper` in scripts
- Speaker samples must be WAV format in `speaker_data/speaker_samples/`
- TTS model requires GPU (CUDA) or Apple Silicon (MPS)