alexei.dolgolyov
4975a74ff3
Some checks failed
Lint & Test / test (push) Failing after 29s
Auth is now optional: when `auth.api_keys` is empty, all endpoints are open (no login screen, no Bearer tokens). Health endpoint reports `auth_required` so the frontend knows which mode to use. Backup/restore fixes: - Auto-backup uses atomic writes (was `write_text`, risked corruption) - Startup backup skipped if recent backup exists (<5 min cooldown), preventing rapid restarts from rotating out good backups - Restore rejects all-empty backups to prevent accidental data wipes - Store saves frozen after restore to prevent stale in-memory data from overwriting freshly-restored files before restart completes - Missing stores during restore logged as warnings - STORE_MAP completeness verified at startup against StorageConfig
78 lines
2.9 KiB
Markdown
78 lines
2.9 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)
|
|
- `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).
|