# lijfrank-open/graphsmile architecture

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

- Interactive diagram: https://gitdiagram.com/lijfrank-open/graphsmile
- Repository: https://github.com/lijfrank-open/graphsmile

## Overview

##### Project type and purpose
- This is a research‐oriented machine‐learning pipeline implementing a graph‐based multimodal emotion‐recognition model (“GraphSmile”) from the referenced paper.
- It is not a user‐facing web app or microservices suite but a standalone Python experiment suite: you feed it datasets, it trains a model, and you collect outputs (models, logs, metrics).

##### File structure
Top‐level files and their responsibilities:
- run.py – CLI entrypoint; parses arguments, sets up environment, invokes training/inference.
- dataloader.py – dataset readers (IEMOCAP, MELD, CMU-MOSEI), batching logic.
- utils.py – shared helpers (path management, logging, metric calculators).
- module.py – graph construction & feature‐engineering modules, multimodal fusion logic.
- model.py – PyTorch model definition (neural layers, forward pass).
- trainer.py – training loop, optimization, checkpoint saving, evaluation.
- requirements.txt – external dependencies (PyTorch, numpy, etc).

##### README for additional insights
- Describes datasets, CLI flags (epochs, learning rate, batch size, graph hyperparams).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Storage
    subgraph "Data Storage"
        DS1["IEMOCAP"]:::external
        DS2["MELD"]:::external
        DS3["CMU-MOSEI"]:::external
    end

    %% Pipeline Components
    DL["Data Loader (dataloader.py)"]:::data
    U["Preprocessing & Utilities (utils.py)"]:::process
    GM["Graph & Feature Module (module.py)"]:::process
    MD["Model Definition (model.py)"]:::process
    TR["Trainer Engine (trainer.py)"]:::orchestrator
    CLI["CLI Orchestrator (run.py)"]:::orchestrator

    %% Resources & Outputs
    GPU["GPU/Compute (CUDA Device)"]:::external
    CO["Checkpoints & Logs (Disk)"]:::external
    REQ["requirements.txt"]:::external
    RD["README.md"]:::external

    %% Flow
    DS1 -->|"Raw dialogues"| DL
    DS2 -->|"Raw dialogues"| DL
    DS3 -->|"Raw dialogues"| DL

    DL -->|"Batches (dialogues)"| U
    U -->|"Token IDs & modal features"| GM
    GM -->|"Graph tensors"| MD
    MD -->|"Fused features"| TR

    TR -->|"Save checkpoints & logs"| CO
    TR -->|"Evaluation calls"| U
    TR -->|"Runs on"| GPU

    CLI -->|"Invoke pipeline"| DL
    CLI --> TR
    CLI -->|"Collect metrics"| CO
    CLI -->|"Use compute"| GPU

    %% Dependencies & Docs
    REQ -.-> CLI
    RD -.-> CLI

    %% Click Events
    click DL "https://github.com/lijfrank-open/graphsmile/blob/main/dataloader.py"
    click U "https://github.com/lijfrank-open/graphsmile/blob/main/utils.py"
    click GM "https://github.com/lijfrank-open/graphsmile/blob/main/module.py"
    click MD "https://github.com/lijfrank-open/graphsmile/blob/main/model.py"
    click TR "https://github.com/lijfrank-open/graphsmile/blob/main/trainer.py"
    click CLI "https://github.com/lijfrank-open/graphsmile/blob/main/run.py"
    click REQ "https://github.com/lijfrank-open/graphsmile/blob/main/requirements.txt"
    click RD "https://github.com/lijfrank-open/graphsmile/blob/main/README.md"

    %% Styles
    classDef data fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef process fill:#90EE90,stroke:#333,stroke-width:1px
    classDef orchestrator fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
