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.

NOTE: Auto-reload is currently disabled (reload=False in main.py) due to watchfiles causing an infinite reload loop. Changes to server code will NOT be automatically picked up - manual server restart is required.

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)

Frontend UI Patterns

Modal Dialogs

IMPORTANT: All modal dialogs must follow these standards for consistent UX:

Backdrop Click Behavior

All modals MUST close when the user clicks outside the dialog (on the backdrop). Implement this by adding a click handler that checks if the clicked element is the modal backdrop itself:

// Show modal
const modal = document.getElementById('my-modal');
modal.style.display = 'flex';

// Add backdrop click handler to close modal
modal.onclick = function(event) {
    if (event.target === modal) {
        closeMyModal();
    }
};

Where to add: In every function that shows a modal (e.g., showAddTemplateModal(), editTemplate(), showTestTemplateModal()).

Close Button Requirement

Each modal dialog that has a "Cancel" button MUST also have a cross (×) close button at the top-right corner of the dialog. This provides users with multiple intuitive ways to dismiss the dialog:

1. Click the backdrop (outside the dialog)
2. Click the × button (top-right corner)
3. Click the Cancel button (bottom of dialog)
4. Press Escape key (if implemented)

HTML Structure:

<div class="modal-content">
    <button class="close-btn" onclick="closeMyModal()">&times;</button>
    <h2>Dialog Title</h2>
    <!-- dialog content -->
    <div class="modal-actions">
        <button onclick="closeMyModal()">Cancel</button>
        <button onclick="submitAction()">Submit</button>
    </div>
</div>

CSS Requirements:

• Close button should be positioned absolutely at top-right
• Should be easily clickable (min 24px × 24px hit area)
• Should have clear hover state

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.