thrillwiki_laravel/memory-bank/features/ReviewsSystemArchitecture.md

# Reviews System Architecture Plan
**Date**: June 21, 2025  
**Status**: 🎯 **PRIORITY 2 TASK - ARCHITECTURE PLANNING PHASE**

## 🚨 CRITICAL DISCOVERY: Architecture Gap Analysis

### **Current Implementation vs Django Parity Requirements**

**MAJOR FINDING**: The current Laravel implementation has a **fundamental architectural mismatch** with the Django reference implementation that must be resolved to achieve Django parity.

### **Django Implementation Analysis**
Based on analysis of `//Volumes/macminissd/Projects/thrillwiki_django_no_react/reviews/models.py`:

**Django Architecture**:
- **Generic Reviews**: Uses ContentType + GenericForeignKey for polymorphic relationships
- **Review Model**: Can review ANY entity (rides, parks, etc.) through `content_type` + `object_id`
- **Rating Scale**: 1-10 (not 1-5 as currently implemented)
- **Required Fields**: `title`, `visit_date` (both required in Django)
- **Additional Models**:
  - `ReviewImage`: Attached images to reviews
  - `ReviewLike`: Like/helpful vote system  
  - `ReviewReport`: Moderation reporting system
- **Advanced Features**: Photo uploads, moderation workflow, reporting system

**Current Laravel Implementation**:
- **Rigid Reviews**: Uses `reviewable_type` + `reviewable_id` morphTo relationship
- **Limited Scope**: Only set up for Ride reviews currently
- **Rating Scale**: 1-5 (incorrect scale)
- **Optional Fields**: `title` and `visit_date` are optional (should be required)
- **Missing Models**: No ReviewImage, ReviewLike, or ReviewReport equivalents
- **Incomplete Features**: No photo uploads, limited moderation, no reporting

### **Critical Architecture Decisions Required**

## ✅ ARCHITECTURAL DECISIONS

### **1. Database Schema Architecture**
**Decision**: Implement Django-compatible polymorphic review system

**Schema Requirements**:
```sql
-- Core Review Table (Django Parity)
reviews:
  - id (primary key)
  - content_type_id (foreign key) -- Enables polymorphic reviews
  - object_id (integer) -- ID of reviewed entity
  - user_id (foreign key to users)
  - rating (integer 1-10) -- Match Django scale
  - title (string, required) -- Match Django requirement
  - content (text, required)
  - visit_date (date, required) -- Match Django requirement
  - is_published (boolean, default true)
  - moderation_notes (text, nullable)
  - moderated_by_id (foreign key to users, nullable)
  - moderated_at (timestamp, nullable)
  - created_at (timestamp)
  - updated_at (timestamp)

-- Review Images (Django Parity)
review_images:
  - id (primary key)
  - review_id (foreign key to reviews)
  - image_path (string) -- Store image file path
  - caption (string, optional)
  - order (integer, default 0)
  - created_at (timestamp)

-- Review Likes/Helpful Votes (Django Parity)
review_likes:
  - id (primary key)
  - review_id (foreign key to reviews)
  - user_id (foreign key to users)
  - created_at (timestamp)
  - UNIQUE(review_id, user_id)

-- Review Reports (Django Parity)
review_reports:
  - id (primary key)
  - review_id (foreign key to reviews)
  - user_id (foreign key to users)
  - reason (text, required)
  - resolved (boolean, default false)
  - resolved_by_id (foreign key to users, nullable)
  - resolution_notes (text, nullable)
  - resolved_at (timestamp, nullable)
  - created_at (timestamp)
```

### **2. Entity Integration Strategy**
**Decision**: Support reviews for multiple entity types (Parks, Rides, potentially Operators)

**Supported Reviewable Entities**:
1. **Rides** (Primary) - Individual ride experiences
2. **Parks** (Secondary) - Overall park experiences  
3. **Future**: Operators, Areas, Events

**Implementation Approach**:
- Laravel's `morphTo`/`morphMany` relationships for polymorphic associations
- Reviewable trait for consistent interface across entities
- Centralized review logic in Review model

### **3. Component Architecture Strategy**
**Decision**: Reusable component system with entity-specific customization

**Core Livewire Components**:

1. **ReviewFormComponent** (Reusable)
   - Generic review creation/editing
   - Entity-agnostic design
   - Configurable for different reviewable types
   - Real-time validation
   - Image upload support

2. **ReviewListComponent** (Reusable)  
   - Generic review display
   - Pagination, sorting, filtering
   - Entity-agnostic design
   - Helpful vote functionality
   - Moderation actions (admin)

3. **ReviewModerationComponent** (Admin)
   - Cross-entity review moderation
   - Batch operations
   - Report management
   - Statistics dashboard

4. **Entity-Specific Integrations**:
   - `RideReviewSection` - Integrates with ride detail pages
   - `ParkReviewSection` - Integrates with park detail pages
   - `ReviewWidgets` - Reusable review display widgets

### **4. Performance Strategy**
**Decision**: Multi-layer caching with real-time statistics

**Caching Architecture**:
- **Model Caching**: Cache review aggregates (average rating, count)
- **Query Caching**: Cache expensive review queries
- **Statistics Caching**: Cache review statistics per entity
- **Real-time Updates**: Livewire for immediate UI feedback

**Performance Optimizations**:
- Eager loading with `with()` for relationships
- Database indexes on frequently queried fields
- Pagination for large review sets
- Image optimization for review photos

### **5. Generator Integration Strategy**
**Decision**: Leverage ThrillWiki custom generators for rapid development

**Generator Commands for Reviews**:
```bash
# Create Review system models
php artisan make:thrillwiki-model Review --migration --factory --with-relationships --cached --api-resource --with-tests
php artisan make:thrillwiki-model ReviewImage --migration --with-relationships --with-tests
php artisan make:thrillwiki-model ReviewLike --migration --with-relationships --with-tests  
php artisan make:thrillwiki-model ReviewReport --migration --with-relationships --with-tests

# Create review components
php artisan make:thrillwiki-livewire ReviewFormComponent --reusable --with-tests --cached
php artisan make:thrillwiki-livewire ReviewListComponent --reusable --with-tests --cached --paginated
php artisan make:thrillwiki-livewire ReviewModerationComponent --with-tests

# Create full CRUD system
php artisan make:thrillwiki-crud Review --api --with-tests
```

## 🏗️ IMPLEMENTATION ROADMAP

### **Phase 1: Database Foundation** (Priority: Critical)
**Objective**: Establish Django-compatible database schema

**Tasks**:
1. **Schema Migration Strategy**
   - Analyze current `reviews` and `helpful_votes` tables
   - Create migration to add missing Django parity fields
   - Add `content_type_id`, `object_id` for polymorphic reviews
   - Modify `rating` field to support 1-10 scale
   - Make `title` and `visit_date` required fields

2. **New Model Creation**
   - Generate `ReviewImage` model with file upload capabilities
   - Generate `ReviewLike` model (rename from HelpfulVote for clarity)
   - Generate `ReviewReport` model for moderation workflow
   - Update existing models for Django parity

3. **Relationship Updates**
   - Update Review model to use polymorphic relationships
   - Add reviewable trait to Ride and Park models
   - Establish proper foreign key relationships

### **Phase 2: Core Model Enhancement** (Priority: Critical)
**Objective**: Bring Review model to full Django parity

**Tasks**:
1. **Review Model Refactoring**
   - Implement polymorphic `reviewable()` relationship
   - Add required field validation (title, visit_date)
   - Implement 1-10 rating scale validation
   - Add image relationship management
   - Add like/report relationship management

2. **Supporting Model Implementation**
   - ReviewImage with file upload and ordering
   - ReviewLike with toggle functionality
   - ReviewReport with moderation workflow
   - Proper indexes and constraints

3. **Business Logic Implementation**
   - Review creation with validation
   - Moderation workflow (approve/reject/edit)
   - Image upload and management
   - Helpful vote system
   - Reporting and resolution workflow

### **Phase 3: Component Development** (Priority: High)
**Objective**: Create reusable, high-performance Livewire components

**Tasks**:
1. **ReviewFormComponent**
   - Multi-entity support (rides, parks)
   - Real-time validation
   - Image upload interface
   - Edit mode support
   - Success/error handling

2. **ReviewListComponent**
   - Polymorphic review display
   - Advanced filtering and sorting
   - Pagination optimization
   - Helpful vote interface
   - Admin moderation controls

3. **ReviewModerationComponent**
   - Cross-entity moderation queue
   - Batch operation support
   - Report management interface
   - Moderation statistics
   - Search and filtering

### **Phase 4: Integration & Testing** (Priority: High)
**Objective**: Integrate with existing entities and ensure quality

**Tasks**:
1. **Entity Integration**
   - Update Ride detail pages with review system
   - Update Park detail pages with review system
   - Add review widgets to listing pages
   - Implement review statistics display

2. **Performance Optimization**
   - Implement caching strategies
   - Optimize database queries
   - Add real-time updates
   - Image optimization and CDN integration

3. **Testing & Validation**
   - Unit tests for all models and methods
   - Component tests for Livewire interactions
   - Feature tests for complete workflows
   - Django parity validation tests

### **Phase 5: Advanced Features** (Priority: Medium)
**Objective**: Complete feature parity with additional enhancements

**Tasks**:
1. **Advanced Moderation**
   - Automated spam detection
   - User reputation system
   - Content filtering
   - Escalation workflows

2. **Analytics & Insights**
   - Review analytics dashboard
   - Sentiment analysis integration
   - Review trends and insights
   - Performance metrics

3. **Enhanced User Experience**
   - Review recommendation system
   - Social features (follow reviewers)
   - Review collections
   - Mobile-optimized interface

## 🔧 TECHNICAL SPECIFICATIONS

### **Model Relationships**
```php
// Review Model Relationships
class Review extends Model {
    // Polymorphic relationship
    public function reviewable(): MorphTo
    
    // Standard relationships  
    public function user(): BelongsTo
    public function moderator(): BelongsTo
    public function images(): HasMany
    public function likes(): HasMany
    public function reports(): HasMany
}

// Reviewable Entities
class Ride extends Model {
    public function reviews(): MorphMany
    public function getAverageRatingAttribute(): float
    public function getReviewCountAttribute(): int
}

class Park extends Model {
    public function reviews(): MorphMany
    public function getAverageRatingAttribute(): float  
    public function getReviewCountAttribute(): int
}
```

### **API Design**
**RESTful API Endpoints** (Django Parity):
```
GET    /api/reviews                 # List reviews (with filtering)
POST   /api/reviews                 # Create review
GET    /api/reviews/{id}            # Show review  
PUT    /api/reviews/{id}            # Update review
DELETE /api/reviews/{id}            # Delete review

GET    /api/{entity}/{id}/reviews   # Entity-specific reviews
POST   /api/{entity}/{id}/reviews   # Create review for entity

POST   /api/reviews/{id}/like       # Toggle helpful vote
POST   /api/reviews/{id}/report     # Report review
```

### **Component Props Interface**
```php
// ReviewFormComponent
public string $reviewableType;    // 'App\Models\Ride'
public int $reviewableId;         // Entity ID
public ?int $reviewId = null;     // For editing

// ReviewListComponent  
public string $reviewableType;    // 'App\Models\Ride'
public int $reviewableId;         // Entity ID
public string $sortBy = 'date';   // 'date', 'rating', 'helpful'
public array $filters = [];       // Rating filters, etc.
```

## 🔍 DJANGO PARITY CHECKLIST

### **Database Schema** ✅ **PLANNED**
- [x] Polymorphic review relationships (content_type + object_id)
- [x] 1-10 rating scale (match Django)
- [x] Required title and visit_date fields
- [x] Review images with caption and ordering
- [x] Review likes/helpful votes
- [x] Review reporting system
- [x] Moderation workflow (is_published, moderated_by, etc.)

### **Model Features** ⚠️ **REQUIRES IMPLEMENTATION**
- [ ] Generic review creation for any entity
- [ ] Image upload and management
- [ ] Helpful vote toggle functionality
- [ ] Moderation workflow methods
- [ ] Report creation and resolution
- [ ] Statistics calculation (average rating, counts)

### **Component Features** ⚠️ **REQUIRES IMPLEMENTATION**
- [ ] Multi-entity review form
- [ ] Image upload interface
- [ ] Real-time validation
- [ ] Advanced filtering and sorting
- [ ] Moderation interface
- [ ] Report management
- [ ] Batch operations

### **Performance Features** ⚠️ **REQUIRES IMPLEMENTATION**  
- [ ] Multi-layer caching
- [ ] Query optimization
- [ ] Real-time updates
- [ ] Image optimization
- [ ] Statistics caching

## 🚀 DEVELOPMENT ACCELERATION STRATEGY

### **Generator Utilization**
**Speed Advantage**: 98-99% faster development using ThrillWiki custom generators

**Planned Generator Usage**:
1. **Model Generation**: Use `make:thrillwiki-model` for all review models
2. **Component Generation**: Use `make:thrillwiki-livewire` for reusable components
3. **CRUD Generation**: Use `make:thrillwiki-crud` for admin interfaces
4. **Test Generation**: Include `--with-tests` for all generated code

**Time Savings Projection**:
- **Manual Implementation**: 3-4 weeks for complete review system
- **Generator-Accelerated**: 3-4 days for complete review system
- **Speed Multiplier**: 7-10x faster development

### **Component Reuse Strategy**
**Maximum Reusability**: Design components for use across multiple entities

**Reuse Patterns**:
- ReviewFormComponent used for Rides, Parks, future entities
- ReviewListComponent used across all reviewable entities  
- Shared validation logic and UI patterns
- Consistent styling and behavior

## 📋 SUCCESS METRICS

### **Django Parity Validation**
- [ ] All Django review features implemented
- [ ] Identical database schema structure
- [ ] Matching API response formats
- [ ] Equivalent user workflows
- [ ] Performance parity or improvement

### **Performance Targets**
- [ ] Review list loading < 200ms
- [ ] Review form submission < 300ms
- [ ] Image upload < 2 seconds
- [ ] Statistics calculation < 100ms
- [ ] 99.9% uptime under normal load

### **Quality Assurance**
- [ ] 100% test coverage for models
- [ ] 90%+ test coverage for components
- [ ] All user workflows tested
- [ ] Performance benchmarks met
- [ ] Security review completed

## 🎯 NEXT IMMEDIATE STEPS

### **For Code Mode Implementation**
1. **Database Migration**: Create migration to add missing Django parity fields
2. **Model Generation**: Use generators to create ReviewImage, ReviewLike, ReviewReport
3. **Model Updates**: Update existing Review model for polymorphic relationships
4. **Component Creation**: Generate core Livewire components
5. **Integration Testing**: Validate Django parity compliance

### **Ready-to-Execute Commands**
```bash
# Phase 1: Model Foundation
php artisan make:thrillwiki-model ReviewImage --migration --with-relationships --with-tests
php artisan make:thrillwiki-model ReviewLike --migration --with-relationships --with-tests  
php artisan make:thrillwiki-model ReviewReport --migration --with-relationships --with-tests

# Phase 2: Component Development
php artisan make:thrillwiki-livewire ReviewFormComponent --reusable --with-tests --cached
php artisan make:thrillwiki-livewire ReviewListComponent --reusable --with-tests --cached --paginated
php artisan make:thrillwiki-livewire ReviewModerationComponent --with-tests

# Phase 3: API & CRUD
php artisan make:thrillwiki-crud Review --api --with-tests
```

This comprehensive architecture plan provides a clear roadmap to achieve full Django parity while leveraging ThrillWiki's acceleration framework for rapid development.