thrillwiki_django_no_react/docs/trending-system-architecture.md

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

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

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