Streaming Stack — Technical Architecture

Streaming Stack has three core systems: (1) a content metadata database with cross-platform availability, (2) a recommendation engine matching mood/context to titles, and (3) a watchlist + expiration alert system. The Mac Mini handles nightly data refreshes and the recommendation AI pipeline.

┌──────────────────────────────────────────────────────┐ │ USER INTERFACE │ │ ┌──────────────┐ ┌─────────────┐ ┌──────────────┐ │ │ │ Web App │ │ Telegram │ │ Email │ │ │ │ (SvelteKit) │ │ Bot │ │ (Resend) │ │ │ │ Dashboard │ │ Chat UI │ │ Digests │ │ │ └──────┬───────┘ └──────┬──────┘ └──────┬──────┘ │ └─────────┼──────────────────┼──────────────────┼─────────┘ │ │ │ ▼ ▼ ▼ ┌──────────────────────────────────────────────────────┐ │ APPLICATION LAYER (Deno) │ │ ┌────────────┐ ┌────────────┐ ┌────────────────┐ │ │ │ Rec Engine │ │ Watchlist │ │ Expiration │ │ │ │ Service │ │ Service │ │ Alert Service │ │ │ └────────────┘ └────────────┘ └────────────────┘ │ │ ┌────────────┐ ┌────────────┐ ┌────────────────┐ │ │ │ Content │ │ User Prefs │ │ Analytics │ │ │ │ Sync │ │ Service │ │ Service │ │ │ └────────────┘ └────────────┘ └────────────────┘ │ └──────────────────────────────────────────────────────┘ │ │ ▼ ▼ ┌─────────────────────┐ ┌──────────────────────────┐ │ DATA SOURCES │ │ DATA STORES │ │ ┌───────────────┐ │ │ ┌────────────────────┐ │ │ │ JustWatch API │ │◄────│ │ Supabase (Postgres)│ │ │ │ (availability │ │ │ │ Titles, watchlists, │ │ │ │ + metadata) │ │ │ │ users, alerts │ │ │ └───────────────┘ │ │ └────────────────────┘ │ │ ┌───────────────┐ │ │ ┌────────────────────┐ │ │ │ TMDB API │ │ │ │ Upstash Redis │ │ │ │ (metadata) │ │ │ │ Session cache, │ │ │ └───────────────┘ │ │ │ recommendation │ │ │ ┌───────────────┐ │ │ │ pre-compute cache │ │ │ │ JustWatch │ │ │ └────────────────────┘ │ │ │ Expired API │ │ └──────────────────────────┘ │ │ └───────────────┘ │ └─────────────────────┘ │ ▼ ┌─────────────────────┐ │ AI RUNTIME │ │ ┌────────────────┐ │ │ │ Ollama (Mac Mini)│ │ │ │ Mistral 7B │ │ │ │ "Why you'll │ │ │ │ love this" │ │ │ └────────────────┘ │

Frontend

Component	Technology	Why
Web App	SvelteKit	Dashboard, recommendation interface, watchlist management. SSR for SEO of recommendation pages.
Mobile	Telegram Mini App	Rich chat-based UI inside Telegram — primary mobile interface for many users.
Telegram Bot	Deno Telegram Bot API	Text-based interaction for quick recommendations. "I'm in the mood for X, 90 minutes, solo."

Backend

Component	Technology	Why
Runtime	Deno 2	Runs recommendation pipeline and nightly sync on Mac Mini.
Database	Supabase (PostgreSQL)	Content metadata, user watchlists, alert preferences, viewing analytics.
Cache	Upstash Redis	Recommendation results cached per user (recompute daily). Session data.
Email	Resend	Weekly "leaving soon" digest, expiration alerts, monthly viewing report.
Scheduling	Upstash QStash	Nightly content sync (2am), weekly "leaving soon" digest (Sunday 10am), expiration checks every 6 hours.

Content Data

Source	What It Provides	Cost
JustWatch API	Cross-platform availability, pricing, launch dates	Usage-based (~$50/mo for 10K queries)
TMDb (The Movie Database)	Genre, cast, crew, ratings, keywords, synopses	Free (API key required)
Trakt.tv API	User watchlists, ratings, viewing history (if user connects)	Free
OTT Data (justwatch.com scraper)	Content expiration dates (scraped nightly)	Build in-house

AI Stack

🤖 AI Philosophy: Local for Explanations, Cloud for Scale

"Why you'll love this": Ollama Mistral 7B on Mac Mini generates personalized "why" explanations for each recommendation. Free, fast, good enough.
Recommendation matching: Hybrid approach: rule-based filtering (genre + mood + duration + platform) first, then Ollama re-ranks with "why" explanations. Avoids cold-start problem of pure ML.
Weekly email curation: Human-vetted精选 for top titles (reduces algorithmic churn feel). AI drafts descriptions; human reviews.

titles
id	uuid	Primary key
tmdb_id	integer	TheMovieDB reference ID
imdb_id	varchar(20)	IMDb reference ID
title	varchar(500)
type	enum('movie','series')
year	integer
runtime_minutes	integer
genres	varchar[]	e.g., {drama, thriller}
moods	varchar[]	e.g., {thoughtful, tense, fun}
moods	varchar[]	e.g., {thoughtful, tense, fun}
critics_score	integer	Rotten Tomatoes
audience_score	integer	IMDb / user rating
short_synopsis	varchar(500)	One-line description
long_synopsis	text	Full description
key_keywords	text[]	For search/matching

platform_availability
title_id	uuid (FK)	Ref titles
platform	enum('netflix','hbo_max','disney_plus','hulu','amazon_prime','apple_tv_plus','peacock','paramount_plus','crunchyroll','max','other')
availability_type	enum('subscription','rent','buy','free')
price_cents	integer (for rent/buy)
expires_at	timestamp (nullable)	NULL = no expiration known
last_checked_at	timestamp

users
id	uuid
email	varchar(255)
telegram_chat_id	varchar(50)	For alerts
subscribed_platforms	enum[]	Which services they have
profile_prefs_json	jsonb	{mood_preferences, avoid_genres, group_watch_style}
tier	enum('free','pro','household')
last_recommendation_at	timestamp

watchlists
id	uuid
user_id	uuid (FK)
title_id	uuid (FK)
added_at	timestamp
watched	boolean
watched_at	timestamp
platform_to_watch	enum	Preferred platform at time of adding
notes	text	Personal note

recommendation_log
id	uuid
user_id	uuid (FK)
mood	varchar(50)
time_available_min	integer
group_size	integer
results_json	jsonb	Top 5 recommendations with scores
clicked_title_id	uuid (FK, nullable)	Which one they clicked
created_at	timestamp

Recommendations

POST /api/recommend

Get recommendations. Body: {mood, time_min, group_size, subscribed_platforms[], exclude_titles[]?, watch_history[]?}. Returns top 5 ranked titles with "why" explanations. Rate limited: 10/min for free, unlimited for Pro.

GET /api/recommend/leaving-soon

Get top 20 titles on user's platforms expiring in next 7 days.

Watchlist

GET /api/watchlist

Get user's watchlist with platform availability and expiration warnings.

POST /api/watchlist

Add title to watchlist. Body: {title_id, platform_preference?}.

DELETE /api/watchlist/:titleId

Remove from watchlist.

PATCH /api/watchlist/:titleId/watched

Mark as watched.

Search

GET /api/search?q=&platform=&genre=&page=

Search titles with filters. Returns: title, year, platform(s), runtime, mood tags.

User Profile

GET /api/me/platforms

Get/set subscribed platforms (for filtering recommendations).

PATCH /api/me/preferences

Update mood preferences, avoid genres, notification settings.

GET /api/me/report

Get monthly viewing analytics report (Pro).

Webhooks (Internal)

POST /webhooks/justwatch

Receives JustWatch availability/expiration updates. Updates platform_availability table.

Step 1: Filter by Constraints

User's mood + time + group size + subscribed platforms → hard filter on titles table. Remove: titles not on their platforms, too long/short, wrong genre mood. Returns candidate set of ~20-50 titles.

Step 2: Rank by Relevance

Score remaining candidates by: watchlist affinity (similar to what user already added), viewing history patterns, critics score, recency, "leaving soon" bonus (if applicable). Ranks top 10.

Step 3: "Why You'll Love This" (Ollama)

For each of top 5 recommendations, Ollama Mistral 7B generates a personalized one-line "why" based on user's watch history and stated mood. Example: "Since you loved Breaking Bad's tension and Darryl's character arc, you'll appreciate this thriller's moral complexity." Cached in Redis for 24hrs.

Step 4: Binge Schedule (Pro)

For series recommendations, Ollama calculates: total runtime, episodes per day to finish in user's target timeframe, flags filler episodes to skip (from community data via Trakt).

Nightly: Content Sync (QStash)

2am nightly: sync with JustWatch API for availability changes. Update expiration dates. Flag newly expired content. This keeps watchlist availability signals fresh.

Weekly: "Leaving Soon" Digest (Resend)

Sunday 10am: for each user, find watchlist titles expiring in next 7 days. Send email/Telegram alert. Include "3 things we think you'd love that are leaving too."

Component	Where	Notes
Dashboard	Cloudflare Pages (free)	Auto-deploy, global CDN
Backend API	Deno Deploy or Mac Mini	Deno Deploy for production; Mac Mini for nightly jobs
Database	Supabase (free tier: 500MB)	Sufficient for <50K titles + 10K users.
Redis	Upstash (free tier: 10K commands/day)	Caching recommendations, sessions
Nightly Sync	Mac Mini + QStash cron	Runs on home server 24/7
AI (local)	Mac Mini Ollama	Mistral 7B — "why you'll love this" generation
Email	Resend (free: 3K/month)	Weekly digest, alerts
Content Data	JustWatch API + TMDb	~$50/mo for JustWatch

🍿 Streaming Stack — Architecture

🏗️ Architecture Overview

🛠️ Tech Stack