How ankit5641/movie-recommend-system works
1. Overall shape
- This repo is a small two-stage recommendation system: an offline data/preprocessing stage and an online Streamlit inference UI.
- The runtime app does not train a model; it consumes precomputed artifacts produced from TMDB movie data.
2. Primary runtime entrypoint
- app.py is the main application entrypoint for the deployed experience.
- The README’s local run instructions use streamlit run app.py, so this is the user-facing boundary where requests start and results are rendered.
3. Interactive UI layer
- The frontend is built with Streamlit.
- Its job is to let a user pick a movie, trigger a recommendation lookup, and display results as movie cards/posters.
4. Recommendation engine boundary
- The core ML logic is content-based filtering.
- Instead of calling a live model service, the app reads a precomputed similarity matrix from similarity.pkl and uses it to rank movies similar to the selected title.
5. Movie metadata store
- movie_dict.pkl and movies.pkl are serialized data artifacts used by the app.
- These likely hold the normalized movie catalog and lookup-friendly structures needed to map a title selection into an internal movie index and metadata for display.
6. Offline data preparation
- The raw sources are tmdb_5000_movies.csv and tmdb_5000_credits.csv.
- The notebook Movie recommender system.ipynb is the offline workspace where the CSVs were cleaned, feature-engineered, vectorized, and converted into the persisted .pkl artifacts.
7. Data flow at runtime
- User selects a movie in Streamlit.
- The app looks up that movie in the serialized movie dictionary.
- It reads the corresponding row from the similarity matrix, finds the nearest matches, and returns the top recommendations.
- For each recommended title, the app fetches poster imagery from the external TMDB service.
8. External integration
- The only clear external runtime dependency beyond Python packages is the TMDB API.
- TMDB is used for poster enrichment, not for recommendation scoring, which keeps the recommender fast and deterministic while still producing rich UI output.
9. Persistence and deployment model
- There is no database, queue, or backend service layer in this repo.
- Persistence is file-based through pickle artifacts checked into the repository, which makes the deployment simple and Streamlit-friendly.
10. Supporting scripts
- main.py is present as an additional Python entrypoint, but the README and structure indicate app.py is the canonical app path.
- If you’re drawing the architecture, treat main.py as auxiliary unless its contents show otherwise.
11. Technology stack
- Core stack: Python 3.9, Streamlit, Pandas, and Pickle serialization.
- ML is implemented as lightweight offline feature engineering plus similarity computation, rather than a model-serving framework.
12. Key architectural boundary to diagram
- The most important split is between:
- offline artifact generation from TMDB CSV data, and
- online recommendation serving from precomputed pickle files plus live TMDB poster lookup.
- That boundary is what makes the app responsive and easy to deploy on Streamlit Cloud.
Main entry points: Movie recommender system.ipynb Notebook · movies.pkl Movies data · movie_dict.pkl Movie map · similarity.pkl Similarity matrix
Components 12
Offline prep
Builds the serialized recommendation artifacts from raw TMDB data.
- Notebook · Exploratory workspace that cleans TMDB data, engineers features, and generates artifacts.
Movie recommender system.ipynb - Movies CSV · Raw TMDB movie metadata source used during offline preparation.
tmdb_5000_movies.csv - Credits CSV · Raw TMDB cast and crew source used during offline preparation.
tmdb_5000_credits.csv - Movies data · Normalized movie catalog and lookup-friendly records consumed by the app.
movies.pkl - Movie map · Dictionary-like structure for mapping titles to internal movie indices and metadata.
movie_dict.pkl - Similarity matrix · Precomputed content-similarity scores used to find nearest movie matches.
similarity.pkl
Online app
Serves interactive movie recommendations in Streamlit using precomputed artifacts.
- App entry · Primary runtime entrypoint for the deployed recommendation experience.
app.py - Movie UI · Lets users pick a movie and displays recommended titles as cards or posters.
- Recommender · Loads the movie lookup data and similarity matrix, then ranks nearest movies for the selected title.
- Poster lookup · Fetches poster imagery from TMDB for recommended titles.
- Main entry · Secondary Python entrypoint present in the repo, but not the documented deployment path.
main.py
Other components
- TMDB API · External API used only for poster enrichment at runtime.
Connections 14
- Movies CSV → Notebook: inputs · Raw movie metadata is processed in the offline notebook.
- Credits CSV → Notebook: inputs · Raw credit data is joined and transformed offline.
- Notebook → Movies data: produces · Offline preprocessing writes the normalized movie catalog.
- Notebook → Movie map: produces · Offline preprocessing writes lookup structures for title selection.
- Notebook → Similarity matrix: produces · Offline feature engineering computes the similarity matrix.
- App entry → Movie UI: renders · The Streamlit entrypoint serves the interactive interface.
- Movie UI → Recommender: triggers · User selection initiates recommendation lookup.
- Recommender → Movie map: reads · The engine resolves titles to movie indices and metadata.
- Recommender → Movies data: reads · The engine uses the catalog for recommendation display data.
- Recommender → Similarity matrix: reads · The engine ranks candidates using the precomputed similarity scores.
- Recommender → Poster lookup: enriches · Recommended titles are passed for poster enrichment.
- Poster lookup → TMDB API: calls · Poster imagery is fetched from TMDB at runtime.
- Poster lookup → Movie UI: returns · Poster URLs or images are returned for display.
- Main entry → Movie UI: alt entry · Auxiliary entrypoint that may also launch or proxy the app.