# swuzz123/book-recommendation architecture

> Architecture diagram of the GitHub repository swuzz123/book-recommendation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/swuzz123/book-recommendation
- Repository: https://github.com/swuzz123/book-recommendation

## Overview

##### Project Type and Purpose
- This is a full‐stack, explainable book recommendation system powered by large language models (LLMs), semantic embeddings, zero‐shot classification, and emotion detection.
- Users interact via a Gradio dashboard; behind the scenes, the app ingests book metadata, transforms and indexes it, and exposes an API to answer natural‐language queries and return personalized book suggestions.

##### File‐Structure Analysis
- Root
- .gitignore, README.md, requirements.txt, .env (runtime configuration for HF_TOKEN)
- app/
- gradio-dashboard.py → entry point for the interactive UI and orchestrator of backend functions
- demo/
- demo_app.mp4, UI_demo.png, demo GIF → screenshots/videos for documentation
- src/
- Jupyter notebooks for each pipeline stage:
– data‐exploration.ipynb (cleaning & feature engineering → books_cleaned.csv)
– vector‐search.ipynb (Hugging Face embeddings + ChromaDB storage)
– text‐classification.ipynb (zero‐shot genre classification → books_with_categories.csv)
– sentiment‐analysis.ipynb (emotion detection → books_with_emotions.csv)
– tagged_description.txt (preprocessed text snippets)

##### README Insights
- Four major processing stages: data cleaning, semantic embedding & retrieval, genre classification, emotion analysis
- Core technologies: Python 3.10+, Hugging Face transformers + embeddings, LangChain, ChromaDB, Gradio
- External dependency: Hugging Face API (authenticated via HF_TOKEN)
- Final user interface: a Gradio web app that ties all processing modules together

a. Main Components
- User Interface (Gradio Dashboard)
- Orchestrator / API Layer (app/gradio-dashboard.py)
- Data Processing Modules:
– Embedding Service (sentence-transformers + LangChain splitter)
– Vector Store (ChromaDB)
– Genre Classification Service (zero-shot bart-large-mnli)
– Emotion Detection Service (fine-tuned RoBERTa)
- Data Stores:
– Cleaned CSVs (books_cleaned.csv, books_with_categories.csv, books_with_emotions.csv)
– Chroma vector database
- External Services:
– Hugging Face model hub
– (Optionally) source Kaggle dataset

b. Relationships & Data Flow
1. User submits natural-language query via Gradio UI
2. Orchestrator retrieves relevant embeddings from ChromaDB
3. Maps vectors to book metadata (CSV storage)
4. Calls zero-shot classification to label genre
5. Calls emotion-detection to score tone
6. Aggregates results and returns ranked recommendations to UI

c. Architectural Patterns
- Modular pipeline structure (separate concerns for embedding, classification, emotion)
- Service‐oriented approach within a monolith (each “service” can be refactored to microservice)
- Vector-search as a specialized data layer
- Layered pattern: Presentation (UI) → Application (orchestrator) → Domain services → Persistence

d. Key Technologies & Libraries
- Python + Gradio for UI & orchestration
- Hugging Face Transformers for LLM tasks
- sentence-transformers + LangChain for text splitting and embedding
- ChromaDB for vector storage & retrieval
- pandas/CSV for tabular metadata storage

## Diagram (Mermaid)

```mermaid
graph TD
    UI["Gradio Dashboard / Orchestrator"]:::ui

    subgraph "Data Processing Modules"
        DC["Data Cleaning Module"]:::compute
        ES["Embedding Service"]:::compute
        GC["Genre Classification Service"]:::compute
        ED["Emotion Detection Service"]:::compute
    end

    subgraph "Data Stores"
        CleanCSV["books_cleaned.csv"]:::datastore
        CatCSV["books_with_categories.csv"]:::datastore
        EmoCSV["books_with_emotions.csv"]:::datastore
        VecDB["ChromaDB Vector Store"]:::datastore
        PreTxt["Preprocessed Text Snippets"]:::datastore
    end

    subgraph "External Services"
        HF["Hugging Face Model Hub"]:::external
        Kaggle["Kaggle Dataset"]:::external
    end

    subgraph "Configuration & Docs"
        Req["requirements.txt"]:::external
        Env[".env (HF_TOKEN)"]:::external
        Readme["README.md"]:::external
        Demo["Demo Assets"]:::external
    end

    DC -->|"produces cleaned CSV"| CleanCSV
    CleanCSV --> ES
    DC -->|"preprocesses snippets"| PreTxt
    PreTxt --> ES
    ES -->|"stores vectors"| VecDB
    UI -->|"1. submit query"| ES
    ES -->|"2. vector retrieval"| VecDB
    VecDB -->|"3. return vectors"| UI
    UI -->|"4. classify genre"| GC
    GC -->|"5. genre labels"| UI
    UI -->|"6. detect emotion"| ED
    ED -->|"7. emotion scores"| UI
    UI -->|"8. aggregate & respond"| UI

    ES -->|"HTTP calls"| HF
    GC -->|"HTTP calls"| HF
    ED -->|"HTTP calls"| HF
    DC -->|"ingests data"| Kaggle

    UI -.-> Env
    DC -.-> Req
    ES -.-> Req
    GC -.-> Req
    ED -.-> Req

    click UI "https://github.com/swuzz123/book-recommendation/blob/master/app/gradio-dashboard.py"
    click DC "https://github.com/swuzz123/book-recommendation/blob/master/src/data-exploration.ipynb"
    click ES "https://github.com/swuzz123/book-recommendation/blob/master/src/vector-search.ipynb"
    click GC "https://github.com/swuzz123/book-recommendation/blob/master/src/text-classification.ipynb"
    click ED "https://github.com/swuzz123/book-recommendation/blob/master/src/sentiment-analysis.ipynb"
    click PreTxt "https://github.com/swuzz123/book-recommendation/blob/master/src/tagged_description.txt"
    click Req "https://github.com/swuzz123/book-recommendation/blob/master/requirements.txt"
    click Env "https://github.com/swuzz123/book-recommendation/blob/master/.env"
    click Readme "https://github.com/swuzz123/book-recommendation/blob/master/README.md"
    click Demo "https://github.com/swuzz123/book-recommendation/blob/master/demo/demo_app.mp4"

    classDef ui fill:#E0F7FA,stroke:#006064
    classDef compute fill:#E8F5E9,stroke:#1B5E20
    classDef datastore fill:#FFF9C4,stroke:#F57F17
    classDef external fill:#FFF3E0,stroke:#E65100,stroke-dasharray: 5 5
```
