I Code It

Video Feed Page Architecture

Design a YouTube-like video feed page with smooth playback transitions and personalized ranking.

Quick take: Separate playback state from recommendation state. / Use cursor-based recommendation pagination with resilient media fallback.

Production notes: Preconnect to media/CDN origin before playback starts. / Fallback to lower bitrate ladders on unstable networks.

TL;DR

Keep playback state isolated, paginate recommendations via cursor, and prefetch adjacent content for smooth transitions.

Steel thread

Load a video, autoplay next recommendation candidate metadata, and append recommendation rail items on scroll.

C - Collect

  • Should autoplay be enabled by default?
  • What startup delay is acceptable before first frame?
  • Are captions and keyboard controls mandatory for all locales?

C - Component structure

  • WatchPage orchestrates selected video and recommendation feed.
  • VideoPlayerShell owns playback and quality controls.
  • RecommendationRail handles pagination and virtualization.

D - Data modeling

  • Video, Channel, RecommendationEdge, and PlaybackSession entities.
  • Recommendation order stored separately from canonical video map.
  • Track playback telemetry by session ID.

A - API design

  • GET /videos/:id for metadata and playback manifest pointer.
  • GET /videos/:id/recommendations?cursor=...
  • POST /playback/events batched telemetry endpoint.

O - Optimization

  • Prefetch next recommendation metadata and poster images.
  • Use adaptive quality ladder and startup bitrate hints.
  • Ensure keyboard controls and caption toggles are always reachable.
  • pagination-offset-cursor-infinite for recommendation pagination.
  • virtualization-strategies for long side-rail rendering.
  • a11y-testing-strategy-dynamic-uis for playback and update accessibility.

Failure modes

  • Recommendation reorder during scroll causes duplicate cards.
  • Adaptive bitrate oscillates and creates playback stalls.
  • Screen-reader users miss playback state changes.

Testing checklist

Testing + Accessibility Rubric

CategoryLevelRequirementDone When
functionalunitState transitions handle loading, success, empty, and error.Reducer/state machine tests cover all transitions.
functionalintegrationClient correctly maps API contracts into UI-ready view models.Contract fixtures pass with no runtime shape mismatch.
a11yintegrationFull keyboard flow works for primary interaction loop.Tab/Shift+Tab/Enter/Escape scenarios pass for critical controls.
a11ye2eDynamic updates expose meaningful live region announcements.Manual SR checks validate announcement timing and text quality.

Explain it clearly

  • Short version: isolate playback core, paginate rail with cursor, prefetch next payload.
  • Longer version: ABR strategy, telemetry contracts, and a11y control model.

Production hardening notes

  • Alert on startup-failure rate and rebuffer ratio by device class.
  • Roll out new ranking models with shadow traffic first.

Related Patterns