# 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:

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

Run backend:

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

Frontend dev mode (separate shell):

```powershell
cd frontend
npm run dev
```

Frontend production-style build:

```powershell
cd frontend
npm run build
```

Run tests:

```powershell
pytest
```

Overlay local run:

```powershell
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