alexei.dolgolyov/wled-screen-controller-mixed

Files

Lint & Test / test (push) Failing after 29s

Details

feat: optional auth + backup/restore reliability fixes

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

2026-03-23 14:50:25 +03:00

2.9 KiB

Raw Blame History

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

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

Adding a new field to existing API

Update Pydantic schema in api/schemas/
Update corresponding dataclass in storage/
Update backend logic to populate the field
Restart the server
Update frontend to display the new field
Rebuild bundle: cd server && npm run build

Adding translations

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

Modifying display/monitor detection

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

Testing

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.

Server Operations

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

2.9 KiB Raw Blame History