# hitman-dev/recommender architecture

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

- Interactive diagram: https://gitdiagram.com/hitman-dev/recommender
- Repository: https://github.com/hitman-dev/recommender

## Overview

##### Project Type and Purpose
- This project is a content‐based recommendation web app that recommends movies, songs, and books using cosine similarity.
- It is built in Python and leverages tools and libraries like Pandas, scikit-learn, and Streamlit. It is designed for deployment on platforms such as Heroku Cloud and Streamlit Cloud.
- The purpose is to allow users to input a selection (movie, song, or book) and receive curated recommendations along with details about the items.

##### File Structure Analysis
- The top-level files include:
– Data_Links.txt and URL.txt: Possibly containing external dataset links.
– Procfile, runtime.txt, and setup.sh: Deployment and environment configuration files.
– README.md: Contains an overview and instructions.
– requirements.txt: Lists all necessary dependencies.
– app.py: Likely the entry-point of the Streamlit web application.
- There are specialized directories:
– "NoteBooks": Contains Jupyter notebooks (for testing, exploration, or demonstration of individual recommenders).
– "bookparquet", "movieparquet", "songparquet": Each holds Parquet files such as primary datasets, similarity matrices, and additional metadata. These are the data repositories powering recommendations.
– "images": Contains screenshots and UI images used in the README.
- This layout identifies distinct modules: a frontend built in Streamlit (in app.py), data storage (parquet files), and logic modules (within app.py and possibly helper functions in notebooks).

##### Architectural Components
- Frontend/User Interface:
– Represented by Streamlit in app.py. This is the interactive component where users select an input (movie, song, or book), view recommended outputs, and optionally change the theme.
- Recommendation Engine:
– The engine uses text vectorization (through CountVectorizer) and cosine similarity (from scikit-learn) to compute similarities between items.
– This logic is integrated within Python modules; although not separate in multiple files, conceptually think of this as one or more “Service” components within the application.
- Data Storage/Access Layer:
– Parquet files stored in separate directories act as the data repositories for books, movies, and songs.
– They store not only the lists of items but also pre-computed similarity matrices and additional information required for detailed views.
- Deployment/Configuration:
– Files like Procfile, runtime.txt, and setup.sh indicate the project’s readiness for cloud deployment.
- Auxiliary/Exploratory Components:

##### Relationships and Interactions
- The UI (Streamlit frontend) collects user inputs and passes them to the Recommendation Engine.
- The Recommendation Engine queries the appropriate datasets (from Parquet files) to compute similarity scores with the help of machine learning libraries (scikit-learn).
- Results are sent back to the UI for display — including both a list of recommended items and detailed descriptions.
- Deployment configuration files interact with the overall system to manage the environment and runtime behavior, but they are more on the side of infrastructure.

##### Architectural Patterns and Technologies
- The design is modular with clear separation between:
– Presentation Layer (Streamlit UI)
– Business Logic (Recommendation Engine using cosine similarity and vectorization)
– Data Access Layer (Parquet file storage for three types of content)
- Leveraging libraries and frameworks like scikit-learn (for computational tasks) and Pandas (for data manipulation) is critical to the core logic.
- There is an implicit MVC-like pattern: the UI is the view, the recommendation logic is the controller, and the datasets serve as the model.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer"
        UI["User Interface (Streamlit)"]
    end

    subgraph "Business Logic"
        RE["Recommendation Engine (Python, scikit-learn, Pandas)"]
        subgraph "Experimental Modules"
            BR["Book Recommender (Notebook)"]
            MR["Movie Recommender (Notebook)"]
            SR["Song Recommender (Notebook)"]
        end
    end

    subgraph "Data Access Layer"
        Books["Books Data (Parquet)"]
        Movies["Movies Data (Parquet)"]
        Songs["Songs Data (Parquet)"]
    end

    subgraph "Deployment & External Config"
        Proc["Procfile"]
        RT["runtime.txt"]
        SS["setup.sh"]
        DL["Data_Links.txt"]
        ULT["URL.txt"]
    end

    %% Connections between Presentation and Business Logic
    UI -->|"UserInput"| RE
    RE -->|"ReturnResults"| UI

    %% Connections between Business Logic and Experimental Modules
    RE -->|"experimental"| BR
    RE -->|"experimental"| MR
    RE -->|"experimental"| SR

    %% Connections from Recommendation Engine to Data Access Layer
    RE -->|"ReadBooks"| Books
    RE -->|"ReadMovies"| Movies
    RE -->|"ReadSongs"| Songs

    %% Styling for layers using classes
    class UI ui
    class RE logic
    class BR notebook
    class MR notebook
    class SR notebook
    class Books data
    class Movies data
    class Songs data
    class Proc,RT,SS deploy
    class DL,ULT external

    %% Click Events for Frontend and Business Logic
    click UI "https://github.com/hitman-dev/recommender/blob/main/app.py"
    click RE "https://github.com/hitman-dev/recommender/blob/main/app.py"
    click BR "https://github.com/hitman-dev/recommender/blob/main/NoteBooks/book_recommender.ipynb"
    click MR "https://github.com/hitman-dev/recommender/blob/main/NoteBooks/movie_recommender.ipynb"
    click SR "https://github.com/hitman-dev/recommender/blob/main/NoteBooks/song_recommender.ipynb"

    %% Click Events for Data Storage
    click Books "https://github.com/hitman-dev/recommender/tree/main/bookparquet/"
    click Movies "https://github.com/hitman-dev/recommender/tree/main/movieparquet/"
    click Songs "https://github.com/hitman-dev/recommender/tree/main/songparquet/"

    %% Click Events for Deployment & External Config
    click Proc "https://github.com/hitman-dev/recommender/tree/main/Procfile"
    click RT "https://github.com/hitman-dev/recommender/blob/main/runtime.txt"
    click SS "https://github.com/hitman-dev/recommender/blob/main/setup.sh"
    click DL "https://github.com/hitman-dev/recommender/blob/main/Data_Links.txt"
    click ULT "https://github.com/hitman-dev/recommender/blob/main/URL.txt"

    %% Class Definitions for color styling
    classDef ui fill:#f9c,stroke:#000,stroke-width:2px;
    classDef logic fill:#bbf,stroke:#000,stroke-width:2px;
    classDef notebook fill:#ffd,stroke:#000,stroke-width:2px;
    classDef data fill:#cfc,stroke:#000,stroke-width:2px;
    classDef deploy fill:#fbb,stroke:#000,stroke-width:2px;
    classDef external fill:#cff,stroke:#000,stroke-width:2px;
```
