# nogawanogawa/recommender_algorithms architecture

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

- Interactive diagram: https://gitdiagram.com/nogawanogawa/recommender_algorithms
- Repository: https://github.com/nogawanogawa/recommender_algorithms

## Overview

##### Main Components
- CPU Recommenders: In the “cpu” directory, you have several algorithm implementations (collaborative filtering, matrix factorization, factorization machine, iALS, EASE, and topic modeling). This module also includes Docker configurations and a setup script that suggests containerized execution.
- GPU Recommenders: The “gpu” directory similarly contains different recommender models designed for a GPU environment (LightGCN, Two-Tower model, sequential, recsim ng). It also has its own Docker configuration and setup scripts.
- Evaluation Module: Found in the “eval” directory, this part of the system is responsible for computing evaluation metrics such as NDCG, recall, precision, and F1-score, which are crucial for assessing the performance of the various algorithms.
- Utility Functions & Data Pipeline: Located in “util,” this part includes data loader and data preprocessor implementations (and possibly data_downloader/pipeline as mentioned in the README). These functions are likely used by both CPU and GPU modules to handle data setup and transformation tasks.

##### Relationships and Interactions
- The utility component (in “util”) is a shared resource accessed by both the CPU and GPU modules. It is responsible for loading and preparing the data required for training and testing.
- Both CPU- and GPU-based models (under “cpu” and “gpu”) are responsible for different recommendation algorithms. These modules process the datasets provided by the utility functions.
- The output or predictions from these recommender model modules are then evaluated using the evaluation module (“eval”), which calculates performance metrics.
- Docker containers and orchestration (via docker-compose) in both “cpu” and “gpu” folders suggest that the system is designed to run isolated environments for modeling and possibly ease deployment or scaling.

##### Architecturally Significant Patterns
- Separation of Concerns: The code is clearly segmented based on execution environment (CPU vs GPU) and functionality (modeling vs evaluation vs data handling).
- Containerization: Dockerfiles and docker-compose configurations indicate that containerization is a core part of deployment and reproducibility.
- Modular Design: Each recommender algorithm is implemented as separate scripts (e.g., individual Python files for collaborative filtering, matrix factorization, etc.), which supports plug-and-play and comparative development.

##### Incorporate Relevant Technologies and Frameworks
- Docker is used for environment setup and containerization.
- Python is the underlying language (referenced by pyproject.toml files), and you might be using a package management system like Poetry.
- If applicable, frameworks and libraries for machine learning or deep learning (such as PyTorch or TensorFlow) might be used within the GPU implementations, though you might need to inspect the source code for specifics.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Utility/Data Pipeline"
        direction TB
        U_DL["Data Loader"]:::util
        U_PP["Preprocessor"]:::util
    end

    subgraph "CPU Recommenders"
        direction TB
        CPU_D["CPU Recommenders (Containerized)"]:::docker
        CPU_CF["Collaborative Filtering"]:::cpu
        CPU_MF["Matrix Factorization"]:::cpu
        CPU_FM["Factorization Machine"]:::cpu
        CPU_iALS["iALS"]:::cpu
        CPU_EASE["EASE"]:::cpu
        CPU_TM["Topic Modeling"]:::cpu

        CPU_D --> CPU_CF
        CPU_D --> CPU_MF
        CPU_D --> CPU_FM
        CPU_D --> CPU_iALS
        CPU_D --> CPU_EASE
        CPU_D --> CPU_TM
    end

    subgraph "GPU Recommenders"
        direction TB
        GPU_D["GPU Recommenders (Containerized)"]:::docker
        GPU_LGCN["LightGCN"]:::gpu
        GPU_TTW["Two-Tower Model"]:::gpu
        GPU_SEQ["Sequential Model"]:::gpu
        GPU_RECSIM["Recsim NG"]:::gpu

        GPU_D --> GPU_LGCN
        GPU_D --> GPU_TTW
        GPU_D --> GPU_SEQ
        GPU_D --> GPU_RECSIM
    end

    subgraph "Evaluation Module"
        EVAL["Evaluation Module"]:::eval
    end

    %% Data Flow from Utility to Recommenders
    U_DL --> CPU_D
    U_DL --> GPU_D
    U_PP --> CPU_D
    U_PP --> GPU_D

    %% Data Flow from CPU Algorithms to Evaluation
    CPU_CF --> EVAL
    CPU_MF --> EVAL
    CPU_FM --> EVAL
    CPU_iALS --> EVAL
    CPU_EASE --> EVAL
    CPU_TM --> EVAL

    %% Data Flow from GPU Algorithms to Evaluation
    GPU_LGCN --> EVAL
    GPU_TTW --> EVAL
    GPU_SEQ --> EVAL
    GPU_RECSIM --> EVAL

    %% Click Events for Utility Functions
    click U_DL "https://github.com/nogawanogawa/recommender_algorithms/blob/main/util/dataloader.py"
    click U_PP "https://github.com/nogawanogawa/recommender_algorithms/blob/main/util/preprpcessor.py"

    %% Click Events for CPU Recommenders
    click CPU_D "https://github.com/nogawanogawa/recommender_algorithms/tree/main/cpu/"
    click CPU_CF "https://github.com/nogawanogawa/recommender_algorithms/blob/main/cpu/src/collaborative_filtering.py"
    click CPU_MF "https://github.com/nogawanogawa/recommender_algorithms/blob/main/cpu/src/matrix_factorization.py"
    click CPU_FM "https://github.com/nogawanogawa/recommender_algorithms/blob/main/cpu/src/fm.py"
    click CPU_iALS "https://github.com/nogawanogawa/recommender_algorithms/blob/main/cpu/src/iALS.py"
    click CPU_EASE "https://github.com/nogawanogawa/recommender_algorithms/blob/main/cpu/src/ease.py"
    click CPU_TM "https://github.com/nogawanogawa/recommender_algorithms/tree/main/cpu/"

    %% Click Events for GPU Recommenders
    click GPU_D "https://github.com/nogawanogawa/recommender_algorithms/tree/main/gpu/"
    click GPU_LGCN "https://github.com/nogawanogawa/recommender_algorithms/tree/main/gpu/"
    click GPU_TTW "https://github.com/nogawanogawa/recommender_algorithms/tree/main/gpu/"
    click GPU_SEQ "https://github.com/nogawanogawa/recommender_algorithms/tree/main/gpu/"
    click GPU_RECSIM "https://github.com/nogawanogawa/recommender_algorithms/tree/main/gpu/"

    %% Click Event for Evaluation Module
    click EVAL "https://github.com/nogawanogawa/recommender_algorithms/blob/main/eval/eval_func.py"

    %% Styles
    classDef util fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef cpu fill:#cce5ff,stroke:#1b4f72,stroke-width:2px;
    classDef gpu fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef eval fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef docker fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
```
