Sequence Diagrams: Hot Video Priority and Trending Feed¶
- PRD: PRD-hot-video-priority
- ADR: 0011-hot-video-priority
- Spec: — (see plan-hot-video-priority and plan-vid2-hot-score-migration)
- Status: Draft (the hot score is NOT implemented. Flows 1-3 are as-built, flow 4 is planned only)
Planned vs built.
- Built: manual
prioritycolumn (0-9999) onvideo_sources, set by an admin and used for feed ordering. TheVideoAccessStatsentity and repo, theVideoAccessService.recordAccess(String)signature, and acleanUpOldVideosjob whose delete step is commented out.- Not built:
recordAccess()body (commented out with a TODO), the Liquibase migration forhot_score,is_hot,hot_rank,HotVideoService/HotVideoServiceImpl,HotVideoProperties(app.hot-video.*), therecomputeHotScores()job,GET /videos/trending,sort=hot, cache pre-warming, and the frontend Hot badge. There is no server trending endpoint or section.ExploreView.jsxshows a "Trending Now" hero badge, but it is client side only: the hero is the first video of the list fromuseVideos, sorted by upvotes, views or newest (default upvotes). A grep forhotScore/hot_scoreinapi/srcreturns nothing.- PRD vs code. The PRD uses paths
/api/videos,/api/videos/trending. The real feed endpoint isGET /v1/funny-app/video-stream/list, and there is no/videoslist endpoint.recordAccessis called only insidegetFileRangeFromDisk, so even once implemented it would count cache misses, not every stream request as the PRD (FR-1) intends. The web client (useVideos) re-sorts the list byupvotesdescending, which can override the server order except for ties.
1. Stream a video chunk (access recording is a no-op today)¶
The browser requests byte ranges. A chunk-cache hit never touches disk. On a miss the service reads the file, records a cache miss in StatsCache, and calls recordAccess, which does nothing yet.
sequenceDiagram
autonumber
participant FE as Browser (VideoPlayer.jsx)
participant API as VideoStreamController
participant S as StreamVideoServiceImpl
participant C as VideoCache (Guava LRU)
participant ST as VideoStorageServiceImpl
participant SC as StatsCache
participant VA as VideoAccessServiceImpl
FE->>API: GET /v1/funny-app/video-stream/stream/{fileId} (Range header)
API->>S: getFileSize(fileId)
alt malformed or unsatisfiable Range
API-->>FE: 416 Range Not Satisfiable (Content-Range bytes */size)
end
API->>S: getPartialFileUsingRAF(fileId, start, end)
S->>C: getChunkStream(fileId, start, end, loader)
alt chunk cached
C-->>S: InputStream from memory
else cache miss
C->>ST: getFileRangeFromDisk(fileId, start, end)
ST->>SC: recordMiss(fileId)
ST-)VA: recordAccess(fileId) (@Async)
Note over VA: body is commented out (TODO)<br/>no DB write, no hit count
ST-->>C: bytes via RandomAccessFile
end
API-->>FE: 206 Partial Content (video/mp4, Content-Range)
2. Home feed ordering (manual priority, then newest)¶
The feed is ordered by the priority column, not by a hot score. There is no sort parameter.
sequenceDiagram
autonumber
actor U as Viewer
participant FE as Browser (useVideos.js, VideoFeed.jsx)
participant API as VideoStreamController
participant S as StreamVideoServiceImpl
participant P as HlsPlaybackServiceImpl
participant FC as FeedCache (Guava, 30 s)
participant R as VideoSourceRepository
participant DB as PostgreSQL
U->>FE: open Home
FE->>API: GET /v1/funny-app/video-stream/list
API->>S: getVideosToStream()
S->>P: hlsEnabled()
P-->>S: flag
S->>FC: get(flag, loader)
alt cache hit (within 30 s)
FC-->>S: cached unmodifiable list
else cache miss
FC->>R: findAllByIsHideAndStatusOrderByPriorityDescCreatedAtDesc(false, PUBLISHED)
R->>DB: SELECT ... ORDER BY priority DESC, created_at DESC
DB-->>R: rows
FC-->>S: List of VideoDto (no hotScore field)
end
API-->>FE: 200 ResultListInfo of VideoDto
FE->>FE: mapApiVideo then sort by upvotes desc (client side, queryKey videos + category, staleTime 5 min)
FE-->>U: swipe feed
3. Admin pins a video with a manual priority¶
This is the only "hot" lever that exists. An admin edits the priority cell in the video table.
sequenceDiagram
autonumber
actor A as Admin
participant FE as Browser (AdminVideoTable.jsx, useUpdateVideoPriority)
participant API as AdminController (hasRole ADMIN)
participant S as AdminVideoServiceImpl
participant R as VideoSourceRepository
participant FC as FeedCache
A->>FE: type priority and blur the input
FE->>API: PATCH /v1/funny-app/admin/videos/{id}/priority (JWT, body priority)
API->>S: updatePriority(id, priority)
alt priority outside 0..9999
S-->>API: Contract.require fails
API-->>FE: error ResultErrorInfo
else unknown id
S-->>API: IllegalArgumentException Video not found
API-->>FE: error ResultErrorInfo
else ok
S->>R: save(source with new priority)
S->>FC: invalidate()
API-->>FE: 200 ResultObjectInfo "Priority updated" (@AuditLog updateVideoPriority)
end
FE-->>A: SaveIndicator, admin videos query refreshed
4. PLANNED: scheduled hot score recompute and trending read¶
Not implemented. Drawn from PRD FR-2 to FR-8, ADR-0011 and plan-hot-video-priority. Names such as HotVideoServiceImpl and recomputeHotScores are the planned names and do not exist in the code.
sequenceDiagram
autonumber
participant J as AppScheduler.recomputeHotScores (PLANNED, every 30 min)
participant H as HotVideoServiceImpl (PLANNED)
participant AS as VideoAccessStatsRepo
participant DB as PostgreSQL (video_sources, share_link)
participant SC as StatsCache
participant VC as VideoCache
actor U as Viewer
participant FE as Browser (PLANNED Trending Now section)
participant API as Video controller (PLANNED GET trending)
J->>H: recompute()
H->>AS: hits per video in 24h window
H->>DB: share counts per video
H->>H: hotScore = 0.60 hits + 0.25 shares + 0.15 recency (min-max normalised)
H->>DB: UPDATE hot_score, is_hot, hot_rank (new columns, migration missing)
H->>SC: put top N trending list (TTL 30 min)
H->>VC: preWarm top 10 videos
U->>FE: open Home
FE->>API: GET trending?limit=5
API->>SC: read cached list
SC-->>API: List of VideoDto with hotScore, isHot, rank
API-->>FE: 200 ResultListInfo of VideoDto
FE-->>U: Trending Now row and Hot badge on cards