---
name: pictureFrame project context
description: Goals, stack, hardware, current status, and key decisions for the pictureFrame project
type: project
---

Handcrafted e-ink digital picture frame ecosystem built as a meaningful gift. ESP32 + Waveshare 7.3" 6-color e-ink display, battery or plugin, companion Symfony web app for image management, device configuration, and family sharing.

**Why:** Personal project — frames are hand-built and gifted. The software keeps them personal and current without requiring the recipient to do anything.

## Hardware

- ESP32 dev board (esp32dev), dual-core 240MHz, 4MB flash
- Waveshare 7.3" 6-colour e-ink (800×480, E-Ink Spectra 6)
- SPI pinout: SCK=18, MOSI=23, CS=5, DC=17, RST=16, BUSY=4
- 4bpp packed, palette: BLACK=0x0, WHITE=0x1, YELLOW=0x2, RED=0x3, BLUE=0x5, GREEN=0x6

## Stack

- Firmware: PlatformIO + Arduino framework (C/C++)
- Web app: Symfony 8.0 (PHP 8.4+), PostgreSQL 16, Nginx-FPM
- Local dev: DDEV (mirrors ~/src/aqua-iq setup)
- Infra reference: ~/src/aqua-iq for Docker/DDEV config, server location, SSH details
- Git: git.edholm.me (self-hosted Gitea/Forgejo)
- Domain: pictureframe.edholm.me

## Current status (2026-04-27)

- POC firmware previously built (display driver proven)
- PRD complete and validated (4/5 holistic quality, all fixes applied)
- Architecture complete — all 8 steps done, document at `_bmad-output/planning-artifacts/architecture.md`
- No production code written yet; next step is epics/stories or direct Symfony scaffold

## Key architectural decisions

- Async image processing: Symfony Messenger (Doctrine transport), `max_retries: 1`
- Image storage: `storage/images/{id}/{model}_{orientation}.bin`, relative paths in DB, `STORAGE_PATH` env var
- Device pull endpoint: `GET /api/device/{mac}/image` — 200 (binary), 204 (no ready image), 404 (unknown MAC)
- Enums: PHP 8.1 backed enums for `RenderStatus`, `TokenType`, `Orientation`
- Repositories: `findActive*` prefix for all soft-delete-aware methods
- Token entity: UUID PK, type enum, expires_at, used_at — single-use authorization links
- Testing: Unit/Integration/Functional split, no DB mocks
- Imagick for Floyd-Steinberg dithering (not GD)

## How to apply

Stack is decided — Symfony, PostgreSQL, DDEV. Don't suggest alternatives. For infrastructure patterns (docker-compose, server location, SSH), reference ~/src/aqua-iq. APP_BASE_URL = https://pictureframe.edholm.me — baked into firmware as build constant. First implementation command: `symfony new pictureframe --webapp`.