PRD: Hot Video Priority & Trending Feed

I Overview

A trending signal that surfaces popular videos and pre-warms them for faster playback.

🎯 What & Why

🎯

Give viewers a curated "Trending Now" experience instead of a flat, unordered video list — improving discovery, engagement, and viral spread.

This PRD introduces a hot-score ranking, a dedicated trending endpoint, a sort option on the existing feed, a scheduled recompute job, cache pre-warming for hot videos, and frontend surfacing (trending section + 🔥 badge).

📋 Metadata

Field	Value
Status	Approved
Author	nguyenhuuca
Date	2026-02-28
Version	1.0
Beads Issue	N/A
PR-FAQ	N/A
Stakeholders	Backend Team, Frontend Team, Product

🔎 Next Steps & Related Artifacts

After PRD approval

[x] Architect Review: Technical feasibility — Output: ADR-0011
[ ] UI/UX Designer: Wireframes for Trending Now section + Hot badge (/ui-ux-designer) — Output: artifacts/design_spec_hot-video.md
[x] Engineering Estimate: Effort estimation & decomposition — Output: plan-hot-video-priority
[ ] Create Beads Issues: bd create "Hot Video Priority" -t feature

Related Artifacts

ADR: ADR-0011 — Hot Video Priority Scoring
Implementation Plan: plan-hot-video-priority
Cache Strategy: ADR-0003
LRU Cache: ADR-0005

Approval

Role	Name	Date	Status
Product	nguyenhuuca	2026-02-28	Approved
Engineering	nguyenhuuca	2026-02-28	Approved
Design	N/A	N/A	N/A

Version History

Version	Date	Author	Changes
1.0	2026-02-28	nguyenhuuca	Initial draft
1.1	2026-05-31	nguyenhuuca	Restructured to official PRD template; removed non-existent `upCount` field; fixed entity name `YouTubeVideo` → `VideoSource`; fixed doc paths

II Problem Statement

No trending signal exists — discovery is 100% manual browsing.

❓ The Problem

All videos are displayed in a flat, unordered list. Users have no signal about which videos are trending or popular — leading to poor content discovery and lower engagement. Users who want to watch something good must manually browse without any curation.

📊 Quantitative Evidence

No trending signal exists — 100% of content discovery is manual browsing
VideoAccessStats table exists and tracks hitCount + lastAccessedAt, but recordAccess() is commented out — zero access data is being written
ShareLink table tracks share events but is not used for ranking
VideoCacheImpl already promotes videos with ≥5 cache hits — evidence that popularity signals are valuable

💬 Qualitative Evidence

Users who want to watch "something good" have no starting point other than scrolling
Hot content buried in a flat list reduces the chance of viral spread
Pre-caching popular videos is already partially designed in VideoCacheImpl — the infrastructure anticipates this need

III Goals & Success Metrics

Discovery, consumption, latency, and trending engagement.

📈 Goals & Targets

Goal	Metric	Target
Improve content discovery	Average session duration	+15%
Increase video consumption	Videos watched per session	+20%
Reduce hot video latency	Time-to-first-frame for hot videos	< 500ms (from ~2s via pre-cache)
Drive trending engagement	User click-through on hot badges	> 30%

IV User Stories

Viewer-facing experience and API consumer integration.

Viewer Trending Now section

As a viewer, I want to see a "Trending Now" section at the top of the home page so that I can quickly find popular content without browsing.

Acceptance: A "🔥 Trending Now" section shows top 5 hot videos above the main feed.

Viewer Visual hot marker

As a viewer, I want hot videos to be visually marked so that I know at a glance which content is currently popular.

Acceptance: Video cards with isHot = true display a 🔥 badge.

Viewer Faster hot playback

As a viewer, I want hot videos to start playing faster so that I don't wait when choosing trending content.

Acceptance: Top 10 hot videos are pre-warmed in cache; first-frame latency < 500ms.

API consumer Dedicated trending endpoint

As an API consumer, I want a dedicated /api/videos/trending endpoint so that I can build trending feeds in any client.

Acceptance: GET /api/videos/trending?limit=N returns top N videos sorted by hotScore DESC.

API consumer Sort main list by hotness

As an API consumer, I want to sort the main video list by hotness so that I can offer multiple sort options without a separate endpoint.

Acceptance: GET /api/videos?sort=hot returns all videos sorted by hotScore DESC; existing calls without sort are unchanged.

V Requirements

Functional (FR) and non-functional (NFR) requirements.

✅ Functional Requirements

ID	Requirement	Priority	Notes
FR-1	Activate `recordAccess()` — async upsert of `VideoAccessStats` on every stream	Must Have	Must not block stream response
FR-2	Implement hot score formula: weighted hits (60%) + shares (25%) + recency decay (15%)	Must Have	Min-max normalised across active videos
FR-3	`GET /api/videos/trending?limit=N` endpoint (default 10, max 50)	Must Have	Served from `StatsCacheImpl`, TTL 30 min
FR-4	Extend `GET /api/videos?sort=hot` — backward compatible	Must Have	No change to calls without `sort` param
FR-5	Scheduled job: recompute hot scores every 30 minutes	Must Have	Runs in `AppScheduler`
FR-6	Pre-warm `VideoCacheImpl` for top 10 hot videos after each recomputation	Should Have	Goal: first-frame < 500ms
FR-7	Frontend: "🔥 Trending Now" section at top of home page (top 5 videos)	Must Have
FR-8	Frontend: "🔥 Hot" badge on video cards where `isHot = true`	Must Have	Show when hotScore ≥ top 20% threshold

⚙️ Non-Functional Requirements

ID	Requirement	Target
NFR-1	`recordAccess()` latency overhead	< 5ms (async, fire-and-forget)
NFR-2	Trending API response time	< 100ms (served from cache)
NFR-3	Score recomputation time	< 10s for 10,000 videos
NFR-4	Additional memory overhead	< 50MB
NFR-5	Backward compatibility	`GET /api/videos` without `sort` param — unchanged behaviour
NFR-6	Resilience	DB write failure in `recordAccess()` must not fail the stream request

VI Scope

What ships in v1 versus what is deferred.

✅ In Scope

Activate VideoAccessServiceImpl.recordAccess() (upsert VideoAccessStats)
Hot score algorithm with configurable weights (app.hot-video.* in application.yaml)
New GET /api/videos/trending endpoint
sort=hot parameter on existing GET /api/videos
Liquibase migration: hot_score, is_hot, hot_rank columns on video_sources
Scheduled recomputation job every 30 minutes
Cache pre-warming for top 10 hot videos
Frontend: Trending Now section + 🔥 badge on video cards

🚫 Out of Scope

Personalised recommendations (per-user hot scores) — v2
Real-time score updates via WebSocket — v2
A/B testing framework for ranking algorithms — v2
Machine learning-based scoring — v3
Like/dislike counts (not present on VideoSource entity)

VII Dependencies

Most infrastructure already exists; the Liquibase migration is the one gap.

🔗 Dependencies

Dependency	Owner	Status	Risk
`VideoAccessStats` entity + repo	Backend	✅ Exists	Low — just needs `recordAccess()` uncommented
`ShareLink` table	Backend	✅ Exists	Low — read-only query for share count
`StatsCacheImpl`	Backend	✅ Exists	Low — already used for stats
`VideoCacheImpl`	Backend	✅ Exists	Low — `preWarm()` needs to be called
`AppScheduler`	Backend	✅ Exists	Low — add new `@Scheduled` method
Liquibase migration	Backend	❌ Missing	Medium — must land before entity changes
`VideoSource` entity	Backend	✅ Active table	Low — add 3 columns

VIII Risks & Mitigations

Load, score bias, table growth, and staleness — each with a mitigation.

⚠️ Risks & Mitigations

Risk	Likelihood	Impact	Mitigation
`recordAccess()` creates DB bottleneck under high load	Medium	High	Keep `@Async` + catch all exceptions; add write queue in v2 if needed
Hot score biased toward old high-hit videos	Medium	Medium	Apply 24h rolling window + exponential recency decay (`e^(-0.1 × hoursAgo)`)
`video_access_stats` table grows unbounded	Medium	Medium	Activate `cleanUpOldVideos()` in `AppScheduler` to purge rows older than window
Scores stale up to 30 minutes after new viral video	Low	Low	TTL is configurable; acceptable for v1
Cache invalidation on new video added	Low	Low	TTL-based invalidation (30 min) sufficient for v1

IX Data & API

Appendix — data model, hot score formula, API contract, and new components.

🗄️ Data Model

-- Liquibase migration: 202602280001-add-hot-score.sql
ALTER TABLE video_sources ADD COLUMN hot_score  DECIMAL(5,4) DEFAULT 0;
ALTER TABLE video_sources ADD COLUMN is_hot     BOOLEAN      DEFAULT FALSE;
ALTER TABLE video_sources ADD COLUMN hot_rank   INT          DEFAULT NULL;

CREATE INDEX idx_video_sources_hot_score
    ON video_sources(hot_score DESC) WHERE is_hot = TRUE;

CREATE INDEX IF NOT EXISTS idx_video_access_stats_video_id
    ON video_access_stats(video_id);

🧮 Hot Score Formula

$$hotScore = (0.60 \times normalizedHits) + (0.25 \times normalizedShares) + (0.15 \times recencyBoost)$$ $$recencyBoost = e^{-0.1 \times hoursAgo}$$

All inputs min-max normalised to [0, 1] across active videos.

🔌 API Contract

`GET /api/videos/trending`

Query params: limit (int, default=10, max=50)
Response: ResultListInfo<VideoDto>
  data[].videoId     String
  data[].title       String
  data[].embedLink   String
  data[].hotScore    Double
  data[].isHot       Boolean
  data[].rank        Integer  (1 = hottest)

`GET /api/videos?sort=hot`

Same VideoDto structure, ordered by hotScore DESC

🧩 New Components

service/
├── HotVideoService.java
└── impl/HotVideoServiceImpl.java

jobs/
└── AppScheduler.java  ← add recomputeHotScores()

🔎 Research — existing code references

VideoAccessStats entity: api/src/main/java/com/canhlabs/funnyapp/entity/VideoAccessStats.java
VideoSource entity: api/src/main/java/com/canhlabs/funnyapp/entity/VideoSource.java
VideoCacheImpl: api/src/main/java/com/canhlabs/funnyapp/cache/

X Open Questions

Decisions to resolve before the related requirements are implemented.

🧩 Open Questions

[ ] Should /api/videos/trending be a public endpoint (no auth required)? — Owner: Backend — Due: Before FR-3 implementation

[ ] What threshold defines isHot — top 20% by score or a fixed score cutoff? — Owner: Product — Due: Before FR-2 implementation

[ ] Should shares from private share-links count toward the hot score? — Owner: Backend — Due: Before FR-2 implementation

[ ] Do we need a hot_score_history table for analytics / score trending over time? — Owner: Data — Due: v2 planning