espresso_frame/CLAUDE.md

espresso_frame

A DIY e-ink photo frame: an ESP32-C6 (firmware/, ESP-IDF) driving a Waveshare 7.3" E Ink Spectra 6 panel (800x480, 6-color, SPI), paired with a self-hosted FastAPI server (server/) that pulls from Immich, does all image processing (crop/dither/quantize/pack), and serves a placeable photos/calendar/whiteboard/weather widget system to the device.

CURRENT TODO -sharing layouts with linked users -a "coming up this week" widget -on reset dismiss the menu.

Start here, don't re-derive from scratch:

• docs/architecture.md -- how firmware and server talk (sequence diagram, boot flow).
• docs/widgets.md -- the server-side widget system (data model, grid placement, compositor, button-action dispatch).
• docs/hardware.md -- wiring.
• server/README.md, firmware/README.md -- per-component setup, config, and a lot of accumulated gotchas (Immich API shape, TLS trust-anchor details, button GPIO wakeup quirks, etc.) -- check these before assuming something is a new bug.

Conventions specific to this repo

• No Co-Authored-By: Claude trailers in commits. Attribution lives in the root README.md instead (see its last line) -- the maintainer's explicit preference, not the default.
• Copyleft dependencies need an explicit flag, not a silent decision. Before adding anything LGPL/GPL/AGPL (or unclear), verify the actual license via pip show/package metadata -- including transitive deps, not just the top-level package -- and present the finding and tradeoff in plain text rather than picking an approach unilaterally (hand-rolling an alternative, swapping packages, silently accepting it). This project has knowingly accepted AGPL-3.0-or-later exposure once already (icalendar-searcher, a transitive dep of caldav) as a deliberate, explicit call -- not a precedent for skipping the check next time.
• Scope new auth/access-control broadly, not just to the literal endpoint named. When a request changes the trust model (e.g. adding public-internet exposure), apply the new gate to every endpoint serving real data or performing a real action, and call out anything you're tempted to exclude and why. This repo shipped a token gate once that covered /api/* but left /frame/image -- the actual photo bytes -- open; caught immediately in production.
• Commit and push once a task is verified working, without waiting to be asked separately. Once tests pass (and, for UI changes, the browser check has been done), stage the relevant files, write a normal commit message, and push to the current branch -- the maintainer's standing authorization for the commit/push step itself. This doesn't relax anything else: still run git status/review the diff before staging, still never force-push/amend a pushed commit/skip hooks, and still surface anything that looks like it needs a real decision (e.g. a change that would trigger main's deploy workflow, see below) instead of pushing through it silently.

Working in this repo

• Server tests: cd server && pytest (SQLite, fixtures wipe/reseed between tests -- see tests/conftest.py). Migration changes need a matching test in tests/test_migrations.py; anything touching require_frame_view/require_frame_control boundaries needs a same-shape permission test (see tests/test_permission_boundaries.py and tests/test_button_actions.py for the pattern: owner, linked user, unrelated user, logged out).
• UI changes: verify in a real browser (Playwright), not just by reading the JS -- this project has hit multiple bugs that only showed up live (mobile viewport CSS collapse, a dialog's status message landing behind its own backdrop, a JSON/form-urlencoded body mismatch). Spin up uvicorn app.main:app against a scratch DATABASE_URL/CONFIG_PATH sqlite file, don't touch the real deployment's data. .claude/skills/run-server/ (/run-server) has a driver for exactly this.
• New/changed UI must work at both desktop and mobile widths -- screenshot both, don't assume one implies the other. The layout genuinely forks at the 860px breakpoint (theme.css): the sidebar goes off-canvas behind a hamburger below it. A dialog, header control, or new widget that looks right at a wide viewport can overflow, overlap the mobile bar, or mis-center at phone widths. run-server's driver has a viewport command for exactly this (defaults to a phone size; switch to 1280 900 for desktop).
• Deploy: Gitea Actions at git.thumeit.com/tfaour/espresso_frame (.gitea/workflows/server-docker-build.yml: test -> build-and-push -> deploy on any push to main touching server/**; deploy SSHes into the host as espressoframe_deployer and runs docker compose pull && docker compose up -d). A separate workflow (firmware-release-build.yml) builds+publishes firmware binaries as Gitea release assets when firmware/version.txt changes. Poll CI status with curl https://git.thumeit.com/api/v1/repos/tfaour/espresso_frame/actions/tasks rather than asking the user to check.
• Device-facing paths are frozen. /frame/image, /frame/advance, /frame/back, /frame/config, /frame/battery, /frame/firmware and their exact JSON key names (refresh_interval_s, firmware_version, etc.) are baked into deployed firmware -- never rename or restructure these without a firmware-side migration story to match.