# u-faizan/movies-recommendation architecture

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

- Interactive diagram: https://gitdiagram.com/u-faizan/movies-recommendation
- Repository: https://github.com/u-faizan/movies-recommendation

## Overview

##### Project type and purpose
- This “Movies-Recommendation” repo contains three parallel recommendation engines—Sentence-Transformer, TFIDF-KNN, and TMDB-API—each packaged as a small Python “app.py” service with its own data files and dependencies.
- Overall purpose: given a movie title or user input, return similar movie recommendations using different algorithms and/or external metadata.

##### File structure
- Top-level directories:
- Sentence-Transformer/
- TFIDF-KNN/
- TMDB-API/
- Each directory contains:
- app.py – the entry point for that recommendation engine service
- imdb_movies.csv or movies_metadata.csv – dataset of movies and their metadata
- configuration files (requirements.txt or pyproject.toml)
- TFIDF-KNN has an additional model training notebook (model.ipynb) and serialized artifacts (knn_model.pkl, tfidf_vectorizer.pkl) under pickle_model/.

##### README
- The README has only the project title. No architecture details are described there. We infer that the repo is an umbrella for three standalone recommendation microservices.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients and Gateway
    Client["Client (Web/CLI)"]:::external
    APIGateway["API Gateway/Router"]:::internal

    %% Recommendations Suite
    subgraph "Recommendations Suite"
        direction TB
        ST["Sentence-Transformer Service"]:::internal
        TF["TFIDF-KNN Service"]:::internal
        TMDB["TMDB-API Service"]:::internal
    end

    %% Data Stores for Sentence-Transformer
    STCSV["imdb_movies.csv"]:::datastore

    %% Data Stores and Artifacts for TFIDF-KNN
    TFCSV["imdb_movies.csv"]:::datastore
    KNNModel["knn_model.pkl"]:::datastore
    TFIDFVec["tfidf_vectorizer.pkl"]:::datastore
    TFMetaCSV["movies_metadata.csv"]:::datastore
    TFNotebook["model.ipynb"]:::datastore
    TFReq["requirements.txt"]:::datastore
    TFPy["pyproject.toml"]:::datastore

    %% Data Stores and Configs for TMDB-API
    TMDBCSV["imdb_movies.csv"]:::datastore
    TMDBReq["requirements.txt"]:::datastore
    TMDBPy["pyproject.toml"]:::datastore
    TMDBEnv[".python-version"]:::datastore
    TMDBLock["uv.lock"]:::datastore

    %% External Service
    EXT["TMDB REST API"]:::external

    %% Request Flow
    Client -->|"HTTP/JSON"| APIGateway
    APIGateway -->|"Route Request"| ST
    APIGateway -->|"Route Request"| TF
    APIGateway -->|"Route Request"| TMDB

    %% Sentence-Transformer Data Load and Response
    STCSV -->|"CSV Load"| ST
    ST -->|"HTTP/JSON Response"| APIGateway

    %% TFIDF-KNN Data Load and Response
    TFCSV -->|"CSV Load"| TF
    KNNModel -->|"Load Pickle"| TF
    TFIDFVec -->|"Load Pickle"| TF
    TFMetaCSV -->|"CSV Load"| TF
    TFNotebook -->|"Reference"| TF
    TFReq -->|"Deps"| TF
    TFPy -->|"Deps"| TF
    TF -->|"HTTP/JSON Response"| APIGateway

    %% TMDB-API Data Load, External Call, and Response
    TMDBCSV -->|"CSV Load"| TMDB
    TMDBReq -->|"Deps"| TMDB
    TMDBPy -->|"Deps"| TMDB
    TMDBEnv -->|"Env Config"| TMDB
    TMDBLock -->|"Lock"| TMDB
    TMDB -->|"HTTPS/JSON"| EXT
    EXT -->|"JSON Response"| TMDB
    TMDB -->|"HTTP/JSON Response"| APIGateway

    %% Final response
    APIGateway -->|"HTTP/JSON"| Client

    %% Click Events
    click ST "https://github.com/u-faizan/movies-recommendation/blob/main/Sentence-Transformer/app.py"
    click STCSV "https://github.com/u-faizan/movies-recommendation/blob/main/Sentence-Transformer/imdb_movies.csv"
    click TF "https://github.com/u-faizan/movies-recommendation/blob/main/TFIDF-KNN/app.py"
    click TFCSV "https://github.com/u-faizan/movies-recommendation/blob/main/TFIDF-KNN/imdb_movies.csv"
    click KNNModel "https://github.com/u-faizan/movies-recommendation/blob/main/TFIDF-KNN/pickle_model/knn_model.pkl"
    click TFIDFVec "https://github.com/u-faizan/movies-recommendation/blob/main/TFIDF-KNN/pickle_model/tfidf_vectorizer.pkl"
    click TFMetaCSV "https://github.com/u-faizan/movies-recommendation/blob/main/TFIDF-KNN/pickle_model/movies_metadata.csv"
    click TFNotebook "https://github.com/u-faizan/movies-recommendation/blob/main/TFIDF-KNN/model.ipynb"
    click TFReq "https://github.com/u-faizan/movies-recommendation/blob/main/TFIDF-KNN/requirements.txt"
    click TFPy "https://github.com/u-faizan/movies-recommendation/blob/main/TFIDF-KNN/pyproject.toml"
    click TMDB "https://github.com/u-faizan/movies-recommendation/blob/main/TMDB-API/app.py"
    click TMDBCSV "https://github.com/u-faizan/movies-recommendation/blob/main/TMDB-API/imdb_movies.csv"
    click TMDBReq "https://github.com/u-faizan/movies-recommendation/blob/main/TMDB-API/requirements.txt"
    click TMDBPy "https://github.com/u-faizan/movies-recommendation/blob/main/TMDB-API/pyproject.toml"
    click TMDBEnv "https://github.com/u-faizan/movies-recommendation/blob/main/TMDB-API/.python-version"
    click TMDBLock "https://github.com/u-faizan/movies-recommendation/blob/main/TMDB-API/uv.lock"

    %% Styles
    classDef internal fill:#DDEEFF,stroke:#888,stroke-width:1px
    classDef datastore fill:#EEFFEE,stroke:#888,stroke-width:1px
    classDef external fill:#FFEEDD,stroke:#888,stroke-width:1px
```
