---
stepsCompleted: [1]
inputDocuments: ['prd.md', 'architecture.md']
workflowType: 'epics-and-stories'
project_name: 'pictureFrame'
user_name: 'Matt.edholm'
date: '2026-04-27'
---

# pictureFrame - Epic Breakdown

## Overview

This document provides the complete epic and story breakdown for pictureFrame, decomposing the requirements from the PRD and Architecture into implementable stories.

## Requirements Inventory

### Functional Requirements

FR1: Visitors can register a new account with an email address and password
FR2: Registered users can log in to their account
FR3: Super admin can view, edit, and delete any user account, device, or image across the system

FR4: Users can register a device to their account via the provisioning setup flow
FR5: Users can assign a name to each of their devices
FR6: Users can configure display orientation (landscape or portrait) per device
FR7: Users can configure the image rotation frequency per device
FR8: Users can configure the uniqueness window (number of cycles before an image can repeat) per device
FR9: When a device is re-provisioned to a new account, the system atomically purges the prior image history and transfers ownership
FR10: Super admin can view, rename, reconfigure, and transfer any device across all accounts

FR11: Users can upload photos to their personal image library
FR12: Users can view their library filtered by source: Uploaded vs. Shared
FR13: Users can soft-delete images from their library
FR14: When an image is shared to a user, it appears in their library as a reference (not a copy)
FR15: Super admin can add images to and remove images from a global pre-loaded image pool available to all devices

FR16: Users can approve or decline images for a specific device in their account
FR17: Users can share an image from their library to another user
FR18: When an image is shared, the recipient receives an email with the image and an approve action; clicking approve opens a device-selection page (no login required) where the recipient chooses which device(s) to add the image to
FR19: The approval link works from any email client without requiring account creation or login
FR20: Approved images enter the active rotation pool for the selected device(s)
FR21: Users can approve all images within a collection for a device in a single action
FR22: Users can request a full hard delete of their own image, which enters a super-admin review queue
FR23: System sends confirmation to the user when their hard-delete request is fulfilled

FR24: Device enters provisioning mode when the reset button is held for 5 seconds
FR25: In provisioning mode, device displays a scannable QR code for joining the provisioning access point
FR26: User can enter home WiFi credentials through a captive portal served by the device
FR27: On successful WiFi connection, device displays a QR code linking to the account setup page for that specific device
FR28: On failed WiFi connection, device displays a failure indicator, reactivates the AP, and redisplays the provisioning QR code for retry
FR29: Users can register a new account or log in to an existing account from the device setup page to link the device

FR30: System automatically advances to the next approved image on the configured schedule for each device
FR31: System tracks image display history per device to enforce the configured uniqueness window
FR32: When the uniqueness window exceeds the count of available approved images, the window is treated as equal to the available image count
FR33: System pre-renders images to display-ready format per device model and orientation at the time of upload or approval
FR34: Device pulls its next pre-rendered image from the server on each scheduled cycle

FR35: Device displays the current image persistently with no power draw between refresh cycles
FR36: Device retains and displays the last successfully transferred image through power loss and WiFi outages
FR37: Device only updates the display after a complete, confirmed image transfer
FR38: Device renders a yellow border when WiFi is connected but the server sync fails
FR39: Device renders a red border when WiFi connectivity is unavailable

FR40: Super admin can view a queue of user-submitted hard-delete requests and fulfill or dismiss them
FR41: Super admin can force an immediate hard delete of any image in the system
FR42: Super admin can view a device ownership transfer audit log
FR43: System automatically hard-deletes soft-deleted images that have no remaining approvals via a scheduled background process
FR44: Soft-deleted images with at least one active approval are retained until all approvals are removed

### NonFunctional Requirements

NFR1 (Performance): Image pre-rendering completes within 10 seconds of upload or approval trigger
NFR2 (Performance): Device image pull endpoint returns the pre-rendered binary asset within 10 seconds on typical home broadband
NFR3 (Performance): Web application pages load within 3 seconds on a standard broadband connection
NFR4 (Performance): Image rotation fires within ±5 minutes of the configured interval

NFR5 (Security): All device-to-server communication occurs over HTTPS
NFR6 (Security): Device image pull requests are authenticated by MAC address; server rejects requests from unregistered MACs
NFR7 (Security): Email inline approve/decline actions use single-use authorization links that expire after use or after a configurable TTL
NFR8 (Security): User accounts are isolated — a user cannot access another user's images or devices without an explicit sharing action
NFR9 (Security): Super admin access is restricted to a single designated account
NFR10 (Security): Device ownership transfer requires physical access to the reset button

NFR11 (Reliability): A device must never display a blank screen in normal operation — the last successfully transferred image persists indefinitely
NFR12 (Reliability): A display refresh only occurs after a complete, confirmed transfer; a mid-transfer interruption leaves the previous image on screen
NFR13 (Reliability): Soft-delete and scheduled cleanup run on a scheduled basis without manual intervention
NFR14 (Reliability): Breaking API changes are prohibited in V1

NFR15 (Accessibility): All primary user journeys complete successfully on iOS Safari (latest) and Android Chrome (latest)
NFR16 (Accessibility): Email sharing flows must work without requiring app installation or login on the recipient's device

### Additional Requirements

Architecture-derived technical requirements:
- **Starter template:** `symfony new pictureframe --webapp` — first implementation action
- **DDEV setup:** PHP 8.4, nginx-fpm, PostgreSQL 16 — mirror aqua-iq `.ddev/config.yaml`; add `docker-compose.imagick.yaml` for Imagick extension
- **Domain first:** `pictureframe.edholm.me` must be established and Nginx configured on VPS before firmware build constants are set
- **Imagick:** Must be installed in DDEV container and on VPS before image processing worker can run
- **Symfony Messenger:** Doctrine transport, `image_processing` queue, `max_retries: 1`
- **Symfony Scheduler:** Required for rotation engine and cleanup jobs
- **Storage:** `storage/images/` directory, `STORAGE_PATH` env var, relative paths in DB
- **Git / CI:** Repository at `git.edholm.me`; Gitea Actions CI workflow
- **Critical implementation rule:** Device pull endpoint returns 204 (no ready image) vs 404 (unknown MAC) — must never confuse the two
- **Token entity:** UUID PK, TokenType enum (ShareApprove, ShareDecline, HardDeleteConfirm), expires_at, used_at
- **Enums:** PHP backed enums for RenderStatus, TokenType, Orientation
- **Repository naming:** `findActive*` prefix on all soft-delete-aware methods
- **No OTA firmware:** API contract is stable by design; breaking changes require physical reflash

### FR Coverage Map

_To be completed in Step 3 (epic design)_

## Epic List

_To be completed in Step 2_