thrillwiki_django_no_react/docs/system-architecture-diagram.md

# ThrillWiki Trending System - Technical Architecture

## System Components Overview

```mermaid
graph TB
    subgraph "Frontend Layer"
        A[Home.vue Component] --> B[API Service Layer]
        B --> C[Trending Content Display]
        B --> D[New Content Display]
    end
    
    subgraph "API Layer"
        E[/api/v1/trending/] --> F[TrendingViewSet]
        G[/api/v1/new-content/] --> H[NewContentViewSet]
        F --> I[TrendingSerializer]
        H --> J[NewContentSerializer]
    end
    
    subgraph "Business Logic"
        K[Trending Algorithm] --> L[Score Calculator]
        L --> M[Weight Processor]
        M --> N[Ranking Engine]
    end
    
    subgraph "Data Layer"
        O[PageView Model] --> P[View Tracker]
        Q[Park Model] --> R[Content Source]
        S[Ride Model] --> R
        T[pghistory Events] --> U[Change Tracker]
    end
    
    subgraph "Caching Layer"
        V[Redis Cache] --> W[Trending Cache]
        V --> X[New Content Cache]
        W --> Y[6hr TTL]
        X --> Z[24hr TTL]
    end
    
    subgraph "Background Tasks"
        AA[Management Command] --> BB[Calculate Trending]
        CC[Celery/Cron Scheduler] --> AA
        BB --> K
        BB --> V
    end
    
    subgraph "Middleware"
        DD[View Tracking Middleware] --> O
        EE[User Request] --> DD
    end
    
    A --> E
    A --> G
    F --> K
    H --> U
    K --> O
    K --> Q
    K --> S
    F --> V
    H --> V
    EE --> A
```

## Data Flow Architecture

```mermaid
sequenceDiagram
    participant U as User
    participant F as Frontend
    participant API as API Layer
    participant C as Cache
    participant BG as Background Job
    participant DB as Database
    participant M as Middleware
    
    Note over U,M: Page View Tracking
    U->>F: Visit Park/Ride Page
    F->>M: HTTP Request
    M->>DB: Store PageView Record
    
    Note over U,M: Trending Content Request
    U->>F: Load Home Page
    F->>API: GET /api/v1/trending/?tab=rides
    API->>C: Check Cache
    alt Cache Hit
        C->>API: Return Cached Data
    else Cache Miss
        API->>DB: Query Trending Data
        DB->>API: Raw Data
        API->>API: Apply Algorithm
        API->>C: Store in Cache
    end
    API->>F: Trending Response
    F->>U: Display Trending Content
    
    Note over U,M: Background Processing
    BG->>DB: Aggregate PageViews
    BG->>DB: Calculate Scores
    BG->>C: Update Cache
```

## Algorithm Flow

```mermaid
flowchart TD
    A[Start Trending Calculation] --> B[Fetch Recent PageViews]
    B --> C[Group by Content Type/ID]
    C --> D[Calculate View Score]
    D --> E[Fetch Content Ratings]
    E --> F[Calculate Rating Score]
    F --> G[Calculate Recency Score]
    G --> H[Apply Weighted Formula]
    H --> I{Score > Threshold?}
    I -->|Yes| J[Add to Trending List]
    I -->|No| K[Skip Item]
    J --> L[Sort by Final Score]
    K --> L
    L --> M[Cache Results]
    M --> N[End]
```

## Database Schema Relationships

```mermaid
erDiagram
    PageView ||--o{ ContentType : references
    PageView {
        id bigint PK
        content_type_id int FK
        object_id int
        user_session varchar
        ip_address inet
        user_agent text
        timestamp datetime
    }
    
    Park ||--o{ PageView : tracked_in
    Park {
        id int PK
        name varchar
        slug varchar
        average_rating decimal
        status varchar
        opening_date date
        closing_date date
    }
    
    Ride ||--o{ PageView : tracked_in
    Ride {
        id int PK
        name varchar
        slug varchar
        park_id int FK
        average_rating decimal
        category varchar
        status varchar
        opening_date date
    }
    
    TrendingCache {
        key varchar PK
        data json
        expires_at datetime
    }