custom-streamdeck/Agents.md

Agents Guide: Custom Streamdeck

This file is a practical onboarding guide for coding agents and contributors working in this repository.

Mission

Build and maintain a local-first Streamdeck platform:

• Raspberry Pi Pico emits button events over USB serial.
• FastAPI backend owns state, persistence, action execution, and plugin runtime.
• React frontend is the configuration UI.
• Optional Electron overlay displays active profile/folder context.

Tech Stack

• Backend: Python, FastAPI, SQLite, pyserial, pynput
• Frontend: React 19 + TypeScript + Vite
• Overlay: Electron + TypeScript + Tailwind CLI
• Device firmware: MicroPython (pico/main.py)

Repository Map

• backend/: API, runtime lifecycle, DB, action engine, serial + plugin services
• frontend/: Vite React app for deck configuration
• overlay/: transparent desktop overlay app
• plugins/: backend plugin modules (PLUGIN entrypoint contract)
• pico/: Pico firmware
• tests/: backend and plugin behavior tests
• data/: runtime SQLite data (gitignored)

Fast Start Commands

From repo root:

python -m pip install -r requirements.txt
cd frontend; npm install; cd ..
cd overlay; npm install; cd ..

Run backend:

python -m uvicorn backend.main:app --host 127.0.0.1 --port 8000

Frontend dev mode (separate shell):

cd frontend
npm run dev

Frontend production-style build:

cd frontend
npm run build

Run tests:

pytest

Overlay local run:

cd overlay
npm run dev

Runtime Contracts To Respect

Backend Runtime

• App entrypoint and route wiring live in backend/main.py.
• Runtime owns db, websocket manager, plugin manager, action engine, serial service, and app discovery.
• WebSocket event flow (/ws) is part of the product behavior; avoid breaking event names casually.

Database and Layout Rules

• SQLite file defaults to data/streamdeck.sqlite.
• First profile/root folder define canonical physical button layout.
• Physical mapping updates are intentionally restricted to the first profile's root folder.
• Schema + defaults are managed in backend/database.py; preserve migration safety and default seeding.

Action Engine

• Action dispatch is centralized in backend/services/actions.py.
• Built-ins include: noop, key_combo, chain, app_launch, folder, folder_rotation, plugin.
• click_check mode blocks action execution and is relied on by UI/testing flows.

Plugin System

• Plugins load from plugins/ through backend/services/plugins.py.
• Each plugin exports top-level PLUGIN.
• Expected plugin attributes: name, desc, version, actions.
• Optional hooks: on_load(ctx), on_event(ctx, event), execute_action(ctx, action_id, config, event).
• Plugin failures should be isolated (disabled plugin, backend stays alive).

Firmware Assumptions

• Pico reports JSON lines with fields: button, pin, event, pressed.
• Button indices are 1..10.
• Wiring order in firmware is authoritative: 28,27,26,22,21,20,18,19,17,16.

Change Workflow (Recommended)

1. Read impacted module(s) and existing tests.
2. Implement minimal, targeted change.
3. Add/update tests in tests/ for behavior changes.
4. Run pytest.
5. If frontend/overlay touched, run corresponding build command(s).
6. Summarize user-visible impact and any migration or operational notes.

Guardrails

• Keep backend behavior deterministic and explicit; avoid silent fallbacks unless already established.
• Do not commit runtime/generated directories:
  • data/
  • frontend/dist/, frontend/node_modules/
  • overlay/dist/, overlay/release/, overlay/node_modules/
• Prefer extending existing action/plugin patterns over introducing parallel frameworks.
• Preserve local-first behavior: no cloud dependency required for baseline functionality.

High-Value Test Targets

When changing core behavior, prioritize tests around:

• Pico event parsing (parse_pico_line)
• Profile/folder/button invariants in Database
• Physical layout synchronization and restrictions
• Action execution paths (folder, folder_rotation, plugin, chain)
• Plugin isolation and HTTP/device integration plugins