# westlake-repl/pixelrec architecture

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

- Interactive diagram: https://gitdiagram.com/westlake-repl/pixelrec
- Repository: https://github.com/westlake-repl/pixelrec

## Overview

##### Project Type and Purpose
- This is an open-source, research-oriented machine-learning framework for benchmarking multi-modal recommender systems over a large image-interaction dataset (PixelRec).
- It provides data ingestion (raw CSV + images ➔ LMDB), configurable model training (IDNet/PixelNet/ViNet baselines), evaluation metrics, and experiment orchestration via YAML configs and entry scripts (main.py / run.py).

##### High-Level Components
a. Data Storage & Ingestion
- “dataset/” holds raw interaction files, item metadata, images.
b. Configuration Layer
- YAML files under `code/IDNet/`, `code/PixelNet/`, `code/ViNet/`, `code/overall/` define model hyperparameters and encoder choices.
c. Core Library (`code/REC/`)
- Data module (`REC/data/…`) handles datasets, batching, collate functions.
- Model module (`REC/model/…`) houses generic base models, IDNet/PixelNet/ViNet implementations, layer definitions, loading utilities.
- Trainer (`REC/trainer/trainer.py`) orchestrates forward/backward passes, optimizer schedules, mixed-precision, checkpointing.
- Evaluator (`REC/evaluator/…`) collects predictions, computes metrics (HR, NDCG, etc.), registers new metrics.
- Utils (`REC/utils/…`) include logging (local + Weights & Biases), argument parsing, enum types.
d. Entrypoint & Orchestration
- `code/main.py` and `code/run.py` parse CLI arguments (`--config_file`, `--device`), bootstrap the configurator, instantiate data/train/eval pipelines, then execute training or evaluation loops.
e. External Services
- GPU cluster (NVIDIA A100), LMDB file store, optional Weights & Biases server for experiment tracking.

##### Relationships & Data Flow
- Raw Dataset ➔ LMDB Generator ➔ LMDB Files
- LMDB Files + YAML Config ➔ Configurator ➔ DataLoader + Model Factory
- DataLoader ➔ Batches ➔ Trainer
- Trainer + Model ➔ Predictions ➔ Evaluator ➔ Metrics + Logs
- Metrics/Checkpoints ➔ Local Disk / W&B

##### Architectural Patterns & Design Principles
- Modular separation of concerns (Config / Data / Model / Trainer / Evaluator).
- Factory pattern in model loading (loads different baseline classes by name).
- Convention-over-configuration in directory structure (one YAML per experiment).
- Use of dependency injection via configurator for decoupling components.

##### Key Points to Capture
- The distinction between IDNet (ID-only baselines), PixelNet (end-to-end image + ID), ViNet (visual-only baselines).
- The role of `overall/*.yaml` in selecting image encoders (ViT, Swin, BEiT, RN50).
- The flow from raw dataset to LMDB to PyTorch DataLoader.
- The split between experiment orchestration (entry scripts) and reusable library code (`REC/`).
- The evaluation loop and metric reporting pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Preprocessing Phase
    subgraph "Preprocessing"
        Raw["Raw Dataset"]:::dataStore
        Gen["generate_lmdb.py"]:::ingestion
        LMDB["LMDB Files"]:::dataStore
    end
    Raw -->|"raw images+CSV"| Gen
    Gen -->|"stores LMDB"| LMDB

    %% Configuration Layer
    subgraph "Configuration"
        IDConf["IDNet YAML"]:::config
        PixConf["PixelNet YAML"]:::config
        ViConf["ViNet YAML"]:::config
        OvConf["Overall YAML"]:::config
        Configurator["Configurator"]:::config
    end
    IDConf --> Configurator
    PixConf --> Configurator
    ViConf --> Configurator
    OvConf --> Configurator

    %% Core Library
    subgraph "Core Library"
        subgraph "Data Module"
            DatasetDef["dataset/ & collate"]:::codeModule
            DataLoad["dataload.py"]:::codeModule
        end
        subgraph "Model Module"
            Base["basemodel.py & layers.py"]:::codeModule
            LoadFactory["load.py"]:::codeModule
            subgraph "Implementations"
                IDMod["IDNet"]:::codeModule
                PixMod["PixelNet"]:::codeModule
                ViMod["ViNet"]:::codeModule
                AltMods["Freeze/Id/Visual Models"]:::codeModule
            end
        end
        Trainer["trainer.py"]:::codeModule
        HyperTune["hyper_tuning.py"]:::codeModule
        Evaluator["evaluator"]:::codeModule
        Utils["utils"]:::codeModule
    end

    Configurator --> DataLoad
    Configurator --> LoadFactory
    LMDB --> DataLoad
    DataLoad -->|"batches"| Trainer
    LoadFactory -->|"model instance"| Trainer
    Trainer -->|"predictions"| Evaluator
    Evaluator -->|"metrics"| Utils

    %% Entrypoints
    subgraph "Entrypoints"
        Main{"main.py"}:::entry
        Run{"run.py"}:::entry
    end
    Main --> Configurator
    Main --> Trainer
    Run --> Configurator
    Run --> Trainer

    %% External Services
    ConfigSvc["GPU Cluster"]:::service
    LMDBStore["LMDB Store"]:::service
    WandB["Weights & Biases"]:::service
    Trainer --> ConfigSvc
    LMDB --> LMDBStore
    Utils --> WandB

    %% Click Events
    click Raw "https://github.com/westlake-repl/pixelrec/tree/main/dataset/"
    click Gen "https://github.com/westlake-repl/pixelrec/blob/main/code/generate_lmdb.py"
    click IDConf "https://github.com/westlake-repl/pixelrec/tree/main/code/IDNet/"
    click PixConf "https://github.com/westlake-repl/pixelrec/tree/main/code/PixelNet/"
    click ViConf "https://github.com/westlake-repl/pixelrec/tree/main/code/ViNet/"
    click OvConf "https://github.com/westlake-repl/pixelrec/tree/main/code/overall/"
    click Configurator "https://github.com/westlake-repl/pixelrec/blob/main/code/REC/config/configurator.py"
    click DataLoad "https://github.com/westlake-repl/pixelrec/blob/main/code/REC/data/dataload.py"
    click DatasetDef "https://github.com/westlake-repl/pixelrec/tree/main/code/REC/data/dataset/"
    click Base "https://github.com/westlake-repl/pixelrec/blob/main/code/REC/model/basemodel.py"
    click Base "https://github.com/westlake-repl/pixelrec/blob/main/code/REC/model/layers.py"
    click LoadFactory "https://github.com/westlake-repl/pixelrec/blob/main/code/REC/model/load.py"
    click IDMod "https://github.com/westlake-repl/pixelrec/tree/main/code/REC/model/IDNet/"
    click PixMod "https://github.com/westlake-repl/pixelrec/tree/main/code/REC/model/PixelNet/"
    click ViMod "https://github.com/westlake-repl/pixelrec/tree/main/code/REC/model/ViNet/"
    click AltMods "https://github.com/westlake-repl/pixelrec/tree/main/code/REC/model/FreezeModel/"
    click Trainer "https://github.com/westlake-repl/pixelrec/blob/main/code/REC/trainer/trainer.py"
    click HyperTune "https://github.com/westlake-repl/pixelrec/blob/main/code/REC/trainer/hyper_tuning.py"
    click Evaluator "https://github.com/westlake-repl/pixelrec/tree/main/code/REC/evaluator/"
    click Utils "https://github.com/westlake-repl/pixelrec/tree/main/code/REC/utils/"
    click Main "https://github.com/westlake-repl/pixelrec/blob/main/code/main.py"
    click Run "https://github.com/westlake-repl/pixelrec/blob/main/code/run.py"

    %% Styles
    classDef dataStore fill:#a2f5a2,stroke:#333,stroke-width:1px,shape:cylinder
    classDef ingestion fill:#b2fab4,stroke:#333,stroke-width:1px
    classDef config fill:#fff59d,stroke:#333,stroke-width:1px,shape:parallelogram
    classDef codeModule fill:#add8e6,stroke:#333,stroke-width:1px
    classDef entry fill:#add8e6,stroke:#333,stroke-width:1px,shape:diamond
    classDef service fill:#f28c8c,stroke:#333,stroke-width:1px
```
