united-tattoo/artist_profile_refactor_implementation_plan.md

# Artist Profile Refactor Implementation Plan

## Overview
Refactor the artists grid and individual artist profile pages to load content from a Cloudflare D1 database instead of static data. Enable artists to log into backend profiles where they can manage their portfolio images, bio, and other information. The existing `data/artists.ts` will serve as seed data for the database.

This implementation connects the existing database schema, API routes, and authentication system with the public-facing components, while also creating an artist dashboard for self-service portfolio management.

## Types
Database and API type definitions for artist profile management.

**Key Type Updates:**
- Ensure `Artist` interface in `types/database.ts` matches D1 schema columns
- Add `ArtistWithPortfolio` type that includes populated `portfolioImages` array
- Create `PublicArtist` type for sanitized public API responses
- Add `ArtistDashboardStats` type for artist-specific analytics

**New Type Definitions:**
```typescript
// types/database.ts additions
export interface ArtistWithPortfolio extends Artist {
  portfolioImages: PortfolioImage[]
  user?: {
    name: string
    email: string
    avatar?: string
  }
}

export interface PublicArtist {
  id: string
  name: string
  bio: string
  specialties: string[]
  instagramHandle?: string
  portfolioImages: PortfolioImage[]
  isActive: boolean
  hourlyRate?: number
}

export interface ArtistDashboardStats {
  totalImages: number
  activeImages: number
  profileViews?: number
  lastUpdated: Date
}
```

## Files

### Files to Modify

**1. `lib/db.ts`**
- Add `getArtistWithPortfolio(id: string)` function that joins artists with portfolio_images
- Add `getPublicArtists()` function that returns only active artists with public portfolio images
- Add `getArtistByUserId(userId: string)` function for artist dashboard access
- Update `getArtists()` to parse JSON fields properly (specialties)

**2. `app/api/artists/route.ts`**
- Update GET handler to return artists with portfolio images
- Add pagination support to prevent loading all artists at once
- Add filtering by specialty and search query
- Ensure responses match `PublicArtist` type for public endpoints

**3. `app/api/artists/[id]/route.ts`**
- Create this file (currently missing)
- Add GET endpoint to fetch single artist with portfolio
- Add PUT endpoint for updating artist (admin or artist themselves)
- Add authorization check (admin or owner)

**4. `components/artists-grid.tsx`**
- Remove hardcoded `artists` array
- Add `useEffect` to fetch artists from `/api/artists`
- Add loading and error states
- Update to use API response data structure
- Keep existing filtering UI but apply to fetched data
- Update routing to use database IDs instead of hardcoded IDs

**5. `components/artist-portfolio.tsx`**
- Remove hardcoded `artistsData` object
- Add `useEffect` to fetch artist data from `/api/artists/${artistId}`
- Add loading and error states
- Update image galleries to use portfolio images from database
- Handle missing artist gracefully
- Update data structure to match API response

**6. `components/artists-page-section.tsx`**
- Remove import from `@/data/artists`
- Fetch artists from API in component
- Add loading state

**7. `components/artists-section.tsx`**
- Remove import from `@/data/artists`
- Fetch artists from API
- Add loading skeleton

**8. `components/booking-form.tsx`**
- Update artist selection to fetch from API
- Remove import from `@/data/artists`

**9. `app/artists/[id]/page.tsx`**
- Update to use database-friendly slug or ID
- May need to support both slug-based and ID-based routing during migration

**10. `lib/auth.ts`**
- Add `getArtistSession()` helper that checks if logged-in user is an artist
- Add `requireArtistAuth()` helper for artist-only routes

**11. `sql/schema.sql`**
- Add missing columns if needed (review against `data/artists.ts` structure)
- Add indexes for performance (slug, user_id lookups)
- Consider adding `slug` column to artists table for SEO-friendly URLs

**12. `lib/data-migration.ts`**
- Update migration to use all artists from `data/artists.ts`
- Fix portfolio image creation to handle all work images
- Add proper slug generation from artist names
- Ensure idempotency (can be run multiple times safely)

### Files to Create

**1. `app/artist-dashboard/page.tsx`**
- New artist dashboard home page
- Show artist's own profile overview
- Display stats (total images, views, etc.)
- Quick links to edit profile and portfolio

**2. `app/artist-dashboard/layout.tsx`**
- Layout wrapper for artist dashboard
- Navigation sidebar for dashboard sections
- Artist profile header
- Requires ARTIST or SHOP_ADMIN role

**3. `app/artist-dashboard/profile/page.tsx`**
- Artist profile edit page
- Reuse `<ArtistForm>` component but filtered for artist-editable fields
- Artists can edit: bio, specialties, instagram, hourly rate
- Cannot edit: name, email, isActive (admin only)

**4. `app/artist-dashboard/portfolio/page.tsx`**
- Portfolio image management page
- Upload new images
- Edit captions and tags
- Reorder images (drag and drop)
- Delete images
- Set visibility (public/private)

**5. `app/api/artists/me/route.ts`**
- GET endpoint to fetch current logged-in artist's data
- Requires authentication
- Returns artist profile for logged-in user

**6. `app/api/portfolio/route.ts`** (if not exists)
- POST endpoint to add portfolio images
- Requires artist or admin auth
- Handles R2 upload integration

**7. `app/api/portfolio/[id]/route.ts`**
- GET single portfolio image
- PUT to update (caption, tags, order, visibility)
- DELETE to remove image
- Authorization: admin or image owner

**8. `components/admin/portfolio-manager.tsx`**
- Reusable component for managing portfolio images
- Used in both admin and artist dashboard
- Image upload, grid display, edit modals
- Drag-drop reordering

**9. `hooks/use-artist-data.ts`**
- Custom hook for fetching artist data
- Handles loading, error states
- Caching with SWR or React Query pattern
- Reusable across components

**10. `middleware.ts` (update)**
- Add route protection for `/artist-dashboard/*`
- Verify user has ARTIST role
- Redirect to signin if not authenticated

### Files to Delete (after migration)

**None immediately** - Keep `data/artists.ts` as seed data reference

## Functions

### New Functions in `lib/db.ts`

**1. `getArtistWithPortfolio(id: string, env?: any): Promise<ArtistWithPortfolio | null>`**
- Fetch artist by ID
- Join with portfolio_images table
- Parse JSON fields (specialties, tags)
- Return combined object with images array

**2. `getPublicArtists(filters?: ArtistFilters, env?: any): Promise<PublicArtist[]>`**
- Fetch only active artists
- Include only public portfolio images
- Apply filters (specialty, search)
- Sanitize data for public consumption

**3. `getArtistByUserId(userId: string, env?: any): Promise<Artist | null>`**
- Fetch artist record by user_id
- Used for artist dashboard access
- Returns full artist data for owner

**4. `getArtistBySlug(slug: string, env?: any): Promise<ArtistWithPortfolio | null>`**
- Fetch artist by URL slug
- Join with portfolio images
- For SEO-friendly URLs

**5. `updatePortfolioImageOrder(artistId: string, imageOrders: Array<{id: string, orderIndex: number}>, env?: any): Promise<void>`**
- Batch update order indices
- Used for drag-drop reordering
- Transaction support if available

### New Functions in `lib/auth.ts`

**1. `getArtistSession(): Promise<{ artist: Artist, user: User } | null>`**
- Get current session
- Check if user has ARTIST role
- Fetch associated artist record
- Return combined data or null

**2. `requireArtistAuth(): Promise<{ artist: Artist, user: User }>`**
- Like requireAuth but specifically for artists
- Throws error if not an artist
- Returns artist and user data

**3. `canEditArtist(userId: string, artistId: string): Promise<boolean>`**
- Check if user can edit specific artist
- True if: user is the artist, SHOP_ADMIN, or SUPER_ADMIN
- Used for authorization checks

### Modified Functions

**1. `lib/db.ts:getArtists()`**
- Add optional `includePortfolio` parameter
- Parse JSON fields properly
- Add error handling

**2. `lib/db.ts:createArtist()`**
- Add slug generation
- Ensure user creation if needed
- Return artist with portfolio array (empty initially)

**3. `lib/data-migration.ts:migrateArtistData()`**
- Update to migrate all fields from `data/artists.ts`
- Add slug generation
- Handle all portfolio images
- Add progress logging

## Classes

### New Classes

**1. `ArtistDashboardManager` (optional)**
- Class to encapsulate artist dashboard operations
- Methods: getStats(), updateProfile(), getPortfolio()
- Centralizes artist-specific business logic
- Located in `lib/artist-dashboard.ts`

**No other new classes required** - Functional approach with helper functions is sufficient

## Dependencies

### Current Dependencies (verify versions)
- `next`: 15.x
- `next-auth`: Latest compatible with Next.js 15
- `@tanstack/react-table`: For admin tables
- `react-hook-form`: Form management
- `zod`: Schema validation
- `@hookform/resolvers`: Zod integration with react-hook-form

### New Dependencies to Install

**1. `swr` or `@tanstack/react-query`**
- For client-side data fetching and caching
- Recommended: `swr` (lighter weight)
- Install: `npm install swr`

**2. `@dnd-kit/core`, `@dnd-kit/sortable` (optional)**
- For drag-drop portfolio reordering
- Only if implementing drag-drop UI
- Install: `npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities`

**3. `sharp` (dev dependency)**
- Image optimization during migration
- May already be included with Next.js

### Configuration Updates

**1. `next.config.mjs`**
- Ensure image optimization configured for R2 URLs
- Add remote patterns for portfolio image domains

**2. `wrangler.toml`**
- Verify D1 database binding name matches code
- Verify R2 bucket binding for portfolio uploads

**3. `.env.local`**
- No new env vars needed (using Cloudflare bindings)

## Testing

### Unit Tests to Create

**1. `__tests__/lib/db.test.ts`**
- Test artist CRUD operations
- Test portfolio image operations
- Mock D1 database
- Verify JSON parsing

**2. `__tests__/lib/auth.test.ts`**
- Test artist authentication helpers
- Test authorization checks
- Mock NextAuth session

**3. `__tests__/hooks/use-artist-data.test.ts`**
- Test hook with mock data
- Test loading and error states
- Test cache behavior

### Integration Tests to Create

**1. `__tests__/api/artists.test.ts`**
- Test GET /api/artists endpoint
- Test filtering and pagination
- Test error handling

**2. `__tests__/api/artists/[id].test.ts`**
- Test GET single artist
- Test PUT artist update
- Test authorization

**3. `__tests__/api/portfolio.test.ts`**
- Test portfolio CRUD operations
- Test file uploads
- Test authorization

### Component Tests to Update

**1. `__tests__/components/artists-grid.test.tsx`**
- Update to mock API fetch
- Test loading states
- Test error states
- Test filtering

**2. `__tests__/components/artist-portfolio.test.tsx`**
- Update to mock API fetch
- Test portfolio image display
- Test modal interactions

### E2E Test Scenarios

**1. Artist Login and Profile Edit**
- Artist signs in
- Navigates to dashboard
- Edits bio and specialties
- Saves successfully

**2. Portfolio Image Upload**
- Artist uploads images
- Images appear in portfolio
- Reorders images
- Deletes an image

**3. Public Artist Profile View**
- Anonymous user visits artist page
- Sees artist info and portfolio
- Images load correctly
- Filtering works

**4. Admin Artist Management**
- Admin creates new artist
- Edits artist information
- Uploads portfolio images for artist
- Deactivates artist

## Implementation Order

### Phase 1: Database & API Foundation (Steps 1-5)

**1. Update Database Schema and Migration**
- Review and update `sql/schema.sql` if needed (add slug column, indexes)
- Update `lib/data-migration.ts` to properly migrate all artist data from `data/artists.ts`
- Test migration script locally
- Verify all artists and portfolio images are created correctly

**2. Enhance Database Functions**
- Update `lib/db.ts` with new functions: `getArtistWithPortfolio`, `getPublicArtists`, `getArtistByUserId`, `getArtistBySlug`
- Update existing functions to properly parse JSON fields
- Add error handling and logging
- Write unit tests for new functions

**3. Create/Update API Endpoints**
- Create `app/api/artists/[id]/route.ts` with GET and PUT handlers
- Update `app/api/artists/route.ts` to support filtering and return portfolio images
- Create `app/api/artists/me/route.ts` for artist self-access
- Add authorization checks to all endpoints
- Test endpoints with Postman or similar

**4. Update Authentication Helpers**
- Add `getArtistSession()` and `requireArtistAuth()` to `lib/auth.ts`
- Add `canEditArtist()` authorization helper
- Test with mock sessions

**5. Create Data Fetching Hook**
- Create `hooks/use-artist-data.ts` with SWR
- Implement loading and error states
- Add caching and revalidation
- Test hook in isolation

### Phase 2: Public-Facing Components (Steps 6-8)

**6. Refactor Artists Grid**
- Update `components/artists-grid.tsx` to fetch from API
- Remove hardcoded data
- Add loading skeleton UI
- Add error handling UI
- Test filtering and pagination
- Verify routing to individual artists works

**7. Refactor Artist Portfolio Page**
- Update `components/artist-portfolio.tsx` to fetch from API
- Remove hardcoded `artistsData`
- Add loading states
- Update image galleries to use database images
- Test with various artist IDs
- Verify modal/lightbox still works

**8. Update Supporting Components**
- Update `components/artists-section.tsx` to use API
- Update `components/artists-page-section.tsx` to use API
- Update `components/booking-form.tsx` artist selection
- Add loading states to all
- Test home page and booking flow

### Phase 3: Artist Dashboard (Steps 9-12)

**9. Create Artist Dashboard Layout**
- Create `app/artist-dashboard/layout.tsx` with navigation
- Add role protection in middleware
- Create dashboard home page `app/artist-dashboard/page.tsx`
- Display artist stats and quick links
- Test authentication and routing

**10. Build Profile Editor**
- Create `app/artist-dashboard/profile/page.tsx`
- Reuse and adapt `<ArtistForm>` component
- Filter fields for artist-editable only
- Connect to PUT `/api/artists/me` endpoint
- Test profile updates

**11. Build Portfolio Manager**
- Create `app/artist-dashboard/portfolio/page.tsx`
- Create `components/admin/portfolio-manager.tsx` component
- Implement image upload UI
- Add image editing (captions, tags, visibility)
- Test upload and management

**12. Implement Portfolio API**
- Create `app/api/portfolio/route.ts` for creating images
- Create `app/api/portfolio/[id]/route.ts` for update/delete
- Integrate with R2 upload system
- Add authorization checks
- Test full upload flow

### Phase 4: Admin Enhancements (Steps 13-14)

**13. Update Admin Artist Management**
- Update `app/admin/artists/[id]/page.tsx` to use API
- Enhance `<ArtistForm>` with portfolio management
- Test admin CRUD operations
- Verify authorization works

**14. Add Portfolio Management to Admin**
- Integrate `<PortfolioManager>` into admin artist edit page
- Allow admins to manage any artist's portfolio
- Test admin portfolio operations

### Phase 5: Testing & Refinement (Steps 15-17)

**15. Write and Run Tests**
- Create all unit tests for new functions
- Create integration tests for API endpoints
- Create component tests
- Run full test suite
- Fix any failing tests

**16. Performance Optimization**
- Add database indexes for common queries
- Implement image lazy loading
- Add proper caching headers to API
- Optimize large portfolio image displays
- Test with large datasets

**17. Migration & Deployment**
- Run migration on development D1 database
- Test full application flow
- Create migration checklist for production
- Deploy to staging environment
- Final testing in staging
- Production deployment

### Phase 6: Documentation & Cleanup (Step 18)

**18. Documentation and Cleanup**
- Document new API endpoints
- Update README with setup instructions
- Add inline code comments
- Create artist onboarding guide
- Remove deprecated code/comments
- Archive old implementation if needed