How dk-krishna2001/book-recommendation-system works
1. This repository is a small machine-learning web application for book recommendations. The runtime system is centered on a Python server (app.py) plus two HTML templates, with the recommendation logic backed by precomputed pickle artifacts.
2. There are two distinct phases in the repo:
- Offline model/data preparation in book-recommender-system.ipynb
- Online inference and UI serving in app.py
3. The notebook is the training/preprocessing boundary. It appears to build the recommendation data structures from the Kaggle book dataset, then serializes them into:
- pt.pkl — likely the pivot/feature table used to map books into the model space
- similarity_scores.pkl — the precomputed similarity matrix used for nearest-neighbor lookup
- popular.pkl — a curated/popularity-based book list for default or fallback recommendations
4. The online application does not train a model at request time. Instead, it loads the saved pickle artifacts and uses them for fast lookup. That makes the request path lightweight and keeps inference separate from heavy preprocessing.
5. The UI layer is template-driven:
- templates/index.html is the landing page where a user likely selects or enters a book
- templates/recommend.html renders the resulting recommendations
This is a server-rendered web flow, not a client-heavy SPA.
6. The core request flow is: user opens the home page, submits a book choice, app.py looks up similar books from the loaded artifacts, and the server returns a recommendation page populated with ranked results.
7. The recommendation engine is collaborative-filtering/KNN-oriented, based on the README. Practically, the expensive neighborhood computation is done ahead of time in the notebook, and the live app consumes the resulting similarity structure.
8. There is no indication of a database, message queue, or external recommendation API. The system is self-contained and file-backed, with the dataset and trained artifacts packaged alongside the app.
9. requirements.txt defines the Python runtime dependencies, and Procfile indicates deployment on Heroku or a similar process-based platform. That means the application is designed to be run as a single web process.
10. The repo therefore has three main architectural boundaries:
- Data/model preparation boundary: notebook + dataset
- Runtime inference boundary: app.py + pickle artifacts
- Presentation boundary: HTML templates
11. One important repo-specific note: the README mentions Streamlit, but the file structure strongly suggests a Flask-style server-rendered app because of the templates/ directory and Procfile. So an accurate diagram should show a Python web server rendering HTML pages, not a pure Streamlit app.
12. For an architecture diagram, the key external input is the Kaggle dataset used offline, the key internal assets are the pickle files, and the key output is a rendered recommendation page showing similar books to the user’s selected title.
Main entry points: app.py App server · book-recommender-system.ipynb Prep notebook · pt.pkl Pivot table · similarity_scores.pkl Similarity matrix
Components 13
Offline prep
Notebook-driven data preparation and artifact generation.
- Kaggle data · Source book data used during offline preparation.
- Prep notebook · Builds the recommendation structures and exports pickle artifacts.
book-recommender-system.ipynb - Pivot table · Serialized book-feature table used for lookup space.
pt.pkl - Similarity matrix · Precomputed nearest-neighbor similarity scores.
similarity_scores.pkl - Popular list · Curated fallback or default recommendation set.
popular.pkl
Runtime
Python web process that serves recommendations from saved artifacts.
- App server · Loads artifacts and handles recommendation requests.
app.py - Artifact loader · Reads the serialized recommendation artifacts at startup.
- Ranker · Finds similar books from the precomputed similarity structure.
Presentation
Server-rendered HTML pages for the user flow.
- Home page · Landing page for selecting or entering a book.
templates/index.html - Results page · Renders the recommendation output page.
templates/recommend.html
Deployment
Process setup for running the web app.
- Procfile · Declares the process used to run the web app.
Procfile - Requirements · Defines the Python runtime dependencies.
requirements.txt
Other components
- User · Selects a book and requests recommendations.
Connections 18
- Kaggle data → Prep notebook: training data · Offline notebook consumes the book dataset.
- Prep notebook → Pivot table: exports · Creates the pivot/feature table artifact.
- Prep notebook → Similarity matrix: exports · Creates the similarity matrix artifact.
- Prep notebook → Popular list: exports · Creates the popularity/fallback list artifact.
- Procfile → App server: starts · Deployment process launches the Python web app.
- Requirements → App server: depends on · Runtime dependencies support the application process.
- App server → Artifact loader: loads · Application startup reads the saved artifacts.
- Artifact loader → Pivot table: reads · Loads the pivot table into memory.
- Artifact loader → Similarity matrix: reads · Loads the similarity matrix into memory.
- Artifact loader → Popular list: reads · Loads the fallback recommendation list into memory.
- User → Home page: opens · User begins at the home page.
- Home page → App server: submit book · Form submission sends the chosen title to the server.
- App server → Ranker: computes · Request handling delegates to recommendation logic.
- Ranker → Pivot table: matches · Uses the book space to identify the selected title.
- Ranker → Similarity matrix: looks up · Retrieves nearest neighbors from precomputed scores.
- Ranker → Popular list: fallback · Uses popular titles when needed.
- App server → Results page: renders · Server returns the recommendation page.
- Results page → User: shows results · User sees ranked book recommendations.