System design

How the pieces connect

MovieTwirl separates live recommendation serving from offline archetype research. The same movie catalog and affinity matrix feed both paths.

Client

React 19 + Vite + TanStack Query
Discover, search, streaming badges
Trakt OAuth watch-history sync

→

FastAPI API

SQLite movie DB (~18k titles)
TMDB / Watchmode / Trakt clients
Recommendation service orchestration

Phase 1 — Hybrid recommender

Collaborative filtering (user ratings)
Content-based TF-IDF + SVD embeddings
Neural reranker when enough signal exists

Phase 2 — Archetype ranker

Listwise softmax over surfaced candidates
Features: archetype weights, mode, hero stage
Trained on synthetic v1.parquet

Backend modules

Layer	Role
`app/ml/pipeline.py`	Hybrid inference orchestration
`app/ml/archetype_ranker.py`	Session-wise ranking model
`app/ml/archetype_features.py`	User + movie + mode encoding
`app/ml/archetype_eval.py`	Fixed-split cohort metrics
`app/services/trakt_auth_service.py`	OAuth + history import

Data stores

Artifact	Contents
`movierec.db`	Movies, streaming, ratings
`embeddings.npy`	Content vectors for similarity
`affinities.parquet`	Movie ↔ archetype scores
`v1.parquet`	Phase 2 training export
`archetype_ranker.joblib`	Serialized ranker v2

Request flow — archetype recommendations

GET /api/v1/recommendations/archetype?mode=solo&limit=10

1. Load user archetype weights (King/Warrior/Magician/Lover)
2. Fetch candidate movies from catalog or session context
3. Score each (user, movie, mode) with ArchetypeRanker
4. Return ranked list with affinity + model scores

Phase 1 hybrid paths remain the default for cold-start users; Phase 2 activates when archetype profiles exist or for research/demo endpoints.

Ops (historical)

Automation that powered the study

Daily refresh

TMDB trending, Watchmode streaming, optional sklearn retrain.

Weekly cohort snapshot

Append hit@1 metrics to JSONL on fixed holdout.

Dataset sync

Export parquets + CSVs to Kaggle and HuggingFace (private).

Study crons were removed after closure; this demo site documents the architecture statically.