10 KiB
10 KiB
Surprise Me - Architecture Diagrams
System Architecture Overview
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
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
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
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
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
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
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
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
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
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: