# s-m-quadri/toon-suggest architecture

> Architecture diagram of the GitHub repository s-m-quadri/toon-suggest, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/s-m-quadri/toon-suggest
- Repository: https://github.com/s-m-quadri/toon-suggest

## Overview

##### Project type and purpose
- This is a standalone, desktop GUI application (not a web or server-based system).
- Purpose: provide an offline, content-based recommender for animation movies. It trains a TF-IDF model on IMDb `.tsv.gz` files and then lets users query similar titles via a Tkinter GUI.

##### File structure
- Top-level:
- `main.py` – launches the home GUI
- `model.pkl` – persisted TF-IDF model
- `requirements.txt` – Python dependencies
- `setup.spec` – PyInstaller configuration
- `src/` directory:
- `gui_home.py` – main recommendation window (view + controller)
- `gui_train.py` – training window (view + controller)
- `train.py` – data loading, preprocessing, TF-IDF vectorization, and saving model
- `recommend.py` – loading model, computing similarities, returning recommendations
- Build and CI config: `.github/`, `.gitignore`, `LICENSE`

##### README for additional insights
- Confirms two distinct flows: model training vs. model usage (recommendation).
- Built with Python, Tkinter, Pandas, and scikit-learn’s TF-IDF.
- Packaged into a single `.exe` via PyInstaller (`setup.spec`).

##### Essential details
- Both the training and recommendation subsystems as separate but related paths
- PyInstaller packaging step to show how all code and dependencies become a single deployable `.exe`

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User["User"]:::user

    %% UI Layer
    subgraph "UI Layer"
        HomeGUI["Home GUI Window"]:::ui
        TrainGUI["Training GUI Window"]:::ui
    end

    %% Business Logic Layer
    subgraph "Logic Layer"
        RecommendEngine["Recommendation Engine"]:::logic
        TrainEngine["Training Engine"]:::logic
    end

    %% Data Sources
    subgraph "Data Sources"
        IMDbFiles["IMDb Files\n(title.basics.tsv.gz,\ntitle.ratings.tsv.gz)"]:::data
    end

    %% Storage
    subgraph "Model Storage"
        ModelPKL["model.pkl"]:::storage
    end

    %% Deployment
    subgraph "Deployment and Packaging"
        MainPy["main.py"]:::packaging
        Requirements["requirements.txt"]:::packaging
        SetupSpec["setup.spec"]:::packaging
        EXE["Standalone EXE"]:::packaging
    end

    %% Flows
    User -->|"opens"| HomeGUI
    HomeGUI -->|"requests recommendations"| RecommendEngine
    RecommendEngine -->|"loads model"| ModelPKL
    User -->|"clicks Train Model"| HomeGUI -->|"opens"| TrainGUI
    TrainGUI -->|"starts training"| TrainEngine
    TrainEngine -->|"reads data"| IMDbFiles
    TrainEngine -->|"saves model"| ModelPKL

    %% Packaging flow
    MainPy -->|"included in"| SetupSpec
    Requirements -->|"included in"| SetupSpec
    ModelPKL -->|"included in"| SetupSpec
    SetupSpec -->|".exe built"| EXE

    %% Click Events
    click HomeGUI "https://github.com/s-m-quadri/toon-suggest/blob/main/src/gui_home.py"
    click TrainGUI "https://github.com/s-m-quadri/toon-suggest/blob/main/src/gui_train.py"
    click RecommendEngine "https://github.com/s-m-quadri/toon-suggest/blob/main/src/recommend.py"
    click TrainEngine "https://github.com/s-m-quadri/toon-suggest/blob/main/src/train.py"
    click ModelPKL "https://github.com/s-m-quadri/toon-suggest/blob/main/model.pkl"
    click MainPy "https://github.com/s-m-quadri/toon-suggest/blob/main/main.py"
    click SetupSpec "https://github.com/s-m-quadri/toon-suggest/blob/main/setup.spec"
    click Requirements "https://github.com/s-m-quadri/toon-suggest/blob/main/requirements.txt"

    %% Styles
    classDef user fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef ui fill:#add8e6,stroke:#333,stroke-width:1px
    classDef logic fill:#90ee90,stroke:#333,stroke-width:1px
    classDef data fill:#ffffb3,stroke:#333,stroke-width:1px
    classDef storage fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef packaging fill:#dda0dd,stroke:#333,stroke-width:1px
```
