# ThrillWiki Trending & New Content System Architecture

## System Overview

This document outlines the architecture for implementing real trending and new content functionality to replace the current mock data implementation on the ThrillWiki home page.

## Current State Analysis

### Frontend Structure (Vue 3 + TypeScript)
- **Home.vue** expects specific data formats:
  - **Trending Content**: `{id, name, location, category, rating, rank, views, views_change, slug}`
  - **New Content**: `{id, name, location, category, date_added, slug}`
- **Tabs Supported**:
  - Trending: Rides, Parks, Reviews
  - New: Recently Added, Newly Opened, Upcoming

### Backend Infrastructure
- **Django REST Framework** with comprehensive ViewSets
- **pghistory** already tracking model changes
- **Existing endpoints** for recent changes, openings, closures
- **Models**: Park and Ride with ratings, status, dates

## Proposed Architecture

### 1. Data Flow Architecture

```mermaid
flowchart TD
    A[User Views Page] --> B[View Tracking Middleware]
    B --> C[PageView Model]
    
    D[Trending Calculation Job] --> E[Trending Algorithm]
    E --> F[Cache Layer]
    
    G[Frontend Request] --> H[API Endpoints]
    H --> F
    F --> I[Serialized Response]
    I --> J[Frontend Display]
    
    K[Management Command] --> D
    L[Celery/Cron Schedule] --> K
```

### 2. Database Schema Design

#### PageView Model
```python
class PageView(models.Model):
    content_type = models.ForeignKey(ContentType)
    object_id = models.PositiveIntegerField()
    content_object = GenericForeignKey('content_type', 'object_id')
    
    user_session = models.CharField(max_length=40)
    ip_address = models.GenericIPAddressField()
    user_agent = models.TextField()
    timestamp = models.DateTimeField(auto_now_add=True)
    
    class Meta:
        indexes = [
            models.Index(fields=['content_type', 'object_id', 'timestamp']),
            models.Index(fields=['timestamp']),
        ]
```

### 3. Trending Algorithm

#### Calculation Components
- **View Count Weight**: Recent page views (configurable time window)
- **Rating Weight**: Average rating from Park/Ride models
- **Recency Boost**: Recently added/updated content bonus
- **Category Balancing**: Ensure diverse content across categories

#### Formula
```
Trending Score = (View Score × 0.4) + (Rating Score × 0.3) + (Recency Score × 0.2) + (Engagement Score × 0.1)
```

### 4. API Endpoints Design

#### Trending Endpoint
```
GET /api/v1/trending/?tab={rides|parks|reviews}&limit=6
```

#### New Content Endpoint
```
GET /api/v1/new-content/?tab={recently-added|newly-opened|upcoming}&limit=4
```

### 5. Caching Strategy

#### Cache Keys
- `trending_rides_6h`: Trending rides cache (6 hour TTL)
- `trending_parks_6h`: Trending parks cache (6 hour TTL)
- `new_content_24h`: New content cache (24 hour TTL)

#### Cache Invalidation
- Manual refresh via management command
- Automatic refresh on schedule
- Cache warming during low-traffic periods

### 6. Performance Considerations

#### View Tracking Optimization
- Async middleware for non-blocking view tracking
- Batch insert for high-volume periods
- IP-based rate limiting to prevent spam

#### Database Optimization
- Proper indexing on PageView model
- Aggregate tables for trending calculations
- Periodic cleanup of old PageView records

## Implementation Plan

The implementation follows the todo list with these key phases:

1. **Database Layer**: PageView model and migrations
2. **Algorithm Design**: Trending calculation logic
3. **API Layer**: New endpoints and serializers
4. **Tracking System**: Middleware for view capture
5. **Caching Layer**: Performance optimization
6. **Automation**: Management commands and scheduling
7. **Frontend Integration**: Replace mock data
8. **Testing & Monitoring**: Comprehensive coverage

## Security & Privacy

- Anonymous view tracking (no personal data)
- Session-based rate limiting
- User agent validation
- IP address anonymization options

## Monitoring & Analytics

- View tracking success rates
- Trending calculation performance
- Cache hit/miss ratios
- API response times
- Algorithm effectiveness metrics