# prashant3420/movie-recommendation-system architecture

> Architecture diagram of the GitHub repository prashant3420/movie-recommendation-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prashant3420/movie-recommendation-system
- Repository: https://github.com/prashant3420/movie-recommendation-system

## Overview

##### What this project is (type + purpose)
This repository is a **small Python-based web app** that serves a **movie recommendation system**. The presence of:
- `app.py` (single entrypoint)
- `requirements.txt` (Python dependencies)
- `Procfile`, `setup.sh` (typical Heroku-style deployment artifacts)
- `movies.pkl`, `movie_dict.pkl` (precomputed model/data artifacts)
- `tmdb_5000_movies.csv`, `Untitled1.ipynb` (offline dataset + notebook used to build/preprocess artifacts)

…strongly suggests a **two-phase architecture**:

##### How to read the file structure architecturally
Files to architectural responsibilities:

##### Runtime / serving
- `app.py`
The **application server** (likely a Streamlit/Flask-style UI + recommendation logic).
- `requirements.txt`
- `Procfile`, `setup.sh`
**Deployment/runtime wiring** (Heroku dyno start command, environment setup).

##### Model/data artifacts used at runtime
- `movies.pkl`, `movie_dict.pkl`
Treated as the “model”/“index”/“feature store” equivalent in a lightweight app. These are core runtime dependencies.

##### Offline build inputs
- `tmdb_5000_movies.csv`
Source dataset.
- `Untitled1.ipynb`
Offline pipeline to transform CSV into the `.pkl` artifacts.

##### What to put
For best accuracy, separate into **containers** (deployable/runtime units) and **data artifacts**.

##### Web App Container (Heroku Dyno)
- Process started via `Procfile`
- Code: `app.py`
- Dependencies: `requirements.txt`
##### Recommendation Engine (in-process module inside app.py)
- Loads pickles into memory
- Computes similarity / ranking
##### Local Data Artifacts (bundled with app)
- `movies.pkl`
- `movie_dict.pkl`

*(Optional but common in movie recommenders: if `app.py` calls external APIs for posters/metadata, add it explicitly—see section 5.)*

##### Data Source (CSV)
- `tmdb_5000_movies.csv`
##### Feature/Model Build Notebook
- `Untitled1.ipynb`
##### Generated Artifacts
- output: `movies.pkl`, `movie_dict.pkl`
##### Artifact Packaging
- committed to repo / included in deploy slug

This gives a complete picture: “Where do recommendations come from?” and “What does production depend on?”

##### Browser → Web App
- user inputs: selected movie / query
##### Web App → Recommendation Engine (inside same process)
- call: `get_recommendations(movie_id/title)`
##### Recommendation Engine → Pickle Artifacts
- loads/reads: `movies.pkl`, `movie_dict.pkl`
##### Recommendation Engine → Web App
- returns: list of recommended movie titles/ids (and maybe posters)
##### Web App → Browser
- renders recommendations UI

##### “Don’t overthink it”: maximize component separation for clarity
- **UI Layer** (input/output rendering)
- **Recommendation Logic** (similarity/ranking)
- **Artifact Loader / Data Access** (reads pkl)
- **(Optional) External Metadata Client** (TMDB API client)

This is the best way to capture “essential architectural elements” in a small repo without inventing services that don’t exist.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =============== Global Actors / Platform ===============
    User["User (Browser)"]:::actor
    Heroku(("Heroku Platform")):::platform

    %% =============== Online Serving (Runtime) ===============
    subgraph "Online Serving (Production Runtime)"
        WebApp["Web App Container (Python)"]:::service
        ProcfileNode["Dyno Start Command (Procfile)"]:::config
        SetupNode["Runtime Setup (setup.sh)"]:::config
        ReqNode["Python Dependencies (requirements.txt)"]:::config

        subgraph "In-Process Modules (app.py)"
            UI["UI Layer (Input/Render)"]:::module
            RecEngine["Recommendation Engine (Similarity/Ranking)"]:::module
            Loader["Artifact Loader / Data Access"]:::module
        end

        MoviesPKL[("movies.pkl (Precomputed Index/Features)")]:::data
        MovieDictPKL[("movie_dict.pkl (Movie Metadata Dict)")]:::data
    end

    %% =============== Offline Preparation (Build/Precompute) ===============
    subgraph "Offline Preparation (Precompute Artifacts)"
        CSV[("tmdb_5000_movies.csv (Source Dataset)")]:::data
        Notebook["Untitled1.ipynb (Feature/Model Build Notebook)"]:::offline
        GenMoviesPKL[("movies.pkl (Generated Artifact)")]:::data
        GenMovieDictPKL[("movie_dict.pkl (Generated Artifact)")]:::data
        Package["Commit/Package Artifacts into Deployable App"]:::offline
    end

    %% =============== Optional External Dependency (Not Confirmed) ===============
    subgraph "External Services (Optional)"
        TMDB["TMDB API (Posters/Metadata)"]:::external
        TMDBNote["Included only if app.py calls TMDB endpoints"]:::note
    end

    %% =============== Runtime Request Flow (Solid) ===============
    User -->|"select_movie/query"| Heroku
    Heroku -->|"routes_request"| WebApp

    WebApp -->|"render_ui()"| UI
    UI -->|"get_recommendations(title/id)"| RecEngine
    RecEngine -->|"read/load_pickles"| Loader
    Loader -->|"load_embeddings/index"| MoviesPKL
    Loader -->|"load_metadata"| MovieDictPKL
    RecEngine -->|"return_ranked_list"| UI
    UI -->|"render_results"| WebApp
    WebApp -->|"html/ui_response"| Heroku
    Heroku -->|"display_results"| User

    %% Optional external call (dotted to emphasize conditional)
    WebApp -.->|"fetch_posters(optional)"| TMDB
    TMDB -.->|"poster_urls/metadata"| WebApp
    TMDBNote -.-> TMDB

    %% =============== Offline Build Flow (Dashed) ===============
    CSV -.->|"ingest/clean/transform"| Notebook
    Notebook -.->|"generate_artifacts"| GenMoviesPKL
    Notebook -.->|"generate_artifacts"| GenMovieDictPKL
    GenMoviesPKL -.->|"package"| Package
    GenMovieDictPKL -.->|"package"| Package
    Package -.->|"bundled_in_slug"| MoviesPKL
    Package -.->|"bundled_in_slug"| MovieDictPKL

    %% =============== Deployment Wiring / Dependency Boundary ===============
    ProcfileNode -->|"starts"| WebApp
    SetupNode -->|"configures_env"| WebApp
    ReqNode -->|"installs_libs_for"| WebApp

    %% =============== Click Events (Component Mapping) ===============
    click WebApp "https://github.com/prashant3420/movie-recommendation-system/blob/main/app.py"
    click UI "https://github.com/prashant3420/movie-recommendation-system/blob/main/app.py"
    click RecEngine "https://github.com/prashant3420/movie-recommendation-system/blob/main/app.py"
    click Loader "https://github.com/prashant3420/movie-recommendation-system/blob/main/app.py"
    click ProcfileNode "https://github.com/prashant3420/movie-recommendation-system/tree/main/Procfile"
    click SetupNode "https://github.com/prashant3420/movie-recommendation-system/blob/main/setup.sh"
    click ReqNode "https://github.com/prashant3420/movie-recommendation-system/blob/main/requirements.txt"
    click MoviesPKL "https://github.com/prashant3420/movie-recommendation-system/blob/main/movies.pkl"
    click MovieDictPKL "https://github.com/prashant3420/movie-recommendation-system/blob/main/movie_dict.pkl"
    click Notebook "https://github.com/prashant3420/movie-recommendation-system/blob/main/Untitled1.ipynb"
    click CSV "https://github.com/prashant3420/movie-recommendation-system/blob/main/tmdb_5000_movies.csv"
    click GenMoviesPKL "https://github.com/prashant3420/movie-recommendation-system/blob/main/movies.pkl"
    click GenMovieDictPKL "https://github.com/prashant3420/movie-recommendation-system/blob/main/movie_dict.pkl"

    %% =============== Styles ===============
    classDef actor fill:#E3F2FD,stroke:#1565C0,stroke-width:2px,color:#0D47A1
    classDef platform fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px,color:#1B5E20
    classDef service fill:#FFF3E0,stroke:#EF6C00,stroke-width:2px,color:#E65100
    classDef module fill:#FFF8E1,stroke:#F9A825,stroke-width:2px,color:#7A5A00
    classDef data fill:#F3E5F5,stroke:#6A1B9A,stroke-width:2px,color:#4A148C
    classDef offline fill:#E0F2F1,stroke:#00796B,stroke-width:2px,color:#004D40
    classDef external fill:#FFEBEE,stroke:#C62828,stroke-width:2px,color:#B71C1C
    classDef config fill:#ECEFF1,stroke:#546E7A,stroke-width:2px,color:#263238
    classDef note fill:#FFFFFF,stroke:#9E9E9E,stroke-width:1px,color:#424242,stroke-dasharray: 4 4
```
