# zunnu786/movie-recommender-system architecture

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

- Interactive diagram: https://gitdiagram.com/zunnu786/movie-recommender-system
- Repository: https://github.com/zunnu786/movie-recommender-system

## Overview

##### Project type and purpose
- This is a lightweight, single-page web application (full-stack at a small scale) built in Python using Streamlit.
- Its sole purpose is to let a user pick a movie from a dropdown and receive a list of similar movies via a collaborative-filtering recommender.

##### File structure
- Top level:
- README.md – documentation
- dataset.zip – raw data archive
- movies.pkl, movie_dict.pkl – precomputed data pickles (movie metadata and similarity indices)
- movie_recommer_system.ipynb – the notebook containing the Streamlit app code and recommendation logic
- No separate “backend” or “frontend” directories: Streamlit serves both the UI and the logic in one process.
- No external database or microservice folders—data is loaded directly from pickles.

##### README for additional insights
- Frameworks: Python 3, Streamlit, Pandas
- Execution: “streamlit run app.py” (though code is in the notebook)
- Algorithm: collaborative filtering based on movie features to compute pairwise similarity scores.

##### Main components
a. User Interface (Browser / Streamlit frontend)
b. Streamlit Application Server (Python runtime)
- UI Renderer (Streamlit widgets, dropdown, button)
- Controller (handles user events)
- Recommendation Engine
– Data Loader (loads movies.pkl & movie_dict.pkl)
– Similarity Calculator (collaborative filtering logic)
c. Data Layer
- Pickle Store (movies.pkl, movie_dict.pkl)
- (Optionally) dataset.zip as the raw data source
d. External Dependencies (shown as libraries)
- Streamlit
- Pandas
- Python Interpreter

##### Relationships and interactions
1. User selects a movie in the browser →
2. Streamlit frontend sends an event to the Application Server →
3. Controller calls Data Loader if pickles aren’t cached →
4. Similarity Calculator queries the in-memory data structures →
5. Engine returns a ranked list of movies →
6. UI Renderer displays recommendations back to the browser

##### Architectural patterns & design principles
- Single-process MVC style:
- Model = pickled data + data-loading module
- View = Streamlit widgets & page layout
- Controller = event handlers wiring UI to the recommendation logic
- In-memory caching of pickles on first load for performance
- Clear separation of concerns: UI vs. data vs. algorithm

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface
    UI["Browser"]:::ui
    UI -->|"select movie_id"| Controller

    %% Streamlit Application Server
    subgraph "Streamlit Application Server"
        Renderer["Streamlit Widgets (UI Renderer)"]:::logic
        Controller["Event Handlers (Controller)"]:::logic
        subgraph "Recommendation Engine"
            DataLoader["Data Loader"]:::logic
            Similarity["Similarity Calculator"]:::logic
        end
    end

    Controller -->|"invoke render"| Renderer
    Controller -->|"request recommendation(movie_id)"| Similarity
    Similarity -->|"lookup in-memory data"| DataLoader
    Similarity -->|"return list_of_titles"| Controller
    Controller -->|"render results"| Renderer
    Renderer -->|"display list_of_titles"| UI

    %% Data Layer
    subgraph "Data Layer"
        MoviesP["movies.pkl"]:::data
        DictP["movie_dict.pkl"]:::data
        RawData["dataset.zip"]:::data
    end

    DataLoader -->|"load pickles"| MoviesP
    DataLoader -->|"load pickles"| DictP
    DataLoader -->|"initial raw load"| RawData

    %% External Dependencies
    subgraph "External Libraries"
        StreamlitLib["Streamlit"]:::ext
        PandasLib["Pandas"]:::ext
        PythonLib["Python Interpreter"]:::ext
    end

    Controller -.->|uses| StreamlitLib
    DataLoader -.->|uses| PandasLib
    Renderer -.->|runs on| PythonLib

    %% Documentation
    Doc["README.md"]:::doc

    %% Click Events
    click UI "https://github.com/zunnu786/movie-recommender-system/blob/main/movie_recommer_system.ipynb"
    click Renderer "https://github.com/zunnu786/movie-recommender-system/blob/main/movie_recommer_system.ipynb"
    click Controller "https://github.com/zunnu786/movie-recommender-system/blob/main/movie_recommer_system.ipynb"
    click DataLoader "https://github.com/zunnu786/movie-recommender-system/blob/main/movie_recommer_system.ipynb"
    click Similarity "https://github.com/zunnu786/movie-recommender-system/blob/main/movie_recommer_system.ipynb"
    click MoviesP "https://github.com/zunnu786/movie-recommender-system/blob/main/movies.pkl"
    click DictP "https://github.com/zunnu786/movie-recommender-system/blob/main/movie_dict.pkl"
    click RawData "https://github.com/zunnu786/movie-recommender-system/blob/main/dataset.zip"
    click Doc "https://github.com/zunnu786/movie-recommender-system/blob/main/README.md"

    %% Styles
    classDef ui fill:#BBDEFB,stroke:#1E88E5
    classDef logic fill:#C8E6C9,stroke:#388E3C
    classDef data fill:#FFF9C4,stroke:#FBC02D
    classDef ext fill:#E0E0E0,stroke:#757575
    classDef doc fill:#FFE0B2,stroke:#FB8C00
```
