# Claude Instructions for WLED Screen Controller Server

## Development Workflow

### Server Restart Policy

**IMPORTANT**: When making changes to server code (Python files in `src/wled_controller/`), you MUST restart the server if it's currently running to ensure the changes take effect.

#### When to restart:
- After modifying API routes (`api/routes.py`, `api/schemas.py`)
- After updating core logic (`core/*.py`)
- After changing configuration (`config.py`)
- After modifying utilities (`utils/*.py`)
- After updating data models or database schemas

#### How to check if server is running:
```bash
# Look for running Python processes with wled_controller
ps aux | grep wled_controller
# Or check for processes listening on port 8080
netstat -an | grep 8080
```

#### How to restart:
1. Stop the current server (if running as background task, use TaskStop with the task ID)
2. Start a new server instance:
   ```bash
   cd server && python -m wled_controller.main
   ```
3. Verify the new server started successfully by checking the output logs

#### Files that DON'T require restart:
- Static files (`static/*.html`, `static/*.css`, `static/*.js`) - these are served directly
- Locale files (`static/locales/*.json`) - loaded by frontend
- Documentation files (`*.md`)
- Configuration files in `config/` if server supports hot-reload (check implementation)

### Testing Changes

After restarting the server with new code:
1. Test the modified endpoints/functionality
2. Check browser console for any JavaScript errors
3. Verify API responses match updated schemas
4. Test with different locales if i18n was modified

## Project Structure Notes

- `src/wled_controller/main.py` - FastAPI application entry point
- `src/wled_controller/api/` - REST API endpoints and schemas
- `src/wled_controller/core/` - Core business logic (screen capture, WLED client, processing)
- `src/wled_controller/utils/` - Utility functions (logging, monitor detection)
- `src/wled_controller/static/` - Frontend files (HTML, CSS, JS, locales)
- `config/` - Configuration files (YAML)
- `data/` - Runtime data (devices.json, persistence)

## Common Tasks

### Adding a new API endpoint:
1. Add route to `api/routes.py`
2. Define request/response schemas in `api/schemas.py`
3. **Restart the server**
4. Test the endpoint via `/docs` (Swagger UI)

### Adding a new field to existing API:
1. Update Pydantic schema in `api/schemas.py`
2. Update corresponding dataclass (if applicable)
3. Update backend logic to populate the field
4. **Restart the server**
5. Update frontend to display the new field

### 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`

### Modifying server login:
1. Update the logic.
2. **Restart the server**

### Adding translations:
1. Add keys to `static/locales/en.json` and `static/locales/ru.json`
2. Add `data-i18n` attributes to HTML elements in `static/index.html`
3. Use `t('key')` function in `static/app.js` for dynamic content
4. No server restart needed (frontend only)

## Authentication

Server uses API key authentication. Keys are configured in:
- `config/default_config.yaml` under `auth.api_keys`
- Or via environment variables: `WLED_AUTH__API_KEYS`

For development, ensure at least one API key is configured or the server won't start.