Files

T

Lint & Test / test (push) Successful in 1m56s

Details

refactor: rename project to LedGrab, split HA integration into separate repo

- Rename Python package: wled_controller -> ledgrab
- Rename env var prefix: WLED_ -> LEDGRAB_ (with auto-migration for old vars)
- Rename localStorage key: wled_api_key -> ledgrab_api_key (with migration)
- Rename HA integration domain: wled_screen_controller -> ledgrab
- Update all imports, build scripts, Docker, installer, config, docs
- Remove HA integration (moved to ledgrab-haos-integration repo)
- Remove hacs.json (belongs in HA repo now)
- Add startup warning for users with old WLED_ env vars
- All tests pass (715/715), ruff clean, tsc clean, frontend builds

2026-04-12 22:45:28 +03:00

2.9 KiB

Raw Blame History

Claude Instructions for LedGrab Server

Project Structure

src/ledgrab/main.py — FastAPI application entry point
src/ledgrab/api/routes/ — REST API endpoints (one file per entity)
src/ledgrab/api/schemas/ — Pydantic request/response models (one file per entity)
src/ledgrab/core/ — Core business logic (capture, devices, audio, processing, automations)
src/ledgrab/storage/ — Data models (dataclasses) and JSON persistence stores
src/ledgrab/utils/ — Utility functions (logging, monitor detection, SSRF validation, sound playback)
src/ledgrab/static/ — Frontend files (TypeScript, CSS, locales)
src/ledgrab/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: LEDGRAB_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