thrilltrack-explorer/migration/PHASE_05_REVIEWS_SOCIAL.md

PHASE 5: Reviews & Social Features

Status: ⬜ Not Started
Estimated Time: 12-15 hours
Priority: HIGH
Depends On: Phase 1 (Foundation), Phase 4 (Entity Services)
Blocks: Phase 12 (Pages Migration)

---

🎯 Goal

Build service layer for reviews, ride credits, and top lists to replace ALL Supabase queries related to social features.

---

📋 Tasks

Task 5.1: Reviews Service (5 hours)

File: src/services/reviews/reviewsService.ts

Create Core Service

class ReviewsService extends BaseService {
  // GET /reviews/
  async getReviews(filters: ReviewFilters): Promise<PaginatedResponse<Review>>
  
  // GET /reviews/{id}/
  async getReview(id: string): Promise<Review>
  
  // POST /reviews/ (creates submission)
  async submitReview(data: ReviewSubmissionData): Promise<ContentSubmission>
  
  // PATCH /reviews/{id}/ (creates submission)
  async updateReview(id: string, data: Partial<ReviewData>): Promise<ContentSubmission>
  
  // DELETE /reviews/{id}/ (creates submission)
  async deleteReview(id: string, reason: string): Promise<ContentSubmission>
  
  // POST /reviews/{id}/helpful/
  async markHelpful(reviewId: string): Promise<void>
  
  // DELETE /reviews/{id}/helpful/
  async unmarkHelpful(reviewId: string): Promise<void>
  
  // GET /reviews/?entity_type=ride&entity_id={id}
  async getEntityReviews(entityType: string, entityId: string): Promise<Review[]>
  
  // GET /reviews/?user_id={id}
  async getUserReviews(userId: string): Promise<Review[]>
}

Checklist

• Create reviewsService.ts with all methods
• Create types.ts for Review types
• Create mappers.ts for API ↔ Frontend transformations
• Add error handling for all endpoints
• Implement proper TypeScript types
• Export from src/services/reviews/index.ts

---

Task 5.2: Ride Credits Service (3 hours)

File: src/services/rideCredits/rideCreditsService.ts

Create Core Service

class RideCreditsService extends BaseService {
  // GET /ride-credits/
  async getRideCredits(userId: string): Promise<UserRideCredit[]>
  
  // GET /ride-credits/{id}/
  async getRideCredit(id: string): Promise<UserRideCredit>
  
  // POST /ride-credits/ (creates submission)
  async submitRideCredit(data: RideCreditData): Promise<ContentSubmission>
  
  // PATCH /ride-credits/{id}/ (creates submission)
  async updateRideCredit(id: string, data: Partial<RideCreditData>): Promise<ContentSubmission>
  
  // DELETE /ride-credits/{id}/ (creates submission)
  async deleteRideCredit(id: string): Promise<ContentSubmission>
  
  // GET /ride-credits/?ride_id={id}
  async getRideRideCredits(rideId: string): Promise<UserRideCredit[]>
}

Checklist

• Create rideCreditsService.ts with all methods
• Create types for ride credits
• Create mappers for API transformations
• Handle submission creation properly
• Export from src/services/rideCredits/index.ts

---

Task 5.3: Top Lists Service (4 hours)

File: src/services/topLists/topListsService.ts

Create Core Service

class TopListsService extends BaseService {
  // GET /top-lists/
  async getTopLists(filters?: TopListFilters): Promise<UserTopList[]>
  
  // GET /top-lists/{id}/
  async getTopList(id: string): Promise<UserTopList>
  
  // POST /top-lists/
  async createTopList(data: TopListData): Promise<UserTopList>
  
  // PATCH /top-lists/{id}/
  async updateTopList(id: string, data: Partial<TopListData>): Promise<UserTopList>
  
  // DELETE /top-lists/{id}/
  async deleteTopList(id: string): Promise<void>
  
  // GET /top-lists/{id}/items/
  async getTopListItems(listId: string): Promise<UserTopListItem[]>
  
  // POST /top-lists/{id}/items/
  async addTopListItem(listId: string, item: TopListItemData): Promise<UserTopListItem>
  
  // PATCH /top-lists/{id}/items/reorder/
  async reorderTopListItems(listId: string, itemIds: string[]): Promise<void>
  
  // DELETE /top-lists/{id}/items/{itemId}/
  async removeTopListItem(listId: string, itemId: string): Promise<void>
  
  // GET /top-lists/?user_id={id}
  async getUserTopLists(userId: string): Promise<UserTopList[]>
}

Checklist

• Create topListsService.ts with all methods
• Create types for top lists and items
• Create mappers for API transformations
• Handle reordering logic
• Handle item CRUD operations
• Export from src/services/topLists/index.ts

---

Task 5.4: Update Review Components (3 hours)

Files to Update:

• src/components/reviews/ReviewForm.tsx
• src/components/reviews/ReviewsList.tsx
• src/components/reviews/ReviewCard.tsx
• src/components/reviews/HelpfulButton.tsx

Checklist

• Replace supabase.from('reviews') with reviewsService
• Update review submission to use service
• Update helpful votes to use service
• Update review deletion to use service
• Test review CRUD operations
• Verify error handling works

---

Task 5.5: Update Ride Credit Components (2 hours)

Files to Update:

• src/components/profile/RideCreditsManager.tsx
• src/components/profile/AddRideCreditDialog.tsx
• src/components/profile/RideCreditCard.tsx

Checklist

• Replace all Supabase calls with rideCreditsService
• Update submission flow to use service
• Test adding ride credits
• Test editing ride credits
• Test deleting ride credits
• Verify moderation queue receives submissions

---

Task 5.6: Update Top Lists Components (3 hours)

Files to Update:

• src/components/lists/UserListManager.tsx
• src/components/lists/ListDisplay.tsx
• src/components/lists/ListItemEditor.tsx
• src/components/lists/ListSearch.tsx

Checklist

• Replace all Supabase calls with topListsService
• Update list CRUD operations
• Update item reordering logic
• Test creating/editing lists
• Test adding/removing/reordering items
• Verify list sharing works (if implemented)

---

🎯 Success Criteria

Service Layer

• All three services (reviews, rideCredits, topLists) created
• All services extend BaseService
• All services have proper TypeScript types
• All services have error handling
• All services have mappers for API transformations

Components

• Zero supabase.from('reviews') calls
• Zero supabase.from('user_ride_credits') calls
• Zero supabase.from('user_top_lists') calls
• Zero supabase.from('user_top_list_items') calls
• All review operations work
• All ride credit operations work
• All top list operations work

Testing

• Can create a review (goes to moderation)
• Can mark review as helpful
• Can add a ride credit (goes to moderation)
• Can create a top list
• Can add items to top list
• Can reorder top list items
• Can delete top list items
• Can delete entire top list

Sacred Pipeline

• Review submissions go through moderation
• Review updates go through moderation
• Review deletions go through moderation
• Ride credit submissions go through moderation
• Pipeline integrity maintained

---

📝 Implementation Notes

Review Submissions

• Reviews are user-generated content and MUST go through the Sacred Pipeline
• Use reviewsService.submitReview() which creates a ContentSubmission
• Only approved reviews appear in the system

Ride Credits

• Ride credits are also user-generated and MUST go through moderation
• Users claim they've ridden a ride, moderators verify
• Auto-crediting on review approval should still work

Top Lists

• Top lists are personal user content
• May NOT require moderation (check with backend team)
• Item reordering is immediate (no moderation)

Helpful Votes

• Marking a review as helpful is immediate (no moderation)
• Backend tracks vote counts automatically
• Each user can only vote once per review

---

🔗 Related Files

Services

• src/services/reviews/reviewsService.ts
• src/services/reviews/types.ts
• src/services/reviews/mappers.ts
• src/services/rideCredits/rideCreditsService.ts
• src/services/topLists/topListsService.ts

Components

• All files in src/components/reviews/
• All files in src/components/profile/ (ride credits)
• All files in src/components/lists/ (top lists)

Hooks

• src/hooks/useReviews.ts
• src/hooks/useRideCredits.ts
• src/hooks/useTopLists.ts

---

⏭️ Next Phase

Phase 6: Moderation & Admin - Create moderation service and update moderation queue components.