# minhducnguyen9705/book-recommendation architecture

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

- Interactive diagram: https://gitdiagram.com/minhducnguyen9705/book-recommendation
- Repository: https://github.com/minhducnguyen9705/book-recommendation

## Overview

##### Project Type and Purpose
- This is a Python-based book recommendation system (“book_rec”) that implements multiple recommendation algorithms (Popularity, Naive Bayes, TF-IDF, Matrix Factorization, NeuMF).
- It provides training pipelines, model storage (weights), inference scripts, and exposes an API (via `API.py`/`app.py`) for real‐time recommendations.

##### High-Level Architecture Overview
- The system can be broken down into these main components:
A) Data Layer
B) Model Training Pipelines
C) Model Storage / Registry
D) Inference Service (API Layer)
E) CI/CD & Dev Environment
F) Client / Consumer

##### Component Details & Interactions
A) Data Layer
- CSV files under `Data/` (final_books.csv, interaction.csv, user_data.csv)
- Used by all training pipelines and by preprocessing modules
B) Model Training Pipelines
- Six algorithm-specific modules:
1. Popularity (`Popularity/main.py`, `Popularity/model.py`)
2. NaiveBayes (`NaiveBayes/train.py`, `NaiveBayes/infer.py`)
3. TF-IDF (`TF-IDF/train.py`, `TF-IDF/infer.py`)
4. Matrix Factorization (`Matrix_factorization/train.py`, `inference.py`)
5. NeuMF (`NeuMF/train.py`, `inference.py`)
- Each pipeline reads raw data, runs preprocessing (in `utils.py` or `preprocessing_data.py`), trains the model, evaluates (via `test.py`), and writes weights or artifacts.
C) Model Storage / Registry
- `weights/` folder stores trained model files (e.g., `*.h5` for NeuMF, `vocab.joblib` for NaiveBayes).
- This acts as a simple model registry that the inference layer pulls from.
D) Inference Service (API Layer)
- `API.py` and `app.py` implement a Flask/FastAPI service exposing endpoints like `/recommend` or `/predict`.
- On request, loads the appropriate model from `weights/` and runs inference logic in each module’s `inference.py`.
- `example.py` demonstrates client calls to the API.
E) CI/CD & Dev Environment
- `.github/workflows/train.yml` builds and runs training tests on PRs.
- `.github/workflows/demo.yml` might deploy or run a demo.
- `.devcontainer/devcontainer.json` sets up a reproducible dev container.
F) Client / Consumer
- Could be any front end or script that calls the API (`example.py` is one).

##### Architectural Patterns & Design Principles
- Modular “per-algorithm” pattern: each recommendation approach is fully encapsulated in its own directory.
- Clear separation of concerns: data ingestion → preprocessing → training → testing → inference.
- Simple registry pattern for model artifacts (weights directory).
- CI pipelines enforce automated testing on training code and demo deployments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        DataCSV["CSV Data Files"]:::data
    end
    click DataCSV "https://github.com/minhducnguyen9705/book-recommendation/tree/main/Data/"

    %% Training Pipelines
    subgraph "Training Pipelines"
        PopPipe["Popularity Pipeline"]:::compute
        NBPipe["Naive Bayes Pipeline"]:::compute
        TFIDFPipe["TF-IDF Pipeline"]:::compute
        MFPipe["Matrix Factorization Pipeline"]:::compute
        NeuMFPipe["NeuMF Pipeline"]:::compute
    end
    click PopPipe "https://github.com/minhducnguyen9705/book-recommendation/tree/main/Popularity/"
    click NBPipe "https://github.com/minhducnguyen9705/book-recommendation/tree/main/NaiveBayes/"
    click TFIDFPipe "https://github.com/minhducnguyen9705/book-recommendation/tree/main/TF-IDF/"
    click MFPipe "https://github.com/minhducnguyen9705/book-recommendation/tree/main/Matrix_factorization/"
    click NeuMFPipe "https://github.com/minhducnguyen9705/book-recommendation/tree/main/NeuMF/"

    %% Model Registry
    ModelRegistry["Model Registry (weights/)"]:::storage
    click ModelRegistry "https://github.com/minhducnguyen9705/book-recommendation/tree/main/weights/"

    %% Inference Service
    InferenceService["API Service (API.py / app.py)"]:::service
    click InferenceService "https://github.com/minhducnguyen9705/book-recommendation/blob/main/API.py"
    click InferenceService "https://github.com/minhducnguyen9705/book-recommendation/blob/main/app.py"

    %% CI/CD & Dev Environment
    subgraph "CI/CD & Dev Environment"
        CI["Train Workflow"]:::infra
        click CI "https://github.com/minhducnguyen9705/book-recommendation/blob/main/.github/workflows/train.yml"
        Demo["Demo Workflow"]:::infra
        click Demo "https://github.com/minhducnguyen9705/book-recommendation/blob/main/.github/workflows/demo.yml"
        DevEnv["Dev Container"]:::infra
        click DevEnv "https://github.com/minhducnguyen9705/book-recommendation/blob/main/.devcontainer/devcontainer.json"
    end

    %% Client / Consumer
    Client["Client Example (example.py)"]:::client
    click Client "https://github.com/minhducnguyen9705/book-recommendation/blob/main/example.py"

    %% Relationships
    DataCSV -->|reads data| PopPipe
    DataCSV -->|reads data| NBPipe
    DataCSV -->|reads data| TFIDFPipe
    DataCSV -->|reads data| MFPipe
    DataCSV -->|reads data| NeuMFPipe

    PopPipe -->|train → store weights| ModelRegistry
    NBPipe -->|train → store weights| ModelRegistry
    TFIDFPipe -->|train → store weights| ModelRegistry
    MFPipe -->|train → store weights| ModelRegistry
    NeuMFPipe -->|train → store weights| ModelRegistry

    ModelRegistry -->|load model →| InferenceService
    Client -->|HTTP request →| InferenceService
    InferenceService -->|HTTP response →| Client

    CI -->|run training tests on PRs→| PopPipe
    CI -->|run training tests on PRs→| NBPipe
    CI -->|run training tests on PRs→| TFIDFPipe
    CI -->|run training tests on PRs→| MFPipe
    CI -->|run training tests on PRs→| NeuMFPipe
    Demo -->|deploy/demo→| InferenceService
    DevEnv -->|onboard devs→| PopPipe
    DevEnv -->|onboard devs→| NBPipe
    DevEnv -->|onboard devs→| TFIDFPipe
    DevEnv -->|onboard devs→| MFPipe
    DevEnv -->|onboard devs→| NeuMFPipe

    %% Styles
    classDef data fill:#ccf,stroke:#333,stroke-width:1px;
    classDef compute fill:#cfc,stroke:#333,stroke-width:1px;
    classDef storage fill:#ccf,stroke:#333,stroke-width:1px;
    classDef service fill:#fc9,stroke:#333,stroke-width:1px;
    classDef infra fill:#ddd,stroke:#333,stroke-width:1px;
    classDef client fill:#eee,stroke:#999,stroke-dasharray: 5 5,stroke-width:1px;
```
