football2801
44783d0f46
One-time commit of AI-generated planning documents: - prd.md — validated PRD, 44 FRs across 8 domains - prd-validation-report.md — validation results (4/5 holistic quality) - architecture.md — complete architecture document (all 8 steps) - epics.md — epics skeleton with extracted requirements inventory _bmad-output/ remains gitignored; these are committed explicitly. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
118 lines
7.8 KiB
Markdown
118 lines
7.8 KiB
Markdown
---
|
|
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_
|