# dk-krishna2001/book-recommendation-system architecture
> Architecture diagram of the GitHub repository dk-krishna2001/book-recommendation-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-26). It is an AI-made overview: check details against the source.
- Interactive diagram: https://gitdiagram.com/dk-krishna2001/book-recommendation-system
- Repository: https://github.com/dk-krishna2001/book-recommendation-system
## Overview
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`](https://github.com/dk-krishna2001/book-recommendation-system/blob/main/app.py) (App server), [`book-recommender-system.ipynb`](https://github.com/dk-krishna2001/book-recommendation-system/blob/main/book-recommender-system.ipynb) (Prep notebook), [`pt.pkl`](https://github.com/dk-krishna2001/book-recommendation-system/blob/main/pt.pkl) (Pivot table), [`similarity_scores.pkl`](https://github.com/dk-krishna2001/book-recommendation-system/blob/main/similarity_scores.pkl) (Similarity matrix)
## Diagram (Mermaid)
```mermaid
flowchart TD
subgraph group_offline_prep["Offline prep"]
node_dataset[("Kaggle data
external dataset")]
node_notebook["Prep notebook
offline pipeline"]
node_pt["Pivot table
artifact
[pt.pkl]"]
node_similarity["Similarity matrix
artifact"]
node_popular["Popular list
artifact
[popular.pkl]"]
end
subgraph group_runtime["Runtime"]
node_server["App server
web app
[app.py]"]
node_loader["Artifact loader
runtime component"]
node_ranker["Ranker
recommendation logic"]
end
subgraph group_presentation["Presentation"]
node_index["Home page
template
[index.html]"]
node_results["Results page
template
[recommend.html]"]
end
subgraph group_deployment["Deployment"]
node_procfile["Procfile
deployment config"]
node_requirements["Requirements
dependency spec
[requirements.txt]"]
end
node_user(("User
external actor"))
node_dataset -->|"training data"| node_notebook
node_notebook -->|"exports"| node_pt
node_notebook -->|"exports"| node_similarity
node_notebook -->|"exports"| node_popular
node_procfile -->|"starts"| node_server
node_requirements -.->|"depends on"| node_server
node_server -->|"loads"| node_loader
node_loader -->|"reads"| node_pt
node_loader -->|"reads"| node_similarity
node_loader -->|"reads"| node_popular
node_user -->|"opens"| node_index
node_index -->|"submit book"| node_server
node_server -->|"computes"| node_ranker
node_ranker -->|"matches"| node_pt
node_ranker -->|"looks up"| node_similarity
node_ranker -.->|"fallback"| node_popular
node_server -->|"renders"| node_results
node_results -->|"shows results"| node_user
click node_notebook "https://github.com/dk-krishna2001/book-recommendation-system/blob/main/book-recommender-system.ipynb"
click node_pt "https://github.com/dk-krishna2001/book-recommendation-system/blob/main/pt.pkl"
click node_similarity "https://github.com/dk-krishna2001/book-recommendation-system/blob/main/similarity_scores.pkl"
click node_popular "https://github.com/dk-krishna2001/book-recommendation-system/blob/main/popular.pkl"
click node_server "https://github.com/dk-krishna2001/book-recommendation-system/blob/main/app.py"
click node_index "https://github.com/dk-krishna2001/book-recommendation-system/blob/main/templates/index.html"
click node_results "https://github.com/dk-krishna2001/book-recommendation-system/blob/main/templates/recommend.html"
click node_procfile "https://github.com/dk-krishna2001/book-recommendation-system/tree/main/Procfile"
click node_requirements "https://github.com/dk-krishna2001/book-recommendation-system/blob/main/requirements.txt"
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_dataset,node_notebook,node_pt,node_similarity,node_popular toneBlue
class node_server,node_loader,node_ranker toneAmber
class node_index,node_results toneMint
class node_procfile,node_requirements toneRose
class node_user toneNeutral
```
## Components
### Offline prep
Notebook-driven data preparation and artifact generation.
- **Kaggle data**: external dataset · Source book data used during offline preparation.
- [Prep notebook](https://github.com/dk-krishna2001/book-recommendation-system/blob/main/book-recommender-system.ipynb): offline pipeline · Builds the recommendation structures and exports pickle artifacts. · `book-recommender-system.ipynb`
- [Pivot table](https://github.com/dk-krishna2001/book-recommendation-system/blob/main/pt.pkl): artifact · Serialized book-feature table used for lookup space. · `pt.pkl`
- [Similarity matrix](https://github.com/dk-krishna2001/book-recommendation-system/blob/main/similarity_scores.pkl): artifact · Precomputed nearest-neighbor similarity scores. · `similarity_scores.pkl`
- [Popular list](https://github.com/dk-krishna2001/book-recommendation-system/blob/main/popular.pkl): artifact · Curated fallback or default recommendation set. · `popular.pkl`
### Runtime
Python web process that serves recommendations from saved artifacts.
- [App server](https://github.com/dk-krishna2001/book-recommendation-system/blob/main/app.py): web app · Loads artifacts and handles recommendation requests. · `app.py`
- **Artifact loader**: runtime component · Reads the serialized recommendation artifacts at startup.
- **Ranker**: recommendation logic · Finds similar books from the precomputed similarity structure.
### Presentation
Server-rendered HTML pages for the user flow.
- [Home page](https://github.com/dk-krishna2001/book-recommendation-system/blob/main/templates/index.html): template · Landing page for selecting or entering a book. · `templates/index.html`
- [Results page](https://github.com/dk-krishna2001/book-recommendation-system/blob/main/templates/recommend.html): template · Renders the recommendation output page. · `templates/recommend.html`
### Deployment
Process setup for running the web app.
- [Procfile](https://github.com/dk-krishna2001/book-recommendation-system/tree/main/Procfile): deployment config · Declares the process used to run the web app. · `Procfile`
- [Requirements](https://github.com/dk-krishna2001/book-recommendation-system/blob/main/requirements.txt): dependency spec · Defines the Python runtime dependencies. · `requirements.txt`
### Other components
- **User**: external actor · Selects a book and requests recommendations.
## Connections
- 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.