# bharath-allala/movie-recommendation architecture > Architecture diagram of the GitHub repository bharath-allala/movie-recommendation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source. - Interactive diagram: https://gitdiagram.com/bharath-allala/movie-recommendation - Repository: https://github.com/bharath-allala/movie-recommendation ## Overview #### Purpose and Entry Point This repository is a content-based movie recommendation application. The runtime entry point is the Streamlit UI in `app.py`, launched with `streamlit run app.py`. It serves recommendations from precomputed local artifacts rather than building models during user requests. #### Offline Artifact-Build Stage `build_artifacts.py` is the offline preprocessing/training boundary. It prepares the cleaned movie catalog, vectorization model, and sparse feature matrix consumed by the application: - `build_artifacts.py` - `movies_processed.pkl` - `vectorizer.pkl` This separates expensive dataset cleaning and vector creation from interactive serving. #### Movie Catalog and Feature Representation The processed catalog in `movies_processed.pkl` is the central metadata store used for search, display, and ranking. Movie content is represented from overview, genres, keywords, leading cast, and director; genres and directors receive higher weighting before Bag-of-Words generation. The fitted Scikit-learn vectorizer is persisted in `vectorizer.pkl`, allowing feature semantics to remain consistent with the stored vectors. #### Similarity Retrieval Engine `tag_vectors.npz` stores the sparse movie-feature matrix. At request time, the app finds the selected movie’s vector and performs cosine-similarity retrieval against this matrix: - `app.py` - `tag_vectors.npz` - `vectorizer.pkl` Using an `.npz` sparse artifact avoids recomputing vectors and avoids requiring the source TMDB dataset in production. #### Ranking Boundary Similarity is the candidate-generation signal; the application then applies hybrid re-ranking that incorporates weighted movie ratings. This makes content resemblance the primary retrieval mechanism while allowing stronger-rated movies to rank above otherwise comparable candidates: - `app.py` - `movies_processed.pkl` - `tag_vectors.npz` #### User Interaction and Serving Runtime `app.py` owns the Streamlit interaction flow: movie search/selection, recommendation invocation, and result rendering. The deployed system is a Python/Streamlit process with local filesystem artifacts; no database, API integration, or separate backend service is represented in the repository. #### Material Dependencies and Deployment Model The runtime depends on Python with Streamlit, Pandas, NumPy, Scikit-learn, and SciPy, declared in `requirements.txt`. The application is designed for Streamlit hosting and has a published Streamlit deployment link. Its only persistent data/model infrastructure is versioned serialized local files: - `requirements.txt` - `movies_processed.pkl` - `tag_vectors.npz` Main entry points: [`build_artifacts.py`](https://github.com/bharath-allala/movie-recommendation/blob/main/build_artifacts.py) (Artifact builder), [`app.py`](https://github.com/bharath-allala/movie-recommendation/blob/main/app.py) (Movie search and selection), [`movies_processed.pkl`](https://github.com/bharath-allala/movie-recommendation/blob/main/movies_processed.pkl) (Processed movie catalog), [`vectorizer.pkl`](https://github.com/bharath-allala/movie-recommendation/blob/main/vectorizer.pkl) (Fitted vectorizer) ## Diagram (Mermaid) ```mermaid flowchart TD subgraph group_offline["Offline artifact build"] node_builder["Artifact builder
Python preprocessing job
[build_artifacts.py]"] node_feature_model["Weighted content features
Bag-of-Words representation"] end subgraph group_artifacts["Versioned local artifacts"] node_catalog[("Processed movie catalog
serialized catalog")] node_vectorizer["Fitted vectorizer
Scikit-learn model artifact
[vectorizer.pkl]"] node_vectors[("Sparse tag vectors
sparse feature matrix
[tag_vectors.npz]")] end subgraph group_runtime["Streamlit serving runtime"] node_requirements["Python dependencies
dependency manifest
[requirements.txt]"] node_streamlit["Streamlit app
Python entry point
[app.py]"] node_selection["Movie search and selection
UI interaction
[app.py]"] node_retrieval["Cosine similarity retrieval
candidate generator
[app.py]"] node_reranking["Hybrid re-ranking
ranking stage
[app.py]"] node_rendering["Recommendation rendering
UI results
[app.py]"] end node_user(("Movie explorer
end user")) node_hosting{{"Streamlit hosting
deployment platform"}} node_builder -->|"builds"| node_feature_model node_builder -->|"writes"| node_catalog node_feature_model -->|"fits and persists"| node_vectorizer node_feature_model -->|"produces"| node_vectors node_builder -->|"writes"| node_vectorizer node_builder -->|"writes"| node_vectors node_requirements -->|"provides runtime packages"| node_streamlit node_hosting -->|"runs"| node_streamlit node_user -->|"searches and selects"| node_selection node_streamlit -->|"owns interaction"| node_selection node_selection -->|"searches metadata"| node_catalog node_selection -->|"selected movie"| node_retrieval node_vectorizer -->|"feature semantics"| node_retrieval node_vectors -->|"sparse matrix"| node_retrieval node_retrieval -->|"similarity candidates"| node_reranking node_catalog -->|"ratings and metadata"| node_reranking node_reranking -->|"ranked recommendations"| node_rendering node_rendering -->|"displays results"| node_user click node_builder "https://github.com/bharath-allala/movie-recommendation/blob/main/build_artifacts.py" click node_catalog "https://github.com/bharath-allala/movie-recommendation/blob/main/movies_processed.pkl" click node_vectorizer "https://github.com/bharath-allala/movie-recommendation/blob/main/vectorizer.pkl" click node_vectors "https://github.com/bharath-allala/movie-recommendation/blob/main/tag_vectors.npz" click node_requirements "https://github.com/bharath-allala/movie-recommendation/blob/main/requirements.txt" click node_streamlit "https://github.com/bharath-allala/movie-recommendation/blob/main/app.py" click node_selection "https://github.com/bharath-allala/movie-recommendation/blob/main/app.py" click node_retrieval "https://github.com/bharath-allala/movie-recommendation/blob/main/app.py" click node_reranking "https://github.com/bharath-allala/movie-recommendation/blob/main/app.py" click node_rendering "https://github.com/bharath-allala/movie-recommendation/blob/main/app.py" classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554 classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337 classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81 classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a class node_builder,node_feature_model toneBlue class node_catalog,node_vectorizer,node_vectors toneAmber class node_requirements,node_streamlit,node_selection,node_retrieval,node_reranking,node_rendering toneMint class node_user,node_hosting toneNeutral ``` ## Components ### Offline artifact build Precomputes the catalog and feature artifacts. - [Artifact builder](https://github.com/bharath-allala/movie-recommendation/blob/main/build_artifacts.py): Python preprocessing job · Cleans data and persists serving artifacts. · `build_artifacts.py` - **Weighted content features**: Bag-of-Words representation · Weights genres and directors above other movie metadata. ### Versioned local artifacts Files shared between build and serving. - [Processed movie catalog](https://github.com/bharath-allala/movie-recommendation/blob/main/movies_processed.pkl): serialized catalog · Metadata store for search, display, ratings, and ranking. · `movies_processed.pkl` - [Fitted vectorizer](https://github.com/bharath-allala/movie-recommendation/blob/main/vectorizer.pkl): Scikit-learn model artifact · Preserves feature semantics for stored vectors. · `vectorizer.pkl` - [Sparse tag vectors](https://github.com/bharath-allala/movie-recommendation/blob/main/tag_vectors.npz): sparse feature matrix · Precomputed movie-content vectors. · `tag_vectors.npz` ### Streamlit serving runtime Interactive recommendation process. - [Python dependencies](https://github.com/bharath-allala/movie-recommendation/blob/main/requirements.txt): dependency manifest · Declares Streamlit, Pandas, NumPy, Scikit-learn, and SciPy. · `requirements.txt` - [Streamlit app](https://github.com/bharath-allala/movie-recommendation/blob/main/app.py): Python entry point · Launched with streamlit run app.py. · `app.py` - [Movie search and selection](https://github.com/bharath-allala/movie-recommendation/blob/main/app.py): UI interaction · `app.py` - [Cosine similarity retrieval](https://github.com/bharath-allala/movie-recommendation/blob/main/app.py): candidate generator · Compares the selected movie vector with the sparse matrix. · `app.py` - [Hybrid re-ranking](https://github.com/bharath-allala/movie-recommendation/blob/main/app.py): ranking stage · Combines content similarity with weighted movie ratings. · `app.py` - [Recommendation rendering](https://github.com/bharath-allala/movie-recommendation/blob/main/app.py): UI results · `app.py` ### Other components - **Movie explorer**: end user - **Streamlit hosting**: deployment platform · Runs the Python process with local artifacts. ## Connections - Artifact builder → Weighted content features: builds - Artifact builder → Processed movie catalog: writes - Weighted content features → Fitted vectorizer: fits and persists - Weighted content features → Sparse tag vectors: produces - Artifact builder → Fitted vectorizer: writes - Artifact builder → Sparse tag vectors: writes - Python dependencies → Streamlit app: provides runtime packages - Streamlit hosting → Streamlit app: runs - Movie explorer → Movie search and selection: searches and selects - Streamlit app → Movie search and selection: owns interaction - Movie search and selection → Processed movie catalog: searches metadata - Movie search and selection → Cosine similarity retrieval: selected movie - Fitted vectorizer → Cosine similarity retrieval: feature semantics - Sparse tag vectors → Cosine similarity retrieval: sparse matrix - Cosine similarity retrieval → Hybrid re-ranking: similarity candidates - Processed movie catalog → Hybrid re-ranking: ratings and metadata - Hybrid re-ranking → Recommendation rendering: ranked recommendations - Recommendation rendering → Movie explorer: displays results