alexei.dolgolyov
f2871319cb
Some checks failed
Lint & Test / test (push) Failing after 48s
Security: tighten CORS defaults, add webhook rate limiting, fix XSS in automations, guard WebSocket JSON.parse, validate ADB address input, seal debug exception leak, URL-encode WS tokens, CSS.escape in selectors. Code quality: add Pydantic models for brightness/power endpoints, fix thread safety and name uniqueness in DeviceStore, immutable update pattern, split 6 oversized files into 16 focused modules, enable TypeScript strictNullChecks (741→102 errors), type state variables, add dom-utils helper, migrate 3 modules from inline onclick to event delegation, ProcessorDependencies dataclass. Performance: async store saves, health endpoint log level, command palette debounce, optimized entity-events comparison, fix service worker precache list. Testing: expand from 45 to 293 passing tests — add store tests (141), route tests (25), core logic tests (42), E2E flow tests (33), organize into tests/api/, tests/storage/, tests/core/, tests/e2e/. DevOps: CI test pipeline, pre-commit config, Dockerfile multi-stage build with non-root user and health check, docker-compose improvements, version bump to 0.2.0. Docs: rewrite CLAUDE.md (202→56 lines), server/CLAUDE.md (212→76), create contexts/server-operations.md, fix .js→.ts references, fix env var prefix in README, rewrite INSTALLATION.md, add CONTRIBUTING.md and .env.example.
77 lines
2.8 KiB
Markdown
77 lines
2.8 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`
|
|
- 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).
|