# duckduck-05/movie_recommendation architecture

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

- Interactive diagram: https://gitdiagram.com/duckduck-05/movie_recommendation
- Repository: https://github.com/duckduck-05/movie_recommendation

## Overview

##### Project Type and Purpose
- This is a full-stack, ML-driven movie recommendation application.
- Purpose: ingest movie rating data, train/serve recommendation models (collaborative and content‐based), and expose results via a Streamlit UI.

##### File Structure
- data/ml-100k/ : raw user‐movie ratings dataset
- model/ : serialized model parameters (w&b_cb.npz)
- notebooks/ : experimental Jupyter notebooks for data analysis, model training, evaluation
- src/lib/ : core business‐logic modules (collaborative_filtering.py, matrix_factorization.py, get_items_rated.py, evaluate.py)
- src/web.py : Streamlit application entry point
- requirements.txt : Python dependencies

##### Main Components
A. Data Layer
- Raw data files in data/ml-100k/
- (Optionally) External movie metadata API (mentioned in README but not implemented here)
B. Model Layer
- Notebook pipelines for training (Jupyter)
- Trained model artifact (model/w&b_cb.npz)
C. Business Logic Layer
- src/lib modules that implement algorithms:
– Collaborative filtering
– Matrix factorization
– Content‐based methods
– Evaluation & utility functions
D. Presentation Layer
- Streamlit UI (src/web.py)
- User browser → Streamlit server

##### Relationships and Data Flows
1. Data Ingestion: src/lib modules load raw data from data/ml-100k/
2. Model Training (offline/notebooks):
– Notebooks read data → train models → serialize parameters to model/w&b_cb.npz
3. Serving (online):
– On UI startup, web.py loads model/w&b_cb.npz via lib modules
– User inputs (e.g., user ID or ratings) in browser → HTTP calls to Streamlit UI
– Streamlit calls lib.get_items_rated, lib.collaborative_filtering, etc., to compute recommendations
– Recommendations returned to web.py → displayed in browser

##### Architectural Patterns & Principles
- Layered architecture: clear separation of data, model, logic, and UI
- Single‐page application (Streamlit) for rapid prototyping
- Modular design: each algorithm in its own module (supports extensibility and testing)
- Offline training vs. online inference stages

##### Final Checklist
- Components: Data files, Notebooks (training), Model artifact, lib modules, Streamlit server, Browser UI
- Labels: component names, file paths (optional), operation names
- Level of detail: capture all src/lib modules and their interaction with data/model

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        Data[(Raw Movie Ratings\ndata/ml-100k/)]:::data
    end

    %% Notebook Training (Offline)
    subgraph "Notebook Training (Offline)"
        NA["data_analysis.ipynb"]:::notebook
        NC["collaborative_filtering.ipynb"]:::notebook
        NB["content_based.ipynb"]:::notebook
        NGD["Matrix_Fractorization_using_GD.ipynb"]:::notebook
        NSVD["matrix-factorization-SVD.ipynb"]:::notebook
        NEval["evaluate.py"]:::notebook
        NGet["get_items_rated.py"]:::notebook
    end

    %% Model Layer
    subgraph "Model Layer"
        MA[(Model Artifact\nmodel/w&b_cb.npz)]:::model
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        BL1["collaborative_filtering.py"]:::logic
        BL2["matrix_factorization.py"]:::logic
        BL3["get_items_rated.py"]:::logic
        BL4["evaluate.py"]:::logic
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        Browser["Browser UI"]:::ui
        Stream["Streamlit Server\nsrc/web.py"]:::ui
    end

    %% Dependencies
    Req["requirements.txt"]:::data

    %% Training Flow
    Data -->|"load data"| NA
    Data -->|"load data"| NC
    Data -->|"load data"| NB
    Data -->|"load data"| NGD
    Data -->|"load data"| NSVD
    NA -->|"train model"| MA
    NC -->|"train model"| MA
    NB -->|"train model"| MA
    NGD -->|"train model"| MA
    NSVD -->|"train model"| MA

    %% Inference Flow
    Browser -->|"HTTP request"| Stream
    Stream -->|"load model"| BL1
    Stream -->|"load model"| BL2
    Stream -->|"load model"| BL3
    Stream -->|"load model"| BL4
    BL1 -->|"read parameters"| MA
    BL2 -->|"read parameters"| MA
    BL3 -->|"load data"| Data
    BL3 -->|"read parameters"| MA
    BL1 -->|"compute recommendations"| Stream
    BL2 -->|"compute recommendations"| Stream
    BL3 -->|"compute recommendations"| Stream
    BL4 -->|"evaluate utils"| Stream
    Stream -->|"render UI"| Browser
    Stream -->|"dependencies"| Req

    %% Click Events
    click Data "https://github.com/duckduck-05/movie_recommendation/tree/main/data/ml-100k/"
    click MA "https://github.com/duckduck-05/movie_recommendation/blob/main/model/w&b_cb.npz"
    click NA "https://github.com/duckduck-05/movie_recommendation/blob/main/notebooks/data_analysis.ipynb"
    click NC "https://github.com/duckduck-05/movie_recommendation/blob/main/notebooks/collaborative_filtering.ipynb"
    click NB "https://github.com/duckduck-05/movie_recommendation/blob/main/notebooks/content_based.ipynb"
    click NGD "https://github.com/duckduck-05/movie_recommendation/blob/main/notebooks/Matrix_Fractorization_using_GD.ipynb"
    click NSVD "https://github.com/duckduck-05/movie_recommendation/blob/main/notebooks/matrix-factorization-SVD.ipynb"
    click NEval "https://github.com/duckduck-05/movie_recommendation/blob/main/notebooks/evaluate.py"
    click NGet "https://github.com/duckduck-05/movie_recommendation/blob/main/notebooks/get_items_rated.py"
    click BL1 "https://github.com/duckduck-05/movie_recommendation/blob/main/src/lib/collaborative_filtering.py"
    click BL2 "https://github.com/duckduck-05/movie_recommendation/blob/main/src/lib/matrix_factorization.py"
    click BL3 "https://github.com/duckduck-05/movie_recommendation/blob/main/src/lib/get_items_rated.py"
    click BL4 "https://github.com/duckduck-05/movie_recommendation/blob/main/src/lib/evaluate.py"
    click Stream "https://github.com/duckduck-05/movie_recommendation/blob/main/src/web.py"
    click Req "https://github.com/duckduck-05/movie_recommendation/blob/main/requirements.txt"

    %% Styles
    classDef data fill:#FFA500,stroke:#333;
    classDef model fill:#FFFF99,stroke:#333;
    classDef logic fill:#9f6,stroke:#333;
    classDef notebook fill:#add8e6,stroke:#333;
    classDef ui fill:#87CEFA,stroke:#333;
```
