# aryanchougule/youtube_video_recommender_system architecture

> Architecture diagram of the GitHub repository aryanchougule/youtube_video_recommender_system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aryanchougule/youtube_video_recommender_system
- Repository: https://github.com/aryanchougule/youtube_video_recommender_system

## Overview

ReelRank is a session-based video recommender: the API accepts watch history, search, or request controls; the engine retrieves candidates, ranks them for configurable objectives, applies page-level policy, and returns recommendations with explanations. The graph also preserves catalog and interaction-data generation, session intent, and counterfactual evaluation. Edges are limited to README statements, excerpted calls, and SOURCE INDEX references; some implementation details of unsampled modules are therefore not expanded.

Main entry points: [`src/recsys/engine.py`](https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/engine.py) (Recommendation engine), [`src/recsys/artifacts.py`](https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/artifacts.py) (Loaded model artifacts), [`src/recsys/api/app.py`](https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/api/app.py) (Recommendation API), [`src/recsys/recall/blend.py`](https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/recall/blend.py) (Recall fusion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Catalog and behavior data"]
  node_catalog["Catalog sources<br/>[catalog.py]"]
  node_synthetic["Synthetic catalog<br/>[synthetic.py]"]
  node_simulator["Watch simulator<br/>[simulator.py]"]
  node_schema["Interaction schema<br/>[schema.py]"]
end

subgraph group_recommend["Recommendation runtime"]
  node_engine["Recommendation engine<br/>[engine.py]"]
  node_text["Text representation<br/>[text.py]"]
  node_content["Content retrieval<br/>[content.py]"]
  node_collaborative["Collaborative retrieval<br/>[cf.py]"]
  node_recall["Recall fusion<br/>[blend.py]"]
  node_intent["Session intent<br/>[intent.py]"]
end

subgraph group_models["Ranking and policy"]
  node_features["Ranking features<br/>[features.py]"]
  node_multitask["Objective ranker<br/>[multitask.py]"]
  node_ranker["Ranker<br/>[ranker.py]"]
  node_policy["Page policy<br/>[rerank.py]"]
end

subgraph group_service["API and serving"]
  node_api["Recommendation API<br/>[app.py]"]
  node_ui["Demo interface<br/>[app.js]"]
  node_artifacts["Loaded model artifacts<br/>[artifacts.py]"]
  node_serving["Serving export<br/>[export.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_counterfactual["Counterfactual evaluation<br/>[counterfactual.py]"]
  node_metrics["Recommendation metrics<br/>[metrics.py]"]
end

node_viewer(("Viewer"))

node_viewer -->|"uses"| node_ui
node_ui -->|"sends requests"| node_api
node_api -->|"calls"| node_engine
node_api -->|"loads"| node_artifacts
node_engine -->|"uses"| node_artifacts
node_engine -->|"orchestrates retrieval"| node_recall
node_engine -->|"uses"| node_intent
node_engine -->|"applies"| node_policy
node_engine -->|"fuses candidates"| node_recall
node_recall -->|"includes source"| node_content
node_recall -->|"combines sources"| node_collaborative
node_content -->|"queries vectors"| node_text
node_artifacts -->|"loads"| node_content
node_artifacts -->|"loads"| node_collaborative
node_artifacts -->|"builds"| node_features
node_artifacts -->|"loads"| node_ranker
node_engine -->|"ranks by objectives"| node_multitask
node_engine -->|"scores candidates"| node_ranker
node_features -->|"provides features"| node_ranker
node_features -->|"provides features"| node_multitask
node_engine -->|"diversifies page"| node_policy
node_catalog -->|"loads when configured"| node_synthetic
node_simulator -->|"coerces interactions"| node_schema
node_api -.->|"uses exported bundle"| node_serving
node_counterfactual -->|"computes measures"| node_metrics

click node_catalog "https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/data/catalog.py"
click node_synthetic "https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/data/synthetic.py"
click node_simulator "https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/data/simulator.py"
click node_schema "https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/data/schema.py"
click node_api "https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/api/app.py"
click node_ui "https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/api/static/app.js"
click node_engine "https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/engine.py"
click node_artifacts "https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/artifacts.py"
click node_text "https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/features/text.py"
click node_content "https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/recall/content.py"
click node_collaborative "https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/recall/cf.py"
click node_recall "https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/recall/blend.py"
click node_intent "https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/intent.py"
click node_features "https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/rank/features.py"
click node_multitask "https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/rank/multitask.py"
click node_ranker "https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/rank/ranker.py"
click node_policy "https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/policy/rerank.py"
click node_counterfactual "https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/counterfactual.py"
click node_metrics "https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/metrics.py"
click node_serving "https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/serving/export.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_catalog,node_synthetic,node_simulator,node_schema,node_viewer toneBlue
class node_engine,node_text,node_content,node_collaborative,node_recall,node_intent toneAmber
class node_features,node_multitask,node_ranker,node_policy toneMint
class node_api,node_ui,node_artifacts,node_serving toneRose
class node_counterfactual,node_metrics toneIndigo
```

## Components

### Catalog and behavior data

- [Catalog sources](https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/data/catalog.py): `src/recsys/data/catalog.py`
- [Synthetic catalog](https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/data/synthetic.py): `src/recsys/data/synthetic.py`
- [Watch simulator](https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/data/simulator.py): `src/recsys/data/simulator.py`
- [Interaction schema](https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/data/schema.py): `src/recsys/data/schema.py`

### Recommendation runtime

- [Recommendation engine](https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/engine.py): `src/recsys/engine.py`
- [Text representation](https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/features/text.py): `src/recsys/features/text.py`
- [Content retrieval](https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/recall/content.py): `src/recsys/recall/content.py`
- [Collaborative retrieval](https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/recall/cf.py): `src/recsys/recall/cf.py`
- [Recall fusion](https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/recall/blend.py): `src/recsys/recall/blend.py`
- [Session intent](https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/intent.py): `src/recsys/intent.py`

### Ranking and policy

- [Ranking features](https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/rank/features.py): `src/recsys/rank/features.py`
- [Objective ranker](https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/rank/multitask.py): `src/recsys/rank/multitask.py`
- [Ranker](https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/rank/ranker.py): `src/recsys/rank/ranker.py`
- [Page policy](https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/policy/rerank.py): `src/recsys/policy/rerank.py`

### API and serving

- [Recommendation API](https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/api/app.py): `src/recsys/api/app.py`
- [Demo interface](https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/api/static/app.js): `src/recsys/api/static/app.js`
- [Loaded model artifacts](https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/artifacts.py): `src/recsys/artifacts.py`
- [Serving export](https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/serving/export.py): `src/recsys/serving/export.py`

### Evaluation

- [Counterfactual evaluation](https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/counterfactual.py): `src/recsys/counterfactual.py`
- [Recommendation metrics](https://github.com/aryanchougule/youtube_video_recommender_system/blob/main/src/recsys/metrics.py): `src/recsys/metrics.py`

### Other components

- **Viewer**

## Connections

- Viewer → Demo interface: uses
- Demo interface → Recommendation API: sends requests (evidence: `src/recsys/api/static/app.js`)
- Recommendation API → Recommendation engine: calls (evidence: `src/recsys/api/app.py`)
- Recommendation API → Loaded model artifacts: loads (evidence: `src/recsys/api/app.py`)
- Recommendation engine → Loaded model artifacts: uses (evidence: `src/recsys/engine.py`)
- Recommendation engine → Recall fusion: orchestrates retrieval (evidence: `src/recsys/engine.py`)
- Recommendation engine → Session intent: uses (evidence: `src/recsys/engine.py`)
- Recommendation engine → Page policy: applies (evidence: `src/recsys/engine.py`)
- Recommendation engine → Recall fusion: fuses candidates (evidence: `src/recsys/engine.py`)
- Recall fusion → Content retrieval: includes source (evidence: `src/recsys/recall/blend.py`)
- Recall fusion → Collaborative retrieval: combines sources
- Content retrieval → Text representation: queries vectors (evidence: `src/recsys/recall/content.py`)
- Loaded model artifacts → Content retrieval: loads (evidence: `src/recsys/artifacts.py`)
- Loaded model artifacts → Collaborative retrieval: loads (evidence: `src/recsys/artifacts.py`)
- Loaded model artifacts → Ranking features: builds (evidence: `src/recsys/artifacts.py`)
- Loaded model artifacts → Ranker: loads (evidence: `src/recsys/artifacts.py`)
- Recommendation engine → Objective ranker: ranks by objectives
- Recommendation engine → Ranker: scores candidates
- Ranking features → Ranker: provides features (evidence: `src/recsys/rank/ranker.py`)
- Ranking features → Objective ranker: provides features (evidence: `src/recsys/rank/multitask.py`)
- Recommendation engine → Page policy: diversifies page (evidence: `src/recsys/engine.py`)
- Catalog sources → Synthetic catalog: loads when configured (evidence: `src/recsys/data/catalog.py`)
- Watch simulator → Interaction schema: coerces interactions (evidence: `src/recsys/data/simulator.py`)
- Recommendation API → Serving export: uses exported bundle
- Counterfactual evaluation → Recommendation metrics: computes measures (evidence: `src/recsys/counterfactual.py`)
