united-tattoo/docs/brief.md

Project Brief: United Tattoo

Mode: Interactive Last Updated: 2025-09-17

Executive Summary

• Product concept: A unified, artist-powered tattoo studio platform combining a premium public website with a secure admin dashboard. Artists can self-manage profiles and portfolios; clients can discover artists, book consultations or appointments, pay deposits, and manage schedules; the studio retains fine-grained control over permissions and content.
• Primary problem: Fragmented booking, asset, and user management forces the owner to handle technical workflows, while inconsistent UX on key pages hampers conversions and brand/talent exposure.
• Target market: Tattoo enthusiasts across age ranges—from high-ticket realism clients to first-timers—especially women seeking a clean, safe, professional studio environment.
• Key value proposition: Beautiful ShadCN-led UX with immersive visuals, real-time availability and booking with deposits, client portal, two-way Google Calendar sync and notifications, and Cloudflare D1/R2-backed reliability—paired with clear documentation, staging previews, and owner-friendly operations.

Problem Statement

Current state and pain points:

• Admin workflow is blocked by bugs in the dashboard (e.g., cannot create users), preventing artist onboarding and forcing the owner to perform or defer technical tasks.
• Fragmented processes for booking, consultations, and general inquiries create friction and confusion; there’s no unified scheduling with real-time artist availability.
• Clients cannot self-serve key actions (reschedule/cancel, deposit payments), increasing manual coordination and missed opportunities.
• Inconsistent UX and visual design on several public pages (/aftercare, /deposit, /terms, /privacy, portions of /book) undermines brand quality and conversion compared to the polished homepage and /artists pages.
• Portfolio and asset management lacks a streamlined path: artists need a simple, permissioned way to upload/crop/compress assets stored in R2, without owner involvement or Git knowledge.

Impact:

• Lost bookings and reduced conversion due to friction in forms and inconsistent UI.
• Increased owner time cost managing users, content, and schedules (non-scalable).
• Lower artist visibility and slower portfolio updates impact brand/talent exposure and revenue.
• Operational risk from manual workflows (scheduling conflicts, missed reminders).

Why existing solutions fall short:

• Generic booking tools don’t integrate deeply with artist-managed portfolios, fine-grained permissions, Cloudflare R2/D1, and studio-specific workflows.
• “No-code” CMS options do not provide the desired ShadCN-led UX, tight control over permissions, and integrated deposits/Google Calendar sync.
• Current implementation attempts exist but lack consistent functionality and maintainability in key areas.

Urgency:

• Near-term fixes unlock bookings and self-service today; a cohesive platform compounds benefits over time via better artist exposure, higher conversion, and easier operations.

Proposed Solution

Core concept and approach:

• Deliver a ShadCN-led Next.js platform with two faces:
  1. Public site that showcases artists with immersive, oversized visuals and cohesive design across all pages.
  2. A secure admin dashboard where admins invite artists, manage permissions, and artists self-manage their profiles and portfolios stored in Cloudflare R2.
• Implement unified booking with two primary flows (consultation and direct booking), a general inquiry form, and a client portal for reschedule/cancel and deposit payments.

Key differentiators:

• First-class artist self-management (no Git required): upload/crop/compress media to R2 with audit logs and versioning; admin can pause any user or globally.
• Tight integration of booking + portfolios + permissions + Cloudflare D1/R2 + Google Calendar sync + deposits in one cohesive system.
• ShadCN consistency end-to-end for a polished, premium feel aligning with the homepage and /artists pages, including smooth parallax and split-screen experiences.

Why this will succeed:

• Reduces owner burden with invite-based onboarding, role-based access, and reliable asset pipelines; eliminates fragmented tools and manual overhead.
• Improves conversion via unified, consistent UX on critical pages (/aftercare, /deposit, /book, policies) and clear CTAs that guide users to consult or book.
• Enhances reliability with Cloudflare D1/R2, robust validation (Zod), and documented processes; staging environment provides safe preview before release.

High-level vision:

• Phase 1: Unblock user creation and implement portfolio basics.
• Phase 2: Add client portal, deposits, and Google Calendar synchronization.
• Phase 3: Deliver advanced search, educational guides, and refined parallax/split-screen visuals.
• Final phase: Documentation, staging workflows, and handoff to Christy with minimal ongoing effort required.

Target Users

Primary User Segment: Serious collectors & premium clients

• Profile: Adults 25-55 with disposable income; professionals and enthusiasts commissioning large or complex pieces (e.g., full back realism).
• Behaviors: Research-driven, compare portfolios across styles; schedule well in advance; expect transparent pricing/deposits and reliable scheduling.
• Needs & Pain Points: Direct access to artists by style/specialty; high-quality, zoomable portfolios; streamlined booking with deposit; clear aftercare; calendar certainty and reminders.
• Goals: Commission top-tier custom work with minimal friction; confidence in cleanliness, process, and outcome.

Secondary User Segment: First-timers & mainstream return clients (with emphasis on women seeking a clean, safe studio)

• Profile: Teens with guardians through 40s+; diverse backgrounds; many are women prioritizing safety, professionalism, and clear guidance.
• Behaviors: Seek reassurance and education; prefer simple, guided booking and consultation flows; value testimonials and shop photos.
• Needs & Pain Points: Clarity between consultation vs. booking; transparent policies; easy rescheduling/cancellation; accessible aftercare guides; welcoming, consistent design.
• Goals: A safe, supported first (or next) tattoo experience with a studio they trust and want to return to.

Goals & Success Metrics

Business Objectives (SMART where possible)

• Increase successful bookings by 30% within 6 months of launch.
• Reduce owner time spent on user/content/schedule management by 50% within 3 months.
• Achieve consistent brand experience across all public pages with visual parity to homepage and /artists by initial release.
• Enable 100% of active artists to self-manage their profiles/portfolios without developer assistance within 2 months.

User Success Metrics

• Booking flow conversion rate (visit → completed booking or consultation request).
• Deposit completion rate and refund handling satisfaction.
• Client portal adoption (active users performing self-service actions).
• Time-to-first-publish for new artist portfolio updates after invite.
• Aftercare content engagement (views, completion rate, downloads).

KPIs (with definitions and targets)

• Conversion Rate (Book/Consult): target ≥ 3.5% sitewide, ≥ 5% on artist pages.
• Deposit Completion Rate: target ≥ 90% within 24 hours of initiating booking.
• Artist Self-Management Adoption: target ≥ 90% of artists active monthly in dashboard.
• Portfolio Update Latency: median ≤ 1 day from upload to live publish.
• Owner Admin Time: ≤ 2 hrs/week average on routine management after month 3.
• Calendar Sync Success: ≥ 99% successful two-way sync events.
• Notification Deliverability (Email/SMS): ≥ 98% delivery, ≤ 1% bounce.
• Performance: LCP ≤ 2.5s p75, CLS ≤ 0.1, TBT ≤ 200ms on key pages.
• Uptime: ≥ 99.9% monthly.
• Bug Regression Rate (critical): ≤ 1 per month post-stabilization.

MVP Scope

Core Features (Must Have)

• Admin & Auth
  • Fix admin user creation; invite-based onboarding with expiring links.
  • Roles/permissions: owner, admin, artist (edit own profile/portfolio).
  • Artist self-management: name, pronouns, avatar, bio, skills.
• Portfolio & Assets
  • Image/video upload to R2 via server pipeline.
  • Manual cropping and compression UI (AI suggestions disabled by default).
  • Basic versioning (retain original + current).
• Booking & Forms
  • Consultation form and direct booking form (+ general inquiry form).
  • Deposit payments via Stripe (single-processor to reduce scope).
  • Email notifications (client + artist + admin). SMS optional for post‑MVP.
  • Calendar sync: create events on artist Google Calendar (one‑way for MVP).
  • Client portal: view appointment, reschedule/cancel, see deposit receipts.
• Public Site UX
  • Redesign /aftercare, /deposit, /terms, /privacy, /book to match ShadCN baseline and the homepage/artist aesthetic.
  • Smooth navigation/scroll consistency; image-forward sections.
• Search (Basic)
  • Quick find for artists by name/style. Full-site and Ctrl+K advanced search post‑MVP.
• Documentation & Staging
  • README, setup, release process; staging preview for Christy.

Out of Scope for MVP

• AI cropping suggestions (optional setting exists but disabled; polish later).
• Two-way Google Calendar reconciliation; advanced conflict resolution.
• SMS notifications at scale; payment plans/multi‑processor support.
• Advanced search (filters, content-wide, Ctrl+K command palette).
• Mobile app; offline mode/service worker enhancements.
• Complex refund automation/tax scenarios; analytics dashboards.

MVP Success Criteria

• Owner can invite an artist who publishes portfolio updates within 24 hours of invite.
• End-to-end booking with deposit succeeds (client → deposit → event on artist Google Cal → email confirmations).
• Redesigned pages shipped with ShadCN parity and smooth scrolling.
• Booking conversion uplift detectable vs baseline within 60 days.
• Admin routine management time ≤ 2 hrs/week by month 3.

Post‑MVP Vision

Phase 2 Features (near term)

• Two‑way Google Calendar sync with conflict detection and graceful reconciliation.
• SMS notifications (reminders, confirmations, policy prompts) with opt‑in and per‑artist preferences.
• Enhanced search: filters (style, availability, price band), content search, and Ctrl+K command palette.
• Portfolio enhancements: collections/sets, multi‑artist features, richer video handling, and bulk editing.
• Education expansion: interactive aftercare wizard, symptom checker, printable kits, and multilingual content.

Long‑term Vision (12–24 months)

• Advanced analytics: booking funnel, artist performance, portfolio engagement, no‑show insights.
• Payment improvements: payment plans for large projects, partial payments, automated refunds/credits.
• Marketing hooks: email segments for consultations vs bookings, seasonal specials, referral tracking.
• Performance & a11y excellence: continuous budgets (images, JS), WCAG AA across the site.
• The “United Experience”: signature parallax narratives per artist, curated home features, and evolving visual stories.

Expansion Opportunities

• Multi‑location support (unified brand, per‑shop artists and calendars).
• Guest artist programs with temporary access windows and portfolio highlights.
• Merch/e‑commerce pilots (limited drops, prints), integrated with booking.
• Partnerships (aftercare products, studios/events) and co‑marketing pages.
• Mobile companion or PWA for artist tools (appointments, portfolio capture on the go).

Technical Considerations

Platform Requirements

• Target Platforms: Web (Next.js App Router); desktop/mobile browsers; responsive and touch-friendly.
• Browser/OS Support: Evergreen browsers (Chromium/WebKit/Firefox) on iOS/Android/Win/Mac; minimum iOS 15+, Android 10+ where feasible.
• Performance Requirements: LCP ≤ 2.5s p75; CLS ≤ 0.1; TBT ≤ 200ms on key pages; image budgets and lazy loading for portfolios.

Technology Preferences

• Frontend: Next.js 14 App Router, TypeScript, Tailwind + shadcn/ui, Zustand (local UI), React Query (server state).
• Backend/Runtime: Next.js server components & route handlers; server actions for same-origin auth mutations; Cloudflare Pages/Workers via OpenNext adapter.
• Auth & Security: NextAuth (Auth.js), JWT or DB sessions (documented choice); middleware for role-based guards; strict security headers (CSP nonce/hash, Referrer-Policy, X-Frame-Options, Permissions-Policy); cookies HttpOnly/Secure/SameSite=Strict; Zod validation across routes/forms/actions; rate limiting (Redis/Upstash).
• Data & Storage: Cloudflare D1 for relational data; R2 for media assets; all access via environment bindings; no direct DB connections; migrations sourced from sql/ executed via MCP; file uploads with signed URLs and server-side processing.
• Observability: OpenTelemetry for traces/metrics/logs; Sentry for exceptions & releases; log redaction for PII/secrets.
• CI/CD: Lint/typecheck/tests/build; migration dry-run; e2e (Playwright) on preview; bundle budgets; OpenNext build; Cloudflare Pages deploy; fail on type/compat errors.

Architecture Considerations

• Repository Structure: app/, components/ (ui/, custom/), lib/, hooks/, types/, sql/, docs/; no src/.
• Service Architecture: Monorepo single app; separation of concerns for admin vs public routes; route handlers for webhooks and cross-origin APIs; server actions for authed same-origin mutations.
• Integration Requirements: Google Calendar API (one-way MVP; two-way post-MVP); Stripe for deposits; Email provider (e.g., Resend/Postmark) and optional SMS (Twilio/MessageBird) post-MVP.
• Caching & Delivery: Tag-based caching with revalidateTag policy; CDN caching for static/media; image optimization strategy (Cloudflare Images or custom loader); SSR/ISR balance for artist/portfolio pages.
• Security/Compliance: Secrets via Wrangler secrets; .env.example canonical; lib/env.ts Zod schema; rate limits on auth/forms/APIs; content moderation hooks for uploads.
• Staging/Preview: Dedicated preview environments; owner-friendly staging URL; gated feature flags for risky changes.

Constraints & Assumptions

Constraints

• Budget: Fixed/limited; prioritize MVP features that directly impact bookings, artist self‑service, and brand consistency. Advanced features (two‑way calendar, SMS at scale, advanced search) deferred post‑MVP.
• Timeline: MVP delivery target 6–8 weeks from start; phased rollout by section (admin fixes → booking/deposits → public page unification → staging).
• Resources: Primarily single developer with documentation requirements; limited owner time for reviews; artists available for onboarding/testing windows.
• Technical:
  • Cloudflare Pages/Workers, D1, and R2 are required; OpenNext adapter; no direct DB connections.
  • ShadCN design system baseline; consistency with homepage and /artists is mandatory.
  • Security/validation per project rules (CSP/headers, NextAuth, Zod, rate limiting).
  • Stripe as single payment processor for MVP; Google Calendar one‑way sync MVP.
  • No CMS for owner beyond the custom admin; no Git required for owner/artist workflows.

Key Assumptions

• Artists are willing and able to self‑manage portfolios (basic crop/compress via UI) after invite.
• Clients accept deposits during booking and will use the portal for self‑service changes.
• Each artist can provide/authorize a Google account for calendar integration.
• Email provider (e.g., Resend/Postmark) is available with verified domain; optional SMS later.
• Staging/preview environment access is acceptable for owner reviews before release.
• Documentation will be sufficient for future maintainers without creator involvement.
• Performance and accessibility budgets can be met alongside rich imagery/parallax designs.
• Legal/policy pages (/terms, /privacy) content will be provided/approved by the studio.

Risks & Open Questions

Key Risks

• Admin dashboard regressions delaying onboarding; complex role/permission edge cases.
• Calendar sync issues (API quotas, timezones, two-way conflicts post-MVP) causing missed/duplicate events.
• R2 storage growth and egress costs if media optimization/policies aren’t enforced.
• Auth/session and state complexity (NextAuth, SSR/ISR, client cache) leading to subtle bugs.
• Payment disputes/refunds edge cases; policy misalignment causing chargebacks.
• Notification deliverability (email/SMS) and spam compliance.
• Accessibility/performance regressions with heavy imagery and parallax effects.
• Data consistency/race conditions between booking, payments, and calendar creation.

Open Questions

• Deposit policy specifics (amounts, non-refundable conditions, refund windows).
• Cancellation/rescheduling rules (cutoffs, fees, limits per client).
• Stripe configuration (connected account vs single account; geo/legal constraints).
• Email provider preference (Resend/Postmark) and SMS vendor (Twilio/MessageBird) timing.
• Artist Google account availability and access model (shared vs per-artist).
• Staging domain and access model for Christy reviews.
• Legal copy for /terms and /privacy and any HIPAA/age-related consent needs.
• Content moderation thresholds for portfolio uploads (NSFW boundaries, approvals).

Areas Needing Further Research

• Cloudflare D1 patterns at scale (indexes, migration strategy, transactional semantics).
• Best-practice NextAuth session model (JWT vs DB) for this app’s constraints.
• R2 cost optimization: formats, compression levels, responsive variants, caching TTLs.
• Stripe deposit flows for services (payment intents, partial refunds, disputes).
• Google Calendar API scopes/quotas and conflict resolution strategies.
• ShadCN patterns for parallax/scroll with a11y/perf considerations.
• Context7-validated search patterns for scalable artist/content discovery.

Appendices

A. Research Summary

• Brainstorming outputs consolidated in docs/brainstorming.md (admin/portfolio, booking/portal, public UX, technical architecture).
• Current repo docs informing direction: docs/Architecture.md, docs/ui-architecture.md, docs/PRD.md.
• Existing implementation constraints and rules: .clinerules/* (auth, Cloudflare, shadcn/ui, CI/CD, testing).

B. Stakeholder Input

• Owner (Christy) priorities:
  • Increase bookings and brand/talent exposure.
  • Single, unified system where artists self-manage; owner avoids Git/technical workflows.
  • Clean, safe, welcoming brand experience across all pages.
  • Staging previews and strong documentation for long-term maintainability.
• Target audience emphasis:
  • Serious collectors and premium clients.
  • First-timers (particularly women) seeking a safe, professional studio.

C. References

• Internal: docs/brainstorming.md, docs/Architecture.md, docs/ui-architecture.md, docs/PRD.md.
• Project standards: .clinerules/*
• Templates: .bmad-core/templates/project-brief-tmpl.yaml (basis for this brief).

Next Steps

Immediate Actions

1. Admin/Users: Diagnose and fix admin user creation bug; implement invite-based onboarding (expiring links) and roles (owner/admin/artist).
2. Assets: Establish R2 upload pipeline with server-side processing; build manual crop/compress UI; basic versioning.
3. Booking Foundations: Implement consultation, booking, and general inquiry forms; wire Stripe deposits; send email confirmations.
4. Calendar MVP: One-way event creation on artist Google Calendar after successful deposit; simple conflict checks.
5. Public UX Unification: Redesign /aftercare, /deposit, /terms, /privacy, /book to match ShadCN baseline and homepage/artist aesthetic; smooth scrolling.
6. Staging: Create preview workflow and owner-accessible staging URL; enable feature flags for risky changes.
7. Documentation: Draft README, setup guide, environment/secrets, deployment steps, and CHANGELOG structure.

PM Handoff This Project Brief provides the context for United Tattoo. Proceed to PRD generation using docs/PRD.md as the working artifact. Validate scope vs. MVP, document acceptance criteria for Phase 1 epics (Admin/Users, Assets, Booking, Calendar, Public UX, Staging/Docs), and prepare a release plan with checkpoints and success metrics.