docs: add planning artifacts — PRD, architecture, epics skeleton
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>
This commit is contained in:
@@ -0,0 +1,117 @@
|
||||
---
|
||||
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_
|
||||
Reference in New Issue
Block a user