Vitals - PulseVault Frontend — Infinite Scroll Video App

[horner]

Goal

Build a responsive React + Next.js (App Router) frontend for PulseVault that delivers infinite-scroll short videos.
Functions as a PWA (installable, offline shell) and optionally wraps into native mobile apps using Expo.

---

Frontend Stack

Component	Choice
Framework	Next.js (App Router) + TypeScript
Styling	TailwindCSS
Virtualization	react-virtuoso
Video	<video> + hls.js + IntersectionObserver
Animation	Framer Motion
State/query	React Query
Uploads	Uppy + tus-client
Auth	JWT/OIDC (Clerk/Auth.js compatible)
Offline	PWA manifest + Service Worker
Optional Native	Expo + react-native-web
Search	pgvector (default) / OpenSearch optional
Metrics	WebSocket (fastify-ws) + Prometheus instrumentation

---

UI Features

• Infinite-scroll feed with autoplay on visible videos
• Upload page with resumable tus uploads
• Authenticated “My uploads” listing (from manifest.jsonl)
• Player controls: pause on scroll-out, replay, fullscreen
• Realtime reactions/comments via WebSocket
• Offline support: cached app shell + thumbnails
• Adaptive streaming (HLS, DASH)
• Responsive layout for desktop, mobile, and tablets

---

Integration Points

• API: connects to Fastify backend /media and /uploads
• Streaming: signed URLs from /media/sign
• Realtime: wss://api.pulsestream.local/ws
• Observability: Prometheus metrics endpoint + Loki log pipeline

---

Deliverables

• Next.js app scaffold (Tailwind + TypeScript + App Router)
• Infinite-scroll feed component
• Video player w/ IntersectionObserver & hls.js
• Upload form (Uppy + tus)
• PWA manifest + offline caching
• Auth integration (JWT)
• Realtime metrics via WebSocket
• Expo wrapper (optional)
• Grafana panel for frontend metrics
• Docs: setup, API integration, local dev

---

Acceptance Criteria

• Feed scrolls infinitely and smoothly on mobile/desktop
• Videos autoplay in viewport, pause offscreen
• Uploads resume properly after connection drop
• PWA installable and functional offline
• Metrics visible in Grafana; errors logged via Loki
• Optional native wrapper builds successfully with Expo

---

🏗️ Future Tickets (not to implement now)

• PulseVault AI ranker (personalized feed w/ vector embeddings)
• PulseVault Studio (admin dashboard for analytics + moderation)
• PulseVault CDN BAA audit workflow