# Agent Guidelines for Chatterbox-UI

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

# Frontend
npm test  # Run all frontend tests
npx jest frontend/tests/api.test.js  # Run single test file

# Alternative UI
python gradio_app.py  # Run Gradio interface
```

## Code Style Guidelines

### Python
- Use type hints (from typing import Optional, List, etc.)
- Exception handling: Use try/except with specific exceptions
- Async/await for FastAPI endpoints and services
- Docstrings for functions and classes
- Use pathlib.Path for file operations
- Organize code into routers, models, and services

### JavaScript
- ES6 modules with import/export
- JSDoc comments for functions
- Async/await for API calls
- Proper error handling with detailed messages
- Descriptive variable and function names
- Consistent error handling pattern in API calls

### Error Handling
- Backend: Raise specific exceptions, use try/except/finally
- Frontend: Use try/catch with detailed error messages
- Always include error details in API responses

### Naming Conventions
- Python: snake_case for variables/functions, PascalCase for classes
- JavaScript: camelCase for variables/functions
- Descriptive, intention-revealing names

### Architecture Notes
- Backend: FastAPI on port 8000, structured as routers/models/services
- Frontend: Vanilla JS (ES6+) on port 8001, modular design
- API Base URL: http://localhost:8000/api
- Speaker data in YAML format at speaker_data/speakers.yaml