pictureFrame-webApp/_bmad-output/planning-artifacts/epics.md

stepsCompleted, inputDocuments, workflowType, project_name, user_name, date

stepsCompleted	inputDocuments	workflowType	project_name	user_name	date
1	prd.md architecture.md	epics-and-stories	pictureFrame	Matt.edholm	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