# ropdam/recommender_comparison architecture

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

- Interactive diagram: https://gitdiagram.com/ropdam/recommender_comparison
- Repository: https://github.com/ropdam/recommender_comparison

## Overview

##### Project Type and Purpose
- This is an experimental ML research pipeline for a Master’s thesis comparing three recommendation-engine algorithms (BPR, CFRNN, NCF) on MovieLens and Amazon datasets.

##### File-Structure Analysis
- Top-level scripts:
- Data_prep.py – data loading & preprocessing
- BPR.py, CFRNN.py, NCF.py – each model implemented as a class
- Evaluation.py – metrics computation & benchmarking
- visualize_results.py – produce plots/tables from evaluation outputs
- Helpers.py – shared utility functions (e.g., I/O, logging)
- Notebooks/Example – sample end-to-end run of all models
- Notebooks/Thesis – separate experiment notebooks (hyperparameter search, final results)
- Results/Plots & Results/Thesis – output artifacts (charts, thesis figures)

##### Key README Insights
- Describes the three algorithms with literature references.
- Data format requirements (user_id, item_id, datetime).
- Dependencies: pandas, numpy, tensorflow, etc.

##### Core Components
a. Main Components
- Data Sources: MovieLens CSV, Amazon CSVs
- Data Preparation Module (Data_prep.py)
- Model Modules:
- BPR Class (BPR.py)
- CFRNN Class (CFRNN.py)
- NCF Class (NCF.py)
- Shared Utilities (Helpers.py)
- Evaluation Module (Evaluation.py)
- Visualization Module (visualize_results.py)
- Orchestration Layer: Jupyter Notebooks (Example + Thesis)
- Results Storage: Results/Plots, Results/Thesis directories

b. Relationships & Data Flow
1. Raw data → Data_prep → cleaned/structured data
2. Cleaned data + Helpers → each Model Module (train/predict)
3. Model outputs → Evaluation Module → metrics & benchmark tables
4. Metrics → Visualization Module → plots & figures
5. Notebooks call each step in sequence and read/write from Results folders

c. Architectural Patterns & Principles
- Pipeline Pattern: clear, linear flow from raw data to final figures
- Modular Design: each algorithm isolated in its own class, reusable helpers
- Separation of Concerns: data prep, modeling, evaluation, visualization all decoupled
- Strategy Pattern: interchangeable recommendation algorithms behind a common interface

d. Key Technologies & Frameworks
- Data handling: pandas, numpy
- Deep learning: TensorFlow ≥ 2.1
- Experiment orchestration: Jupyter Notebook
- Utils: progressbar, multiprocessing, csv

##### Detailed Component Breakdown (to capture all architectural elements)
- Data Sources: MovieLens, Amazon (CSV files)
- Preprocessing Step: Data_prep.py
- Helper Library: Helpers.py (I/O helpers, logging, utilities)
- Model Implementations: BPR.py, CFRNN.py, NCF.py (each exposes train(), predict())
- Evaluation Engine: Evaluation.py (computes ranking metrics, supports hyperparameter search)
- Visualization Engine: visualize_results.py (generates plots stored in Results/Plots)
- Experiment Layer: Example/all_models.ipynb and Thesis/*.ipynb orchestrate end-to-end runs
- Output Artifacts: Results/Plots/*.png, Results/Thesis/*.pdf

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layers
    RawData["MovieLens & Amazon CSVs"]:::data
    CleanData["Cleaned Data"]:::data
    ResultsPlots["Results/Plots"]:::data
    ResultsThesis["Results/Thesis"]:::data

    %% Processing Modules
    DataPrep["DataPrep Module"]:::process
    Helpers["Shared Utilities (Helpers)"]:::process
    subgraph "Model Modules"
        BPR["BPR Model"]:::process
        CFRNN["CFRNN Model"]:::process
        NCF["NCF Model"]:::process
    end
    Evaluation["Evaluation Module"]:::process
    Visualization["Visualization Module"]:::process

    %% Orchestration
    NotebooksExample["Example Notebook"]:::orchestration
    NotebooksThesis["Thesis Notebooks"]:::orchestration

    %% Data Flow
    RawData --> DataPrep
    DataPrep --> CleanData
    CleanData --> BPR
    CleanData --> CFRNN
    CleanData --> NCF
    BPR --> Evaluation
    CFRNN --> Evaluation
    NCF --> Evaluation
    Evaluation --> Visualization
    Visualization --> ResultsPlots
    Visualization --> ResultsThesis

    %% Helpers usage
    Helpers --> DataPrep
    Helpers --> BPR
    Helpers --> CFRNN
    Helpers --> NCF

    %% Notebook orchestration
    NotebooksExample --> DataPrep
    NotebooksExample --> BPR
    NotebooksExample --> CFRNN
    NotebooksExample --> NCF
    NotebooksExample --> Evaluation
    NotebooksExample --> Visualization

    NotebooksThesis --> DataPrep
    NotebooksThesis --> BPR
    NotebooksThesis --> CFRNN
    NotebooksThesis --> NCF
    NotebooksThesis --> Evaluation
    NotebooksThesis --> Visualization

    %% Click Events
    click DataPrep "https://github.com/ropdam/recommender_comparison/blob/master/Data_prep.py"
    click BPR "https://github.com/ropdam/recommender_comparison/blob/master/BPR.py"
    click CFRNN "https://github.com/ropdam/recommender_comparison/blob/master/CFRNN.py"
    click NCF "https://github.com/ropdam/recommender_comparison/blob/master/NCF.py"
    click Helpers "https://github.com/ropdam/recommender_comparison/blob/master/Helpers.py"
    click Evaluation "https://github.com/ropdam/recommender_comparison/blob/master/Evaluation.py"
    click Visualization "https://github.com/ropdam/recommender_comparison/blob/master/visualize_results.py"
    click NotebooksExample "https://github.com/ropdam/recommender_comparison/blob/master/Notebooks/Example/all_models.ipynb"
    click NotebooksThesis "https://github.com/ropdam/recommender_comparison/tree/master/Notebooks/Thesis"

    %% Styles
    classDef data fill:#D6EFFF,stroke:#0366d6,color:#0366d6
    classDef process fill:#DFFFE0,stroke:#28a745,color:#28a745
    classDef orchestration fill:#FFE5B4,stroke:#FF8C00,color:#FF8C00
```
