# somaiyassine/book-recommender- architecture

> Architecture diagram of the GitHub repository somaiyassine/book-recommender-, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/somaiyassine/book-recommender-
- Repository: https://github.com/somaiyassine/book-recommender-

## Overview

Semantic Book Recommender is a local book-discovery application. Its documented workflow cleans book metadata, prepares searchable descriptions, adds category and emotion annotations, then serves semantic recommendations through a Gradio interface. The dashboard retrieves candidates by vector similarity, maps ISBNs to book records, applies optional category filtering and tone sorting, and displays covers and captions. Notebook internals are not sampled; their stages and data handoffs are represented from the README, while dashboard interactions are grounded in the excerpted Python source.

Main entry points: [`gradio-dashboard.py`](https://github.com/somaiyassine/book-recommender-/blob/main/gradio-dashboard.py) (Gradio dashboard), [`vector-search.ipynb`](https://github.com/somaiyassine/book-recommender-/blob/main/vector-search.ipynb) (Vector index), [`books_cleaned.csv`](https://github.com/somaiyassine/book-recommender-/blob/main/books_cleaned.csv) (Cleaned books), [`tagged_description.txt`](https://github.com/somaiyassine/book-recommender-/blob/main/tagged_description.txt) (Tagged descriptions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Data preparation"]
  node_cleaning["Metadata cleaning"]
  node_rawdata["Kaggle books"]
  node_cleaned["Cleaned books<br/>[books_cleaned.csv]"]
end

subgraph group_enrichment["Book enrichment"]
  node_categorize["Category classification"]
  node_categories["Categorized books"]
  node_emotions["Emotion scoring"]
  node_enriched["Emotion-scored books"]
end

subgraph group_search["Semantic search"]
  node_tagging["ISBN descriptions"]
  node_tagged["Tagged descriptions"]
  node_embedding["Text embeddings"]
  node_vectordb[("Vector index")]
end

subgraph group_app["Recommendation app"]
  node_dashboard["Gradio dashboard"]
  node_recommend["Recommendation handler"]
  node_format["Gallery formatting"]
  node_gallery["Book gallery"]
end

node_reader(("Book seeker"))

node_rawdata -->|"downloads dataset"| node_cleaning
node_cleaning -->|"writes cleaned data"| node_cleaned
node_cleaned -->|"provides descriptions"| node_tagging
node_tagging -->|"writes ISBN text"| node_tagged
node_tagged -->|"embeds descriptions"| node_embedding
node_embedding -->|"indexes vectors"| node_vectordb
node_cleaned -->|"classifies books"| node_categorize
node_categorize -->|"writes categories"| node_categories
node_categories -->|"scores descriptions"| node_emotions
node_emotions -->|"writes emotion scores"| node_enriched
node_reader -->|"enters query"| node_dashboard
node_dashboard -->|"dispatches inputs"| node_recommend
node_dashboard -->|"loads book records"| node_enriched
node_dashboard -->|"loads descriptions"| node_tagged
node_dashboard -->|"configures model"| node_embedding
node_dashboard -->|"opens or builds index"| node_vectordb
node_recommend -->|"searches similar books"| node_vectordb
node_vectordb -->|"returns matches"| node_recommend
node_recommend -->|"maps ISBNs and filters"| node_enriched
node_recommend -->|"passes recommendations"| node_format
node_format -->|"formats cover captions"| node_gallery
node_gallery -->|"displays results"| node_reader

click node_cleaning "https://github.com/somaiyassine/book-recommender-/blob/main/data-exploration.ipynb"
click node_cleaned "https://github.com/somaiyassine/book-recommender-/blob/main/books_cleaned.csv"
click node_tagging "https://github.com/somaiyassine/book-recommender-/blob/main/vector-search.ipynb"
click node_tagged "https://github.com/somaiyassine/book-recommender-/blob/main/tagged_description.txt"
click node_embedding "https://github.com/somaiyassine/book-recommender-/blob/main/vector-search.ipynb"
click node_vectordb "https://github.com/somaiyassine/book-recommender-/blob/main/vector-search.ipynb"
click node_categorize "https://github.com/somaiyassine/book-recommender-/blob/main/text-classification.ipynb"
click node_categories "https://github.com/somaiyassine/book-recommender-/blob/main/books_with_categories.csv"
click node_emotions "https://github.com/somaiyassine/book-recommender-/blob/main/sentiment-analysis.ipynb"
click node_enriched "https://github.com/somaiyassine/book-recommender-/blob/main/books_with_emotions.csv"
click node_dashboard "https://github.com/somaiyassine/book-recommender-/blob/main/gradio-dashboard.py"
click node_recommend "https://github.com/somaiyassine/book-recommender-/blob/main/gradio-dashboard.py"
click node_format "https://github.com/somaiyassine/book-recommender-/blob/main/gradio-dashboard.py"
click node_gallery "https://github.com/somaiyassine/book-recommender-/blob/main/gradio-dashboard.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_cleaning,node_rawdata,node_cleaned toneBlue
class node_categorize,node_categories,node_emotions,node_enriched toneAmber
class node_tagging,node_tagged,node_embedding,node_vectordb toneMint
class node_dashboard,node_recommend,node_format,node_gallery toneRose
class node_reader toneIndigo
```

## Components

### Data preparation

- [Metadata cleaning](https://github.com/somaiyassine/book-recommender-/blob/main/data-exploration.ipynb): `data-exploration.ipynb`
- **Kaggle books**
- [Cleaned books](https://github.com/somaiyassine/book-recommender-/blob/main/books_cleaned.csv): `books_cleaned.csv`

### Book enrichment

- [Category classification](https://github.com/somaiyassine/book-recommender-/blob/main/text-classification.ipynb): `text-classification.ipynb`
- [Categorized books](https://github.com/somaiyassine/book-recommender-/blob/main/books_with_categories.csv): `books_with_categories.csv`
- [Emotion scoring](https://github.com/somaiyassine/book-recommender-/blob/main/sentiment-analysis.ipynb): `sentiment-analysis.ipynb`
- [Emotion-scored books](https://github.com/somaiyassine/book-recommender-/blob/main/books_with_emotions.csv): `books_with_emotions.csv`

### Semantic search

- [ISBN descriptions](https://github.com/somaiyassine/book-recommender-/blob/main/vector-search.ipynb): `vector-search.ipynb`
- [Tagged descriptions](https://github.com/somaiyassine/book-recommender-/blob/main/tagged_description.txt): `tagged_description.txt`
- [Text embeddings](https://github.com/somaiyassine/book-recommender-/blob/main/vector-search.ipynb): `vector-search.ipynb`
- [Vector index](https://github.com/somaiyassine/book-recommender-/blob/main/vector-search.ipynb): `vector-search.ipynb`

### Recommendation app

- [Gradio dashboard](https://github.com/somaiyassine/book-recommender-/blob/main/gradio-dashboard.py): `gradio-dashboard.py`
- [Recommendation handler](https://github.com/somaiyassine/book-recommender-/blob/main/gradio-dashboard.py): `gradio-dashboard.py`
- [Gallery formatting](https://github.com/somaiyassine/book-recommender-/blob/main/gradio-dashboard.py): `gradio-dashboard.py`
- [Book gallery](https://github.com/somaiyassine/book-recommender-/blob/main/gradio-dashboard.py): `gradio-dashboard.py`

### Other components

- **Book seeker**

## Connections

- Kaggle books → Metadata cleaning: downloads dataset (evidence: `README.md`)
- Metadata cleaning → Cleaned books: writes cleaned data (evidence: `README.md`)
- Cleaned books → ISBN descriptions: provides descriptions (evidence: `README.md`)
- ISBN descriptions → Tagged descriptions: writes ISBN text (evidence: `README.md`)
- Tagged descriptions → Text embeddings: embeds descriptions (evidence: `README.md`)
- Text embeddings → Vector index: indexes vectors (evidence: `README.md`)
- Cleaned books → Category classification: classifies books (evidence: `README.md`)
- Category classification → Categorized books: writes categories (evidence: `README.md`)
- Categorized books → Emotion scoring: scores descriptions (evidence: `README.md`)
- Emotion scoring → Emotion-scored books: writes emotion scores (evidence: `README.md`)
- Book seeker → Gradio dashboard: enters query (evidence: `gradio-dashboard.py`)
- Gradio dashboard → Recommendation handler: dispatches inputs (evidence: `gradio-dashboard.py`)
- Gradio dashboard → Emotion-scored books: loads book records (evidence: `gradio-dashboard.py`)
- Gradio dashboard → Tagged descriptions: loads descriptions (evidence: `gradio-dashboard.py`)
- Gradio dashboard → Text embeddings: configures model (evidence: `gradio-dashboard.py`)
- Gradio dashboard → Vector index: opens or builds index (evidence: `gradio-dashboard.py`)
- Recommendation handler → Vector index: searches similar books (evidence: `gradio-dashboard.py`)
- Vector index → Recommendation handler: returns matches (evidence: `gradio-dashboard.py`)
- Recommendation handler → Emotion-scored books: maps ISBNs and filters (evidence: `gradio-dashboard.py`)
- Recommendation handler → Gallery formatting: passes recommendations (evidence: `gradio-dashboard.py`)
- Gallery formatting → Book gallery: formats cover captions (evidence: `gradio-dashboard.py`)
- Book gallery → Book seeker: displays results (evidence: `gradio-dashboard.py`)
