# boredjnurseman/ml-recommender-system-design architecture

> Architecture diagram of the GitHub repository boredjnurseman/ml-recommender-system-design, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/boredjnurseman/ml-recommender-system-design
- Repository: https://github.com/boredjnurseman/ml-recommender-system-design

## Overview

This repository demonstrates a narrow film-recommendation serving workflow: a request uses a deterministic stand-in for cached top-25 candidates, applies regional eligibility, assigns a stable policy cohort, optionally reranks, and returns five films. Policy files supply the versioned weights; disabling reranking preserves the filtered relevance-order fallback. The README also describes offline model production, telemetry, monitoring, and deployment as design context, not implemented subsystems. The graph follows the sampled serving calls and documented policy loading; no deployed API or external store is present.

Main entry points: [`src/recommender_demo/serving.py`](https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/src/recommender_demo/serving.py) (Serving orchestrator), [`src/recommender_demo/config.py`](https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/src/recommender_demo/config.py) (Policy loader), [`src/recommender_demo/candidates.py`](https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/src/recommender_demo/candidates.py) (Snapshot generator), [`src/recommender_demo/models.py`](https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/src/recommender_demo/models.py) (Top-25 snapshot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_candidate_data["Candidate data"]
  node_snapshot_builder["Snapshot generator<br/>[candidates.py]"]
  node_candidate_snapshot["Top-25 snapshot<br/>[models.py]"]
  node_candidate["Film candidate<br/>[models.py]"]
end

subgraph group_policy_control["Policy control"]
  node_rollout["Stable assignment<br/>[rollout.py]"]
  node_policy_loader["Policy loader<br/>[config.py]"]
  node_baseline_policy["Baseline policy<br/>[policy-v1.yaml]"]
  node_experiment_policy["Discovery policy<br/>[policy-v2.yaml]"]
end

subgraph group_online_serving["Online serving"]
  node_region_filter["Regional filter<br/>[constraints.py]"]
  node_serve["Serving orchestrator<br/>[serving.py]"]
  node_reranker["Policy reranker<br/>[reranker.py]"]
  node_five_results["Five recommendations<br/>[serving.py]"]
end

node_requester(("Recommendation caller"))

node_requester -->|"requests"| node_serve
node_snapshot_builder -->|"creates"| node_candidate_snapshot
node_snapshot_builder -->|"generates"| node_candidate
node_candidate_snapshot -->|"supplies candidates"| node_serve
node_serve -->|"filters by region"| node_region_filter
node_region_filter -->|"keeps eligible"| node_candidate
node_serve -->|"assigns cohort"| node_rollout
node_serve -->|"loads policy"| node_policy_loader
node_baseline_policy -->|"read by"| node_policy_loader
node_experiment_policy -->|"read by"| node_policy_loader
node_serve -->|"scores eligible"| node_reranker
node_serve -->|"returns top five"| node_five_results
node_reranker -->|"ranks candidates"| node_five_results
node_five_results -->|"returns"| node_requester

click node_snapshot_builder "https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/src/recommender_demo/candidates.py"
click node_candidate_snapshot "https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/src/recommender_demo/models.py"
click node_candidate "https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/src/recommender_demo/models.py"
click node_region_filter "https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/src/recommender_demo/constraints.py"
click node_serve "https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/src/recommender_demo/serving.py"
click node_rollout "https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/src/recommender_demo/rollout.py"
click node_policy_loader "https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/src/recommender_demo/config.py"
click node_baseline_policy "https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/config/policy-v1.yaml"
click node_experiment_policy "https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/config/policy-v2.yaml"
click node_reranker "https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/src/recommender_demo/reranker.py"
click node_five_results "https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/src/recommender_demo/serving.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_snapshot_builder,node_candidate_snapshot,node_candidate toneBlue
class node_rollout,node_policy_loader,node_baseline_policy,node_experiment_policy toneAmber
class node_region_filter,node_serve,node_reranker,node_five_results toneMint
class node_requester toneIndigo
```

## Components

### Candidate data

- [Snapshot generator](https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/src/recommender_demo/candidates.py): `src/recommender_demo/candidates.py`
- [Top-25 snapshot](https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/src/recommender_demo/models.py): `src/recommender_demo/models.py`
- [Film candidate](https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/src/recommender_demo/models.py): `src/recommender_demo/models.py`

### Policy control

- [Stable assignment](https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/src/recommender_demo/rollout.py): `src/recommender_demo/rollout.py`
- [Policy loader](https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/src/recommender_demo/config.py): `src/recommender_demo/config.py`
- [Baseline policy](https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/config/policy-v1.yaml): `config/policy-v1.yaml`
- [Discovery policy](https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/config/policy-v2.yaml): `config/policy-v2.yaml`

### Online serving

- [Regional filter](https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/src/recommender_demo/constraints.py): `src/recommender_demo/constraints.py`
- [Serving orchestrator](https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/src/recommender_demo/serving.py): `src/recommender_demo/serving.py`
- [Policy reranker](https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/src/recommender_demo/reranker.py): `src/recommender_demo/reranker.py`
- [Five recommendations](https://github.com/boredjnurseman/ml-recommender-system-design/blob/main/src/recommender_demo/serving.py): `src/recommender_demo/serving.py`

### Other components

- **Recommendation caller**

## Connections

- Recommendation caller → Serving orchestrator: requests
- Snapshot generator → Top-25 snapshot: creates
- Snapshot generator → Film candidate: generates
- Top-25 snapshot → Serving orchestrator: supplies candidates
- Serving orchestrator → Regional filter: filters by region
- Regional filter → Film candidate: keeps eligible
- Serving orchestrator → Stable assignment: assigns cohort
- Serving orchestrator → Policy loader: loads policy
- Baseline policy → Policy loader: read by
- Discovery policy → Policy loader: read by
- Serving orchestrator → Policy reranker: scores eligible
- Serving orchestrator → Five recommendations: returns top five
- Policy reranker → Five recommendations: ranks candidates
- Five recommendations → Recommendation caller: returns