wled-screen-controller-mixed/server/CLAUDE.md

Claude Instructions for WLED Screen Controller Server

Development Workflow

Server Restart Policy

IMPORTANT: When making changes to server code (Python files in src/wled_controller/), you MUST restart the server if it's currently running to ensure the changes take effect.

When to restart:

• After modifying API routes (api/routes.py, api/schemas.py)
• After updating core logic (core/*.py)
• After changing configuration (config.py)
• After modifying utilities (utils/*.py)
• After updating data models or database schemas

How to check if server is running:

# Look for running Python processes with wled_controller
ps aux | grep wled_controller
# Or check for processes listening on port 8080
netstat -an | grep 8080

How to restart:

1. Stop the current server (if running as background task, use TaskStop with the task ID)
2. Start a new server instance:

   cd server && python -m wled_controller.main
   

3. Verify the new server started successfully by checking the output logs

Files that DON'T require restart:

• Static files (static/*.html, static/*.css, static/*.js) - these are served directly
• Locale files (static/locales/*.json) - loaded by frontend
• Documentation files (*.md)
• Configuration files in config/ if server supports hot-reload (check implementation)

Git Push Policy

CRITICAL: NEVER push commits to the remote repository without explicit user approval.

Rules

• You MAY create commits when requested or when appropriate
• You MUST NOT push commits unless explicitly instructed by the user
• If the user says "commit", create a commit but DO NOT push
• If the user says "commit and push", you may push after committing
• Always wait for explicit permission before any push operation

Workflow

1. Make changes to code
2. Create commit when appropriate (with user consent)
3. STOP and WAIT - do not push
4. Only push when user explicitly requests it (e.g., "push", "commit and push", "push to remote")

Testing Changes

After restarting the server with new code:

1. Test the modified endpoints/functionality
2. Check browser console for any JavaScript errors
3. Verify API responses match updated schemas
4. Test with different locales if i18n was modified

Project Structure Notes

• src/wled_controller/main.py - FastAPI application entry point
• src/wled_controller/api/ - REST API endpoints and schemas
• src/wled_controller/core/ - Core business logic (screen capture, WLED client, processing)
• src/wled_controller/utils/ - Utility functions (logging, monitor detection)
• src/wled_controller/static/ - Frontend files (HTML, CSS, JS, locales)
• config/ - Configuration files (YAML)
• data/ - Runtime data (devices.json, persistence)

Common Tasks

Adding a new API endpoint:

1. Add route to api/routes.py
2. Define request/response schemas in api/schemas.py
3. Restart the server
4. Test the endpoint via /docs (Swagger UI)

Adding a new field to existing API:

1. Update Pydantic schema in api/schemas.py
2. Update corresponding dataclass (if applicable)
3. Update backend logic to populate the field
4. Restart the server
5. Update frontend to display the new field

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

Modifying server login:

1. Update the logic.
2. Restart the server

Adding translations:

1. Add keys to static/locales/en.json and static/locales/ru.json
2. Add data-i18n attributes to HTML elements in static/index.html
3. Use t('key') function in static/app.js for dynamic content
4. No server restart needed (frontend only)

Authentication

Server uses API key authentication. Keys are configured in:

• config/default_config.yaml under auth.api_keys
• Or via environment variables: WLED_AUTH__API_KEYS

For development, ensure at least one API key is configured or the server won't start.