# Claude Instructions for WLED Screen Controller Server

## Project Structure

- `src/wled_controller/main.py` — FastAPI application entry point
- `src/wled_controller/api/routes/` — REST API endpoints (one file per entity)
- `src/wled_controller/api/schemas/` — Pydantic request/response models (one file per entity)
- `src/wled_controller/core/` — Core business logic (capture, devices, audio, processing, automations)
- `src/wled_controller/storage/` — Data models (dataclasses) and JSON persistence stores
- `src/wled_controller/utils/` — Utility functions (logging, monitor detection)
- `src/wled_controller/static/` — Frontend files (TypeScript, CSS, locales)
- `src/wled_controller/templates/` — Jinja2 HTML templates
- `config/` — Configuration files (YAML)
- `data/` — Runtime data (JSON stores, persisted state)

## Entity & Storage Pattern

Each entity follows: dataclass model (`storage/`) + JSON store (`storage/*_store.py`) + Pydantic schemas (`api/schemas/`) + routes (`api/routes/`).

## Authentication

Server uses API key authentication via Bearer token in `Authorization` header.

- Config: `config/default_config.yaml` under `auth.api_keys`
- Env var: `WLED_AUTH__API_KEYS`
- Dev key: `development-key-change-in-production`

## Common Tasks

### Adding a new API endpoint

1. Create route file in `api/routes/`
2. Define request/response schemas in `api/schemas/`
3. Register the router in `main.py`
4. Restart the server
5. Test via `/docs` (Swagger UI)

### Adding a new field to existing API

1. Update Pydantic schema in `api/schemas/`
2. Update corresponding dataclass in `storage/`
3. Update backend logic to populate the field
4. Restart the server
5. Update frontend to display the new field
6. Rebuild bundle: `cd server && npm run build`

### Adding translations

1. Add keys to `static/locales/en.json`, `static/locales/ru.json`, and `static/locales/zh.json`
2. Add `data-i18n` attributes to HTML elements in `templates/`
3. Use `t('key')` in TypeScript modules (`static/js/`)
4. No server restart needed (frontend only), but rebuild bundle if JS changed

### Modifying display/monitor detection

1. Update functions in `utils/monitor_names.py` or `core/screen_capture.py`
2. Restart the server
3. Test with `GET /api/v1/config/displays`

## Testing

```bash
cd server && pytest                    # Run all tests
cd server && pytest --cov              # With coverage report
cd server && pytest tests/test_api.py  # Single test file
```

Tests are in `server/tests/`. Config in `pyproject.toml` under `[tool.pytest]`.

## Frontend Conventions

For all frontend conventions (CSS variables, UI patterns, modals, localization, icons, bundling), see [contexts/frontend.md](../contexts/frontend.md).

## Server Operations

For restart procedures, server modes, and demo mode checklist, see [contexts/server-operations.md](../contexts/server-operations.md).