united-tattoo/docs/PRD.md

# Product Requirements Document (PRD)
United Tattoo — Public Website, Booking, and Admin System

Version: 1.0  
Date: 2025-09-17  
Source: Consolidated from docs/brainstorming.md

1. Overview
United Tattoo is expanding both its public-facing web experience and internal admin/ops systems. This PRD defines Functional Requirements (FRs), Non-Functional Requirements (NFRs), Epics, and User Stories derived from the brainstorming notes. The goal is a unified, scalable platform for artist onboarding and portfolio management, seamless client booking and portal experiences, and a refined, image-forward public site aligned to a ShadCN-based design system and Cloudflare runtime.

Primary Objectives
- Create a unified system supporting artist onboarding, portfolio and asset management, and secure admin controls.
- Deliver a polished, immersive public site with consistent design and rich educational content.
- Implement robust booking and payment flows with a client portal and calendar integration.
- Provide strong documentation, staging workflows, and an approachable owner handoff.

Key Assumptions & Tech Baseline
- UI baseline: ShadCN components, consistent with homepage and /artist pages.
- Visual language: Oversized image-forward design; layered parallax and split-screen storytelling.
- Infra: Cloudflare D1 (structured data), R2 (media assets); server-side asset loading.
- Docs/patterns: Context7 MCP and ShadCN MCP as primary references for patterns.
- Auth: Invite-based onboarding; RBAC; 2FA; optional passwordless fallback.
- Handoff: Staging environments, clear README/architecture docs, owner training.

2. Functional Requirements (FRs)
FR-A. Admin Dashboard & Artist Management
A1. Invitations & Onboarding
- FR-A1.1: Admin can invite users (artists, staff) via time-limited signup links.
- FR-A1.2: Wizard-style onboarding for artists using ShadCN components guiding profile, portfolio, and settings.
- FR-A1.3: Optional passwordless fallback; primary path supports email+password + 2FA enrollment.
- FR-A1.4: Sandbox mode to preview changes before publishing live.

A2. Role-Based Access & Controls
- FR-A2.1: Roles: viewer, editor (portfolio), admin, owner; assignable per user.
- FR-A2.2: Permissions restrict CRUD on artists, portfolios, and settings per role.
- FR-A2.3: Emergency pause control per artist or system-wide, disabling booking or portfolio visibility.

A3. Artist Profiles & Portfolio
- FR-A3.1: CRUD for artist profiles (bio, styles, rates/tiers, links, availability indicators).
- FR-A3.2: Batch drag-and-drop portfolio upload with progress tracking.
- FR-A3.3: Manual cropping UI with grid guides; save crops as separate asset records.
- FR-A3.4: Optional AI-assisted cropping suggestions (can be disabled per settings).
- FR-A3.5: Versioning for portfolio pieces to track edits/updates.
- FR-A3.6: Portfolio piece metadata: style tags, dimensions/size class, creation date, visibility flag.

A4. Asset Management & Delivery
- FR-A4.1: Store media in R2; metadata in D1.
- FR-A4.2: Server-side asset fetching and transformation for pages; minimize client duplication.
- FR-A4.3: Configurable compression levels; toggles to disable aggressive compression per asset/group.

A5. Auditability & Notifications
- FR-A5.1: Activity logs with user, action, timestamp; filter by user/resource.
- FR-A5.2: Notification preferences per user and per role (email/SMS for key events: new booking, cancellations).
- FR-A5.3: Basic content moderation hooks for uploads (e.g., queue for review).

FR-B. Unified Booking & Client Management
B1. Booking & Consultation Forms
- FR-B1.1: Multi-form flow with smart routing: consultation vs booking based on user input.
- FR-B1.2: Appointment type taxonomy (first tattoo, cover-up, large piece, etc.) drives questions and duration.
- FR-B1.3: Automated quote estimates based on inputs: size, placement, complexity, artist tier/rate.

B2. Client Portal
- FR-B2.1: Clients can create accounts and authenticate to manage appointments.
- FR-B2.2: View upcoming/past appointments, reschedule/cancel (per policy windows).
- FR-B2.3: Payments area: view deposit history, receipts, refunds.
- FR-B2.4: Profile and preferences (email/SMS notifications opt-in/out).

B3. Scheduling & Calendars
- FR-B3.1: Real-time availability across artists with conflict detection.
- FR-B3.2: Google Calendar two-way sync for artists (per-artist toggle).
- FR-B3.3: Automated confirmations and reminders (email/SMS) per policy.

B4. Payments
- FR-B4.1: Multi-merchant gateway support (e.g., Stripe, PayPal) with deposit handling.
- FR-B4.2: Store payment intents and receipt references securely; enable refund workflows.
- FR-B4.3: Deposit policies surfaced during booking; acceptance required to proceed.

B5. Notifications & Communications
- FR-B5.1: Email and SMS channels configurable by users/admins.
- FR-B5.2: Admin notifications for new bookings, cancellations, changes.

FR-C. Public-Facing Website Experience
C1. Design System & Visuals
- FR-C1.1: All pages follow ShadCN baseline; unify typography, spacing, and components.
- FR-C1.2: Implement layered parallax and split-screen storytelling in hero and portfolio sections.
- FR-C1.3: Image-forward layouts throughout; high-quality photography emphasis.

C2. Pages & Navigation
- FR-C2.1: Improve /aftercare, /deposit, /terms, /privacy, /book for consistency and UX.
- FR-C2.2: Smooth, consistent navigation with refined transitions.
- FR-C2.3: Responsive behavior across major breakpoints with mobile-first navigation patterns.

C3. Search & Discovery
- FR-C3.1: Dedicated search page with filters (style, availability, price tier).
- FR-C3.2: Quick search (Ctrl+K) for artists and educational content.
- FR-C3.3: Enhanced artist gallery: style-based filtering and interactive zooms/lightbox.

C4. Educational Content
- FR-C4.1: Detailed aftercare guides with visuals, progress tracking, and checklists.
- FR-C4.2: Healing process explanations with diagrams or annotated imagery.
- FR-C4.3: Downloadable PDFs and printable guides.

FR-D. Technical Delivery & Handoff
D1. Cloudflare Integration & Runtime
- FR-D1.1: Use D1 for structured data and R2 for media; server-side patterns for SSR/ISR where applicable.
- FR-D1.2: Caching strategies to minimize egress and optimize load times.

D2. Performance & Offline
- FR-D2.1: Lazy loading for portfolio assets; progressive image loading.
- FR-D2.2: Service worker for offline support and faster revisits.

D3. Documentation & Staging
- FR-D3.1: Clear README, architecture docs, changelog, contributor guide.
- FR-D3.2: Staging environment for Christy to preview changes.

D4. Handoff
- FR-D4.1: Repo delivered ready-to-merge; Cloudflare transfer instructions documented.
- FR-D4.2: Owner training materials for non-technical management.

3. Non-Functional Requirements (NFRs)
NFR-Security & Privacy
- NFR-S1: Enforce invite-based onboarding; session security; 2FA required for admins/owners; optional passwordless fallback.
- NFR-S2: Role-based access controls across admin features and APIs; least-privilege defaults.
- NFR-S3: Media access via scoped tokens; no direct public RW access to R2.
- NFR-S4: Payment flows must be PCI-compliant through the chosen gateway(s); do not store raw card data.
- NFR-S5: Basic content moderation hooks for uploads; audit and traceability of changes.
- NFR-S6: Conform to privacy policy; provide clear consent for notifications.

NFR-Performance
- NFR-P1: Use SSR-friendly, server-side image processing; progressive/lazy-loading for rich media.
- NFR-P2: Apply CDN caching and optimized asset delivery to keep LCP/INP within target budgets for typical gallery pages.
- NFR-P3: Minimize egress from R2 through caching and efficient formats; favor WebP/AVIF where supported.

NFR-Reliability & Availability
- NFR-R1: Implement robust error handling and retries for R2/D1 operations; graceful degradation of images.
- NFR-R2: Eventual consistency acceptable for search indices and non-critical caches (<1 minute).
- NFR-R3: Activity logs retained per policy; include export capabilities for audits.

NFR-Usability & Accessibility
- NFR-U1: Follow ShadCN conventions for components and patterns; consistent spacing/typography.
- NFR-U2: WCAG AA baseline for color contrast, focus states, and keyboard navigation.
- NFR-U3: Responsive layouts and touch targets across breakpoints.

NFR-Observability & Ops
- NFR-O1: Centralized error tracking for client/server, with release tagging.
- NFR-O2: Structured logs; avoid logging PII beyond necessity.
- NFR-O3: Staging environment should mimic production settings for realistic previews.

NFR-Documentation & Handoff
- NFR-D1: Up-to-date README, architecture overview, environment setup, and runbooks.
- NFR-D2: Owner-facing guides for day-to-day tasks (invites, portfolio updates, refunds, content).

4. Epics
Epic A: Admin Dashboard & Artist Management
Description: Secure, role-based admin experience to onboard artists, manage profiles/portfolios, and control assets.
Business Value: Scales operations; reduces friction for artist content management and quality control.

Epic B: Unified Booking & Client Management
Description: Multi-form booking and consultation flows, client portal, scheduling, and payments.
Business Value: Converts demand into scheduled work efficiently while respecting policies and preferences.

Epic C: Public-Facing Website Experience
Description: Consistent ShadCN-based design system, immersive visuals, improved content and discovery.
Business Value: Enhances brand, increases engagement, and improves conversion to consultations/bookings.

Epic D: Technical Architecture & Delivery
Description: Cloudflare-first architecture, caching/optimization, performance and offline capabilities, and strong documentation.
Business Value: Reliable, fast experience with maintainable operations and smooth handoff to the owner.

5. 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

6. Phasing (Reference)
- Phase 1 (Weeks 1–2): Foundations & Critical Fixes
  - Admin: invites, onboarding wizard, basic portfolio management, R2 integration scaffold (UT-ADM-01..05, 07, 10; UT-ARC-01)
- Phase 2 (Weeks 3–4): Core Features & UX
  - Booking, client portal, deposits/payments, design unification (UT-BKG-01..09; UT-PUB-01; UT-ARC-04)
- Phase 3 (Weeks 5–6): Polish & Visual Experience
  - Parallax/split-screen, search & filters, education content, service worker (UT-PUB-02..06; UT-ARC-02..03)
- Phase 4 (Week 7): Documentation & Delivery
  - Docs, handoff, training, final staging (UT-ARC-05 + wrap-ups)

7. Risks & Mitigations (Summary)
- Admin dashboard complexity/bugs → Incremental delivery, sandbox previews, RBAC testing.
- Cloudflare D1/R2 pitfalls → Follow proven patterns; robust error handling; staging validation.
- Performance with heavy visuals → Lazy loading, image optimization, prudent asset sizing, performance budgets.

End of PRD.