alexei.dolgolyov
e2e1107df7
Some checks failed
Lint & Test / test (push) Has been cancelled
- Replace URL-based image_source/url fields with image_asset_id/video_asset_id on StaticImagePictureSource and VideoCaptureSource (clean break, no migration) - Resolve asset IDs to file paths at runtime via AssetStore.get_file_path() - Add EntitySelect asset pickers for image/video in stream editor modal - Add notification sound configuration (global sound + per-app overrides) - Unify per-app color and sound overrides into single "Per-App Overrides" section - Persist notification history between server restarts - Add asset management system (upload, edit, delete, soft-delete) - Replace emoji buttons with SVG icons throughout UI - Various backend improvements: SQLite stores, auth, backup, MQTT, webhooks
78 lines
3.0 KiB
Markdown
78 lines
3.0 KiB
Markdown
# 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, SSRF validation, sound playback)
|
|
- `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`
|
|
- When `api_keys` is empty (default), auth is disabled — all endpoints are open
|
|
- To enable auth, add key entries (e.g. `dev: "your-secret-key"`)
|
|
|
|
## 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).
|