nextav/docs/SURPRISE_ME_ARCHITECTURE_DIAGRAM.md

# Surprise Me - Architecture Diagrams

## System Architecture Overview

```mermaid
graph TB
    User[User] --> Sidebar[Sidebar Navigation]
    Sidebar --> SurpriseMePage[Surprise Me Page]
    
    SurpriseMePage --> AlgorithmSelector[Algorithm Selector]
    SurpriseMePage --> RecommendationGrid[Recommendation Grid]
    SurpriseMePage --> RefreshButton[Refresh Button]
    
    AlgorithmSelector --> API[/api/videos/recommendations]
    RefreshButton --> API
    
    API --> RecService[Recommendation Service]
    
    RecService --> SmartMix[Smart Mix Algorithm]
    RecService --> WeightedRandom[Weighted Random]
    RecService --> ForgottenGems[Forgotten Gems]
    RecService --> SimilarFavorites[Similar to Favorites]
    RecService --> TimeBased[Time-Based]
    RecService --> PureRandom[Pure Random]
    RecService --> UnwatchedFirst[Unwatched First]
    
    SmartMix --> Database[(SQLite Database)]
    WeightedRandom --> Database
    ForgottenGems --> Database
    SimilarFavorites --> Database
    TimeBased --> Database
    PureRandom --> Database
    UnwatchedFirst --> Database
    
    Database --> MediaTable[media table]
    Database --> AccessTable[media_access table]
    Database --> BookmarksTable[bookmarks table]
    Database --> StarsTable[stars table]
    
    RecommendationGrid --> VideoCard[Video Cards]
    VideoCard --> VideoPlayer[Unified Video Player]
    VideoCard --> AccessTracking[Track Access API]
    
    AccessTracking --> Database
```

## Data Flow Diagram

```mermaid
sequenceDiagram
    participant User
    participant SurpriseMePage
    participant API
    participant RecService
    participant Database
    participant VideoPlayer
    
    User->>SurpriseMePage: Click "Surprise Me" in sidebar
    SurpriseMePage->>API: GET /api/videos/recommendations?algorithm=smart_mix
    API->>RecService: getRecommendations('smart_mix', 20)
    
    RecService->>Database: Query media table
    RecService->>Database: Query media_access table
    RecService->>Database: Query bookmarks & stars
    
    Database-->>RecService: Return matching videos
    RecService->>RecService: Apply algorithm logic
    RecService->>RecService: Score and rank videos
    RecService-->>API: Return top 20 videos
    API-->>SurpriseMePage: JSON response with videos
    
    SurpriseMePage->>User: Display 20 recommended videos
    
    User->>VideoCard: Click video to watch
    VideoCard->>VideoPlayer: Open player with video
    VideoCard->>API: POST /api/media-access/:id {type: "view"}
    API->>Database: INSERT into media_access
    Database-->>API: Success
    
    User->>VideoPlayer: Play video
    VideoPlayer->>API: POST /api/media-access/:id {type: "play"}
    API->>Database: INSERT into media_access
```

## Database Schema Diagram

```mermaid
erDiagram
    MEDIA ||--o{ MEDIA_ACCESS : tracks
    MEDIA ||--o{ BOOKMARKS : has
    MEDIA ||--o{ STARS : has
    MEDIA }o--|| LIBRARIES : belongs_to
    
    MEDIA {
        int id PK
        int library_id FK
        string path
        string type
        string title
        int size
        string thumbnail
        int bookmark_count
        int star_count
        float avg_rating
        datetime created_at
    }
    
    MEDIA_ACCESS {
        int id PK
        int media_id FK
        string access_type
        datetime created_at
    }
    
    BOOKMARKS {
        int id PK
        int media_id FK
        datetime created_at
    }
    
    STARS {
        int id PK
        int media_id FK
        int rating
        datetime created_at
    }
    
    LIBRARIES {
        int id PK
        string path
    }
```

## Algorithm Decision Flow

```mermaid
graph TD
    Start[User Opens Surprise Me] --> CheckAlgorithm{Algorithm Selected?}
    
    CheckAlgorithm -->|Default| SmartMix[Smart Mix Algorithm]
    CheckAlgorithm -->|User Selected| SelectedAlg[Selected Algorithm]
    
    SmartMix --> DistributeLoad[Distribute Load]
    DistributeLoad --> WR[30% Weighted Random]
    DistributeLoad --> FG[25% Forgotten Gems]
    DistributeLoad --> SF[20% Similar Favorites]
    DistributeLoad --> UF[15% Unwatched First]
    DistributeLoad --> TB[10% Time-Based]
    
    WR --> Combine[Combine & Shuffle]
    FG --> Combine
    SF --> Combine
    UF --> Combine
    TB --> Combine
    
    SelectedAlg --> SingleAlg[Run Single Algorithm]
    SingleAlg --> Combine
    
    Combine --> Dedupe[Remove Duplicates]
    Dedupe --> LimitResults[Limit to 20 videos]
    LimitResults --> Display[Display to User]
```

## Weighted Random Scoring Flow

```mermaid
graph LR
    Video[Video] --> BaseScore[Base Score: Random 0.5-1.0]
    
    BaseScore --> CheckAccess{Ever Accessed?}
    CheckAccess -->|Yes| CalcRecency[Calculate Days Since View]
    CheckAccess -->|No| MaxRecency[Recency Multiplier = 1.0]
    
    CalcRecency --> RecencyMult[Recency Multiplier:<br/>min 1.0, days/90]
    
    RecencyMult --> ApplyRecency[Score × Recency]
    MaxRecency --> ApplyRecency
    
    ApplyRecency --> CheckRating{Has Rating?}
    CheckRating -->|Yes| RatingMult[Rating Multiplier:<br/>1.0 + rating/10]
    CheckRating -->|No| NoRating[Rating Multiplier = 1.0]
    
    RatingMult --> ApplyRating[Score × Rating]
    NoRating --> ApplyRating
    
    ApplyRating --> CheckDiversity{From Underrepresented<br/>Library?}
    CheckDiversity -->|Yes| DiversityBonus[Diversity Bonus:<br/>Score × 1.2]
    CheckDiversity -->|No| NoDiversity[No Bonus]
    
    DiversityBonus --> FinalScore[Final Score]
    NoDiversity --> FinalScore
    
    FinalScore --> Rank[Rank Against Others]
```

## UI Component Hierarchy

```mermaid
graph TD
    App[App Layout] --> Sidebar[Sidebar]
    App --> MainArea[Main Content Area]
    
    Sidebar --> SurpriseMenuItem[🎲 Surprise Me Item]
    
    SurpriseMenuItem --> SurpriseMePage[Surprise Me Page]
    MainArea --> SurpriseMePage
    
    SurpriseMePage --> Header[Page Header]
    SurpriseMePage --> Controls[Control Panel]
    SurpriseMePage --> Grid[Recommendation Grid]
    
    Header --> Title[Title & Description]
    Header --> Stats[Statistics]
    
    Controls --> AlgoDropdown[Algorithm Dropdown]
    Controls --> RefreshBtn[Refresh Button]
    Controls --> LimitSelector[Limit Selector]
    
    Grid --> VirtualGrid[Virtualized Grid]
    VirtualGrid --> VideoCard1[Video Card 1]
    VirtualGrid --> VideoCard2[Video Card 2]
    VirtualGrid --> VideoCardN[Video Card N]
    
    VideoCard1 --> Thumbnail[Thumbnail]
    VideoCard1 --> Info[Video Info]
    VideoCard1 --> Badge[Recommendation Badge]
    VideoCard1 --> Actions[Actions]
    
    Actions --> PlayBtn[Play Button]
    Actions --> BookmarkBtn[Bookmark]
    Actions --> RatingStars[Star Rating]
```

## State Management Flow

```mermaid
stateDiagram-v2
    [*] --> Initial
    Initial --> Loading: User clicks Surprise Me
    Loading --> Loaded: Recommendations received
    Loading --> Error: API Error
    
    Error --> Loading: User retries
    
    Loaded --> Refreshing: User clicks Refresh
    Loaded --> ChangingAlgorithm: User changes algorithm
    
    Refreshing --> Loaded: New recommendations received
    Refreshing --> Error: API Error
    
    ChangingAlgorithm --> Loading: Fetching with new algorithm
    
    Loaded --> PlayingVideo: User clicks video
    PlayingVideo --> Loaded: User closes player
    PlayingVideo --> TrackingAccess: Video opened
    
    TrackingAccess --> Loaded: Access tracked
```

## Recommendation Algorithm Comparison

```mermaid
graph LR
    subgraph "Algorithm Characteristics"
        WR[Weighted Random<br/>Balanced & Fair]
        FG[Forgotten Gems<br/>Personal History]
        SF[Similar Favorites<br/>Folder-Based]
        TB[Time-Based<br/>Temporal Patterns]
        PR[Pure Random<br/>Complete Surprise]
        UF[Unwatched First<br/>New Content]
        SM[Smart Mix<br/>Best of All]
    end
    
    subgraph "User Goals"
        Variety[Want Variety]
        Rediscover[Rediscover Old]
        Similar[Similar to Favorites]
        New[Explore New]
        Surprise[Complete Surprise]
    end
    
    Variety --> WR
    Variety --> SM
    Rediscover --> FG
    Similar --> SF
    New --> UF
    New --> TB
    Surprise --> PR
```

## Access Tracking Integration

```mermaid
graph TB
    subgraph "User Actions"
        OpenPlayer[Open Video Player]
        StartPlayback[Start Playback]
        BookmarkVideo[Bookmark Video]
        RateVideo[Rate Video]
    end
    
    subgraph "Tracking System"
        TrackView[Track: view]
        TrackPlay[Track: play]
        TrackBookmark[Track: bookmark]
        TrackRate[Track: rate]
    end
    
    subgraph "Database"
        MediaAccessTable[media_access table]
    end
    
    subgraph "Recommendation Engine"
        UseInAlgorithms[Use in Future Recommendations]
    end
    
    OpenPlayer --> TrackView
    StartPlayback --> TrackPlay
    BookmarkVideo --> TrackBookmark
    RateVideo --> TrackRate
    
    TrackView --> MediaAccessTable
    TrackPlay --> MediaAccessTable
    TrackBookmark --> MediaAccessTable
    TrackRate --> MediaAccessTable
    
    MediaAccessTable --> UseInAlgorithms
    
    UseInAlgorithms --> RecencyPenalty[Apply Recency Penalty]
    UseInAlgorithms --> IdentifyFavorites[Identify Favorite Patterns]
    UseInAlgorithms --> FindUnwatched[Find Unwatched Videos]
```

## Performance Optimization Strategy

```mermaid
graph TB
    Request[Recommendation Request] --> CheckCache{Cache Hit?}
    
    CheckCache -->|Yes| ReturnCached[Return Cached Results]
    CheckCache -->|No| QueryDB[Query Database]
    
    QueryDB --> UseIndexes[Use Optimized Indexes]
    UseIndexes --> idx1[idx_media_access_created_at]
    UseIndexes --> idx2[idx_media_type_created_at]
    UseIndexes --> idx3[idx_media_bookmark_count]
    
    idx1 --> ExecuteQuery[Execute Query]
    idx2 --> ExecuteQuery
    idx3 --> ExecuteQuery
    
    ExecuteQuery --> LimitResults[LIMIT 20]
    LimitResults --> ScoreRank[Score & Rank]
    ScoreRank --> CacheResults[Cache for 5 minutes]
    
    CacheResults --> ReturnResults[Return Results]
    ReturnCached --> ReturnResults
```

---

## Legend

### Diagram Types
- **Architecture Overview**: High-level system components
- **Data Flow**: Request/response sequences
- **Database Schema**: Entity relationships
- **Algorithm Flow**: Decision trees and logic
- **Component Hierarchy**: UI structure
- **State Management**: Application states
- **Performance**: Optimization strategies

### Color Coding
- **Blue**: User-facing components
- **Green**: Backend services
- **Yellow**: Database operations
- **Purple**: Algorithm logic
- **Orange**: Tracking/analytics

---

**Related Documentation**:
- [Complete Design Document](SURPRISE_ME_RECOMMENDATION_DESIGN.md)
- [Quick Summary](SURPRISE_ME_SUMMARY.md)
- [Main Docs Index](README.md)