united-tattoo/docs/prd/user-stories-with-acceptance-criteria.md

User Stories (with Acceptance Criteria)

Legend: UT-[Epic]-[ID]

• ADM = Admin/Artist Management (Epic A)
• BKG = Booking/Client (Epic B)
• PUB = Public Website (Epic C)
• ARC = Architecture/Delivery (Epic D)

Epic A — Admin Dashboard & Artist Management UT-ADM-01: As an admin, I can invite a new artist with a time-limited signup link.

• Given I am an admin
• When I enter the artist’s email and send an invite
• Then the artist receives a link that expires after a configured window and can register successfully

UT-ADM-02: As an artist, I can complete a wizard-style onboarding to set profile, styles, and initial portfolio.

• Given I have a valid invite
• When I follow the wizard steps (profile, styles, rates, availability)
• Then my artist profile is created and set to draft until I publish

UT-ADM-03: As an admin/owner, I can enforce 2FA for admin roles and allow optional passwordless for others.

• Given security settings are configured
• When a new admin registers
• Then they must enroll 2FA before accessing admin features

UT-ADM-04: As an editor, I can batch upload portfolio pieces with progress tracking.

• Given I have editor permissions
• When I drag-and-drop multiple images
• Then I see per-file progress and all successful uploads are linked to my portfolio

UT-ADM-05: As an editor, I can manually crop images with grid guides and save crops as separate assets.

• Given I uploaded an image
• When I open the crop tool and save
• Then a cropped asset version with metadata is created

UT-ADM-06: As an editor, I can toggle AI-assisted crop suggestions on/off at the account or workspace level.

• Given the setting is visible
• When I toggle AI suggestions off
• Then only manual cropping is suggested

UT-ADM-07: As an admin, I can manage compression settings for uploaded assets and override aggressive compression.

• Given default compression is on
• When I disable aggressive compression for a set
• Then newly processed assets use the chosen compression level

UT-ADM-08: As an admin, I can view an activity log with user, action, and timestamp to audit changes.

• Given actions were performed
• When I open the activity log
• Then I can filter by user and resource and export logs

UT-ADM-09: As an admin, I can pause an artist or globally pause the system to halt new bookings.

• Given an emergency scenario
• When I toggle pause for a specific artist or globally
• Then booking forms and availability reflect the pause with clear messaging

UT-ADM-10: As an editor, I can stage portfolio changes in a sandbox and preview before publishing live.

• Given I have draft changes
• When I open preview
• Then I see the draft state exactly as it would appear when published

Epic B — Unified Booking & Client Management UT-BKG-01: As a visitor, I am routed to consultation vs booking based on my form inputs.

• Given I start the booking flow
• When my answers indicate uncertainty or complex needs
• Then I’m guided to a consultation request instead of direct booking

UT-BKG-02: As a visitor, I can select appointment type (first tattoo, cover-up, large piece, etc.) and see appropriate options.

• Given I’m on the booking form
• When I choose an appointment type
• Then the form adapts with relevant questions and duration estimates

UT-BKG-03: As a visitor, I can see an automated quote estimate based on size, complexity, and artist tier.

• Given I filled required fields
• When I request an estimate
• Then I see a non-binding quote and deposit requirements

UT-BKG-04: As a client, I can create an account and see my upcoming/past appointments.

• Given I signed up
• When I log in to the client portal
• Then I can view appointments and details

UT-BKG-05: As a client, I can reschedule or cancel an appointment within policy windows.

• Given I have an upcoming appointment
• When I choose reschedule/cancel within allowed times
• Then the system updates calendar and sends notifications

UT-BKG-06: As an admin, I can enable two-way Google Calendar sync per-artist.

• Given an artist connects Google Calendar
• When sync is enabled
• Then booking changes appear in their calendar and availability reflects external events

UT-BKG-07: As a client, I can pay a deposit securely and receive a receipt.

• Given a deposit is required
• When I complete checkout via supported gateway
• Then my payment intent and receipt reference are stored and visible

UT-BKG-08: As an admin, I can process a refund via the payment gateway and record it in the system.

• Given a valid refund request
• When I issue a refund
• Then the client is notified and records reflect the refund

UT-BKG-09: As an admin, I receive notifications for new bookings, cancellations, and changes.

• Given notification preferences are set
• When key events occur
• Then I receive email/SMS alerts accordingly

Epic C — Public-Facing Website Experience UT-PUB-01: As a visitor, I experience consistent ShadCN-based UI across all pages.

• Given any site page
• When I navigate and interact
• Then spacing, typography, components, and transitions are consistent

UT-PUB-02: As a visitor, I see parallax/split-screen hero sections that are smooth and performant.

• Given I’m on the homepage or artist page
• When I scroll
• Then layered visuals and split sections animate smoothly within performance budgets

UT-PUB-03: As a visitor, I can use a dedicated search with filters (style, availability, price tier).

• Given I’m on /search
• When I apply filters
• Then artist and content results update accordingly

UT-PUB-04: As a visitor, I can use quick search (Ctrl+K) to find artists and educational content.

• Given I press Ctrl+K
• When I type a query
• Then I get navigable results for artists and key pages

UT-PUB-05: As a visitor, I can view improved aftercare content with visuals, progress tracking, and checklists.

• Given I open /aftercare
• When I read and mark steps
• Then my progress is saved locally and content is printable/PDF-downloadable

UT-PUB-06: As a visitor, I can browse artist galleries with style-based filtering and interactive zoom/lightbox.

• Given I’m on an artist page
• When I filter by style or click an image
• Then the gallery updates, and I can zoom without layout shift

Epic D — Technical Architecture & Delivery UT-ARC-01: As a developer, I can configure Cloudflare D1/R2 and verify SSR server-side asset delivery.

• Given environment is set
• When I run the preview
• Then assets are fetched server-side and delivered via caches

UT-ARC-02: As a visitor, I benefit from progressive images and lazy loading while browsing media-heavy pages.

• Given I visit a gallery
• When images load
• Then low-res placeholders progressively upgrade without jank

UT-ARC-03: As a returning visitor, I benefit from a service worker that improves revisit speed and limited offline browsing.

• Given PWA-like capabilities
• When I revisit
• Then common assets/pages load faster and basic offline fallback is available

UT-ARC-04: As the owner, I can preview new changes on a staging environment before production.

• Given staging is deployed
• When I access the staging URL
• Then I can verify new features and content before launch

UT-ARC-05: As a maintainer, I can rely on clear docs (README, architecture, changelog) to operate and extend the system.

• Given the repository
• When a new developer onboards
• Then they can set up, run, and contribute following documented steps