# plaggy/recommender_systems architecture

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

- Interactive diagram: https://gitdiagram.com/plaggy/recommender_systems
- Repository: https://github.com/plaggy/recommender_systems

## Overview

This repository prepares Yelp restaurant, review, and user data, then trains and evaluates either a collaborative-filtering LightFM recommender or a two-stage LightFM→LightGBM ranker. The main workflow is dataset preparation, interaction splitting/encoding, model fitting, candidate refinement (two-level mode), and AUC/MAP@K evaluation. The README documents additional two-level stages whose full implementation is not sampled; those capabilities are shown at the module level, with uncertain internal wiring omitted.

Main entry points: [`two_level_pipeline.py`](https://github.com/plaggy/recommender_systems/blob/master/two_level_pipeline.py) (Two-level workflow), [`yelp_process.py`](https://github.com/plaggy/recommender_systems/blob/master/yelp_process.py) (Extract and filter data), [`main.py`](https://github.com/plaggy/recommender_systems/blob/master/main.py) (Model selection), [`lightfm_only.py`](https://github.com/plaggy/recommender_systems/blob/master/lightfm_only.py) (Split and encode)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Yelp preparation"]
  node_prepare["Extract and filter data<br/>[yelp_process.py]"]
  node_interactions["Interactions and profiles<br/>[yelp_process.py]"]
  node_businesses["Restaurant features<br/>[yelp_process.py]"]
end

subgraph group_entry["Run selection"]
  node_entrypoint["Model selection<br/>[main.py]"]
end

subgraph group_models["Recommendation models"]
  node_lfm_split["Split and encode<br/>[lightfm_only.py]"]
  node_lfm_model["LightFM model<br/>[lightfm_only.py]"]
  node_twolevel["Two-level workflow"]
  node_training_sets["Training and test sets"]
  node_feature_build["Feature extraction"]
  node_encoded_sets["Encoded interactions"]
  node_candidate_select["Candidate selection"]
  node_candidate_sets["Refined candidates"]
  node_lgb_model["LightGBM ranker"]
end

subgraph group_evaluation["Evaluation"]
  node_metrics["AUC and MAP@K<br/>[utils.py]"]
end

node_operator(("Runner"))
node_yelp_data["Yelp dataset"]

node_operator -->|"provides"| node_yelp_data
node_yelp_data -->|"reads"| node_prepare
node_prepare -->|"writes"| node_interactions
node_prepare -->|"writes"| node_businesses
node_operator -->|"runs"| node_entrypoint
node_entrypoint -->|"selects LFM"| node_lfm_split
node_entrypoint -->|"selects pipeline"| node_twolevel
node_interactions -->|"reads"| node_lfm_split
node_lfm_split -->|"fits"| node_lfm_model
node_lfm_model -->|"evaluated by"| node_metrics
node_twolevel -->|"reads"| node_interactions
node_twolevel -->|"reads"| node_businesses
node_twolevel -->|"splits"| node_training_sets
node_twolevel -->|"extracts features"| node_feature_build
node_twolevel -->|"encodes"| node_encoded_sets
node_twolevel -->|"scores candidates"| node_candidate_select
node_candidate_select -->|"writes"| node_candidate_sets
node_twolevel -->|"trains"| node_lgb_model
node_lgb_model -->|"evaluated by"| node_metrics

click node_prepare "https://github.com/plaggy/recommender_systems/blob/master/yelp_process.py"
click node_interactions "https://github.com/plaggy/recommender_systems/blob/master/yelp_process.py"
click node_businesses "https://github.com/plaggy/recommender_systems/blob/master/yelp_process.py"
click node_entrypoint "https://github.com/plaggy/recommender_systems/blob/master/main.py"
click node_lfm_split "https://github.com/plaggy/recommender_systems/blob/master/lightfm_only.py"
click node_lfm_model "https://github.com/plaggy/recommender_systems/blob/master/lightfm_only.py"
click node_twolevel "https://github.com/plaggy/recommender_systems/blob/master/two_level_pipeline.py"
click node_training_sets "https://github.com/plaggy/recommender_systems/blob/master/two_level_pipeline.py"
click node_feature_build "https://github.com/plaggy/recommender_systems/blob/master/two_level_pipeline.py"
click node_encoded_sets "https://github.com/plaggy/recommender_systems/blob/master/two_level_pipeline.py"
click node_candidate_select "https://github.com/plaggy/recommender_systems/blob/master/two_level_pipeline.py"
click node_candidate_sets "https://github.com/plaggy/recommender_systems/blob/master/two_level_pipeline.py"
click node_lgb_model "https://github.com/plaggy/recommender_systems/blob/master/two_level_pipeline.py"
click node_metrics "https://github.com/plaggy/recommender_systems/blob/master/utils.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_prepare,node_interactions,node_businesses toneBlue
class node_entrypoint toneAmber
class node_lfm_split,node_lfm_model,node_twolevel,node_training_sets,node_feature_build,node_encoded_sets,node_candidate_select,node_candidate_sets,node_lgb_model toneMint
class node_metrics toneRose
class node_operator,node_yelp_data toneIndigo
```

## Components

### Yelp preparation

- [Extract and filter data](https://github.com/plaggy/recommender_systems/blob/master/yelp_process.py): `yelp_process.py`
- [Interactions and profiles](https://github.com/plaggy/recommender_systems/blob/master/yelp_process.py): `yelp_process.py`
- [Restaurant features](https://github.com/plaggy/recommender_systems/blob/master/yelp_process.py): `yelp_process.py`

### Run selection

- [Model selection](https://github.com/plaggy/recommender_systems/blob/master/main.py): `main.py`

### Recommendation models

- [Split and encode](https://github.com/plaggy/recommender_systems/blob/master/lightfm_only.py): `lightfm_only.py`
- [LightFM model](https://github.com/plaggy/recommender_systems/blob/master/lightfm_only.py): `lightfm_only.py`
- [Two-level workflow](https://github.com/plaggy/recommender_systems/blob/master/two_level_pipeline.py): `two_level_pipeline.py`
- [Training and test sets](https://github.com/plaggy/recommender_systems/blob/master/two_level_pipeline.py): `two_level_pipeline.py`
- [Feature extraction](https://github.com/plaggy/recommender_systems/blob/master/two_level_pipeline.py): `two_level_pipeline.py`
- [Encoded interactions](https://github.com/plaggy/recommender_systems/blob/master/two_level_pipeline.py): `two_level_pipeline.py`
- [Candidate selection](https://github.com/plaggy/recommender_systems/blob/master/two_level_pipeline.py): `two_level_pipeline.py`
- [Refined candidates](https://github.com/plaggy/recommender_systems/blob/master/two_level_pipeline.py): `two_level_pipeline.py`
- [LightGBM ranker](https://github.com/plaggy/recommender_systems/blob/master/two_level_pipeline.py): `two_level_pipeline.py`

### Evaluation

- [AUC and MAP@K](https://github.com/plaggy/recommender_systems/blob/master/utils.py): `utils.py`

### Other components

- **Runner**
- **Yelp dataset**

## Connections

- Runner → Yelp dataset: provides
- Yelp dataset → Extract and filter data: reads
- Extract and filter data → Interactions and profiles: writes
- Extract and filter data → Restaurant features: writes
- Runner → Model selection: runs
- Model selection → Split and encode: selects LFM
- Model selection → Two-level workflow: selects pipeline
- Interactions and profiles → Split and encode: reads
- Split and encode → LightFM model: fits
- LightFM model → AUC and MAP@K: evaluated by
- Two-level workflow → Interactions and profiles: reads
- Two-level workflow → Restaurant features: reads
- Two-level workflow → Training and test sets: splits
- Two-level workflow → Feature extraction: extracts features
- Two-level workflow → Encoded interactions: encodes
- Two-level workflow → Candidate selection: scores candidates
- Candidate selection → Refined candidates: writes
- Two-level workflow → LightGBM ranker: trains
- LightGBM ranker → AUC and MAP@K: evaluated by