# juctxy/book-recommendation architecture

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

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

## Overview

This repository is a Gradio novel-recommendation app. A user submits a text query, optional categories, and a language; the app filters and ranks books, then displays recommendation cards. The app also offers popular-book defaults and book details, and loads book data and illustrations from remote sources. The graph reflects only relationships visible in the app.py excerpts; image lookup and some recommendation internals are not fully shown, so uncertain links are omitted.

Main entry points: [`app.py`](https://github.com/juctxy/book-recommendation/blob/main/app.py) (Recommendation handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_gradio["Gradio controls<br/>[app.py]"]
  node_submit["Query events<br/>[app.py]"]
  node_cards["Result cards<br/>[app.py]"]
end

subgraph group_recommendation["Recommendation"]
  node_recommend["Recommendation handler<br/>[app.py]"]
  node_category_filter["Category filter<br/>[app.py]"]
  node_encoder["Query encoder<br/>[app.py]"]
  node_similarity["Similarity ranking<br/>[app.py]"]
  node_popular["Popular defaults<br/>[app.py]"]
end

subgraph group_content["Book content"]
  node_book_data["Book dataset<br/>[app.py]"]
  node_illustrations["Illustration files<br/>[app.py]"]
end

subgraph group_integrations["External sources"]
  node_translator["Google Translator<br/>[app.py]"]
  node_csv_source["Novel CSV source"]
  node_image_source["Image ZIP source"]
end

node_reader(("Reader"))

node_reader -->|"enters query"| node_gradio
node_gradio -->|"submits inputs"| node_submit
node_submit -->|"dispatches query"| node_recommend
node_submit -->|"dispatches blank query"| node_popular
node_recommend -.->|"translates query"| node_translator
node_recommend -->|"filters books"| node_category_filter
node_recommend -->|"encodes query"| node_encoder
node_recommend -->|"ranks matches"| node_similarity
node_recommend -->|"renders results"| node_cards
node_popular -->|"renders defaults"| node_cards
node_csv_source -->|"loads CSV"| node_book_data
node_image_source -->|"downloads archive"| node_illustrations

click node_gradio "https://github.com/juctxy/book-recommendation/blob/main/app.py"
click node_submit "https://github.com/juctxy/book-recommendation/blob/main/app.py"
click node_cards "https://github.com/juctxy/book-recommendation/blob/main/app.py"
click node_book_data "https://github.com/juctxy/book-recommendation/blob/main/app.py"
click node_illustrations "https://github.com/juctxy/book-recommendation/blob/main/app.py"
click node_recommend "https://github.com/juctxy/book-recommendation/blob/main/app.py"
click node_category_filter "https://github.com/juctxy/book-recommendation/blob/main/app.py"
click node_encoder "https://github.com/juctxy/book-recommendation/blob/main/app.py"
click node_similarity "https://github.com/juctxy/book-recommendation/blob/main/app.py"
click node_popular "https://github.com/juctxy/book-recommendation/blob/main/app.py"
click node_translator "https://github.com/juctxy/book-recommendation/blob/main/app.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_gradio,node_submit,node_cards toneBlue
class node_recommend,node_category_filter,node_encoder,node_similarity,node_popular toneAmber
class node_book_data,node_illustrations toneMint
class node_translator,node_csv_source,node_image_source toneRose
class node_reader toneIndigo
```

## Components

### User interface

- [Gradio controls](https://github.com/juctxy/book-recommendation/blob/main/app.py): `app.py`
- [Query events](https://github.com/juctxy/book-recommendation/blob/main/app.py): `app.py`
- [Result cards](https://github.com/juctxy/book-recommendation/blob/main/app.py): `app.py`

### Recommendation

- [Recommendation handler](https://github.com/juctxy/book-recommendation/blob/main/app.py): `app.py`
- [Category filter](https://github.com/juctxy/book-recommendation/blob/main/app.py): `app.py`
- [Query encoder](https://github.com/juctxy/book-recommendation/blob/main/app.py): `app.py`
- [Similarity ranking](https://github.com/juctxy/book-recommendation/blob/main/app.py): `app.py`
- [Popular defaults](https://github.com/juctxy/book-recommendation/blob/main/app.py): `app.py`

### Book content

- [Book dataset](https://github.com/juctxy/book-recommendation/blob/main/app.py): `app.py`
- [Illustration files](https://github.com/juctxy/book-recommendation/blob/main/app.py): `app.py`

### External sources

- [Google Translator](https://github.com/juctxy/book-recommendation/blob/main/app.py): `app.py`
- **Novel CSV source**
- **Image ZIP source**

### Other components

- **Reader**

## Connections

- Reader → Gradio controls: enters query (evidence: `app.py`)
- Gradio controls → Query events: submits inputs (evidence: `app.py`)
- Query events → Recommendation handler: dispatches query (evidence: `app.py`)
- Query events → Popular defaults: dispatches blank query (evidence: `app.py`)
- Recommendation handler → Google Translator: translates query (evidence: `app.py`)
- Recommendation handler → Category filter: filters books (evidence: `app.py`)
- Recommendation handler → Query encoder: encodes query (evidence: `app.py`)
- Recommendation handler → Similarity ranking: ranks matches (evidence: `app.py`)
- Recommendation handler → Result cards: renders results (evidence: `app.py`)
- Popular defaults → Result cards: renders defaults (evidence: `app.py`)
- Novel CSV source → Book dataset: loads CSV (evidence: `app.py`)
- Image ZIP source → Illustration files: downloads archive (evidence: `app.py`)
