# triiju/hybrid-recommendation-engine architecture

> Architecture diagram of the GitHub repository triiju/hybrid-recommendation-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/triiju/hybrid-recommendation-engine
- Repository: https://github.com/triiju/hybrid-recommendation-engine

## Overview

##### Project type and purpose
- This is a full-stack, modular hybrid recommendation engine written in Python.
- It provides both an offline batch pipeline (data download, preprocessing, baseline models, tuning, evaluation, cold-start experiments) and an online serving layer (FastAPI REST API).

##### File structure
Top-level directories:
- api/               – FastAPI application for serving recommendations and metadata
- scripts/           – Standalone automation scripts (alpha sweep, end-to-end pipeline)
- src/               – Core Python modules implementing data loading, preprocessing, recommenders, evaluation, logging, hyperparameter tuning, and the API entry point via uvicorn
- models/            – Serialized model artifacts (e.g., neural_cf.pt)
- experiments/       – Empty placeholder for experiment outputs
- tests/             – Unit tests for key modules and metrics
Configuration and build files:
- Makefile           – Orchestrates reproducible pipeline targets
- requirements.txt   – Python dependency list
- vercel.json        – Deployment configuration (likely for frontend or serverless host)

##### README for additional insights
- Offers a clear breakdown of each component’s file, function, and purpose
- Defines the offline workflow (download → preprocess → baselines → neural → hybrid → evaluate → alpha sweep → cold-start)
- Exposes a FastAPI-based REST API with three endpoints: /recommend, /health, /meta
- Mentions external dependencies: MovieLens 100K dataset, PyTorch, Optuna, FastAPI, uvicorn

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["Client / Consumer"]:::external -->|calls REST API| API["FastAPI App"]:::api

    %% Offline Batch Pipeline
    subgraph "Offline Batch Pipeline"
        direction TB
        Makefile["Makefile"]:::orchestration
        RunScript["run_pipeline.sh"]:::orchestration
        AlphaSweep["Alpha Sweep Script"]:::orchestration
        DataLoad["Data Loading"]:::dataStore
        Preprocess["Preprocessing"]:::dataStore
        Popularity["Popularity Baseline"]:::model
        CF["Collaborative-Filtering Baseline"]:::model
        Content["Content-Based Model"]:::model
        NeuralCF["Neural CF Model"]:::model
        Hybrid["Hybrid Blending"]:::model
        Optuna["Optuna Tuner"]:::orchestration
        ColdStart["Cold-Start Evaluation"]:::model
        Eval["Evaluation Pipeline"]:::model
        Metrics["Metrics Definitions"]:::model
        Logging["Logging Config"]:::orchestration
        Config["Configuration Settings"]:::orchestration
        Utils["Utility Functions"]:::orchestration
        MultiAnchor["Multi-Anchor Logic"]:::model
        ModelStore["Model Artifact Store"]:::dataStore

        Makefile -->|invokes| RunScript
        RunScript -->|runs| DataLoad
        DataLoad -->|outputs raw CSV| Preprocess
        Preprocess -->|outputs processed data| Popularity
        Preprocess --> CF
        Preprocess --> Content
        Preprocess --> NeuralCF
        Popularity -->|predictions| Eval
        CF --> Eval
        Content --> Eval
        NeuralCF --> Eval
        Eval --> Metrics
        Eval --> ColdStart
        Eval -->|stores model| ModelStore
        Optuna -->|tunes hyperparams| NeuralCF
        AlphaSweep -->|sweeps| Hybrid
        ColdStart --> Eval
        Hybrid --> Eval
        Logging -->|used by| DataLoad
        Logging --> Preprocess
        Logging --> Eval
        Config --> DataLoad
        Config --> Hybrid
        Utils --> DataLoad
        Utils --> Eval
        MultiAnchor --> Hybrid
    end

    %% Online Serving Layer
    subgraph "Online Serving Layer"
        direction TB
        API["FastAPI App"]:::api
        MetaWriter["Service Metadata Writer"]:::api
        API -->|calls| Hybrid
        API --> MetaWriter
        API -->|health check| Health["/health Endpoint"]:::api
        API -->|recommend| Recommend["/recommend Endpoint"]:::api
        API -->|meta| Meta["/meta Endpoint"]:::api
        ModelStore -->|loads model| API
    end

    %% External Source
    ExtSource["MovieLens 100K Dataset"]:::dataStore
    ExtSource --> DataLoad

    %% Click Events
    click DataLoad "https://github.com/triiju/hybrid-recommendation-engine/blob/main/src/data_loading.py"
    click Preprocess "https://github.com/triiju/hybrid-recommendation-engine/blob/main/src/preprocess.py"
    click Popularity "https://github.com/triiju/hybrid-recommendation-engine/blob/main/src/popularity.py"
    click CF "https://github.com/triiju/hybrid-recommendation-engine/blob/main/src/cf_baseline.py"
    click Content "https://github.com/triiju/hybrid-recommendation-engine/blob/main/src/content_based.py"
    click NeuralCF "https://github.com/triiju/hybrid-recommendation-engine/blob/main/src/neural_cf.py"
    click Hybrid "https://github.com/triiju/hybrid-recommendation-engine/blob/main/src/hybrid.py"
    click Optuna "https://github.com/triiju/hybrid-recommendation-engine/blob/main/src/optuna_tune.py"
    click AlphaSweep "https://github.com/triiju/hybrid-recommendation-engine/blob/main/scripts/alpha_sweep.py.py"
    click ColdStart "https://github.com/triiju/hybrid-recommendation-engine/blob/main/src/cold_start.py"
    click Eval "https://github.com/triiju/hybrid-recommendation-engine/blob/main/src/evaluation.py"
    click Metrics "https://github.com/triiju/hybrid-recommendation-engine/blob/main/src/metrics.py"
    click Logging "https://github.com/triiju/hybrid-recommendation-engine/blob/main/src/logging_config.py"
    click Makefile "https://github.com/triiju/hybrid-recommendation-engine/tree/main/Makefile"
    click RunScript "https://github.com/triiju/hybrid-recommendation-engine/tree/main/scripts/run_pipeline_sh"
    click ModelStore "https://github.com/triiju/hybrid-recommendation-engine/tree/main/models/"
    click API "https://github.com/triiju/hybrid-recommendation-engine/blob/main/src/app.py"
    click MetaWriter "https://github.com/triiju/hybrid-recommendation-engine/blob/main/src/meta_writer.py"
    click Config "https://github.com/triiju/hybrid-recommendation-engine/blob/main/src/config.py"
    click Utils "https://github.com/triiju/hybrid-recommendation-engine/blob/main/src/utils.py"
    click MultiAnchor "https://github.com/triiju/hybrid-recommendation-engine/blob/main/src/multi_anchor_recommend.py"

    %% Styles
    classDef dataStore fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef model fill:#98FB98,stroke:#000,stroke-width:1px
    classDef orchestration fill:#FFA500,stroke:#000,stroke-width:1px
    classDef api fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef external fill:#f2f2f2,stroke:#000,stroke-width:1px
```
