# dm4m/fsru architecture

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

- Interactive diagram: https://gitdiagram.com/dm4m/fsru
- Repository: https://github.com/dm4m/fsru

## Overview

1. **Repository purpose**
   - This is a compact PyTorch research implementation of the FSRU model from the AAAI 2024 paper on multimodal rumor detection.
   - The repo is not a service or app; it is an experiment pipeline centered on training and evaluating a multimodal classifier.

2. **Main execution path**
   - `main_kfold.py` is the orchestration entry point.
   - It likely drives k-fold cross-validation, wires together argument parsing, dataset loading, model construction, loss computation, and evaluation.

3. **Configuration boundary**
   - `arguments.py` is the central configuration layer.
   - It likely defines CLI flags and experiment hyperparameters such as dataset choice, batch size, learning rate, fold settings, and model dimensions.
   - This is the main control boundary between the user and the training pipeline.

4. **Data ingestion subsystem**
   - `data_loader.py` and `datasets.py` form the input pipeline.
   - `datasets.py` likely defines dataset objects and sample formatting for multimodal rumor examples.
   - `data_loader.py` likely builds PyTorch `DataLoader` instances, handles batching, shuffling, and train/validation split logic for each fold.

5. **Input data characteristics**
   - The project depends on external datasets: Weibo and Twitter/MediaEval.
   - These datasets are not stored in the repo, so the architecture has a clear external data boundary: raw multimodal samples come from downloaded dataset files and are fed into the local training pipeline.

6. **Model subsystem**
   - `model.py` contains the FSRU network implementation.
   - Based on the paper and repository name, this is the core multimodal fusion architecture, where text/image features are transformed and combined in the frequency spectrum domain.
   - This is the central compute boundary of the system.

7. **Loss / optimization subsystem**
   - `loss.py` encapsulates the objective used during training.
   - It likely provides the classification loss and any auxiliary terms needed by FSRU.
   - This module sits between model outputs and the optimizer loop in the training script.

8. **Training and evaluation flow**
   - The flow is: arguments → dataset/dataloader → model forward pass → loss computation → backpropagation → fold-level evaluation.
   - Because the entry point is `main_kfold.py`, the architecture emphasizes repeated train/validate cycles rather than a single static train/test run.

9. **Experiment structure**
   - The repository is designed for reproducible academic experiments.
   - There is no obvious server, database, or message queue layer; all state is local, with data read from disk and metrics produced by the training run.

10. **Outputs and artifacts**
   - The main outputs are trained model checkpoints, validation/test metrics, and possibly fold-aggregated results.
   - The `fig/` directory is documentation-only and contains the model illustration used in the README, not a runtime dependency.

11. **Important architectural boundaries for a diagram**
   - External datasets on one side.
   - Local experiment runner and configuration in the center.
   - Data loading/formatting feeding the FSRU model and loss modules.
   - Cross-validation and metrics aggregation wrapping the whole training process.

12. **Technology stack**
   - Python + PyTorch is the core runtime stack.
   - The README lists supporting scientific libraries: NumPy, Pandas, SciPy, scikit-learn, and timm, which indicate standard ML preprocessing, metrics, and model utilities.

Main entry points: [`main_kfold.py`](https://github.com/dm4m/fsru/blob/main/main_kfold.py) (K-fold runner), [`model.py`](https://github.com/dm4m/fsru/blob/main/model.py) (FSRU model), [`data_loader.py`](https://github.com/dm4m/fsru/blob/main/data_loader.py) (Data loader), [`datasets.py`](https://github.com/dm4m/fsru/blob/main/datasets.py) (Datasets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external["External data"]
  node_weibo[("Weibo data<br/>external dataset")]
  node_mediaeval[("Twitter data<br/>external dataset")]
end

subgraph group_core["Experiment pipeline"]
  node_entry["K-fold runner<br/>experiment entry<br/>[main_kfold.py]"]
  node_args["CLI config<br/>experiment config<br/>[arguments.py]"]
  node_loader["Data loader<br/>batching pipeline<br/>[data_loader.py]"]
  node_dataset["Datasets<br/>sample formatter<br/>[datasets.py]"]
  node_model{{"FSRU model<br/>multimodal network<br/>[model.py]"}}
  node_loss["Losses<br/>objective module<br/>[loss.py]"]
  node_trainloop(("Train loop<br/>optimization flow<br/>[main_kfold.py]"))
  node_eval(("Evaluation<br/>metrics flow<br/>[main_kfold.py]"))
  node_folds(("Fold split<br/>cross-validation<br/>[main_kfold.py]"))
  node_artifacts[("Checkpoints<br/>run artifacts")]
end

subgraph group_docs["Docs and figures"]
  node_readme["README<br/>documentation<br/>[README.md]"]
  node_figures["Figures<br/>static asset"]
end

node_readme -->|"describes"| node_entry
node_readme -->|"includes"| node_figures
node_args -->|"configures"| node_entry
node_entry -->|"orchestrates"| node_folds
node_folds -->|"builds"| node_loader
node_loader -->|"wraps"| node_dataset
node_dataset -->|"reads"| node_weibo
node_dataset -->|"reads"| node_mediaeval
node_loader -->|"feeds"| node_model
node_entry -->|"constructs"| node_model
node_model -->|"produces"| node_loss
node_loss -->|"guides"| node_trainloop
node_model -->|"updates"| node_trainloop
node_trainloop -->|"yields"| node_eval
node_eval -->|"aggregates"| node_folds
node_trainloop -->|"writes"| node_artifacts
node_eval -->|"writes"| node_artifacts

click node_entry "https://github.com/dm4m/fsru/blob/main/main_kfold.py"
click node_args "https://github.com/dm4m/fsru/blob/main/arguments.py"
click node_loader "https://github.com/dm4m/fsru/blob/main/data_loader.py"
click node_dataset "https://github.com/dm4m/fsru/blob/main/datasets.py"
click node_model "https://github.com/dm4m/fsru/blob/main/model.py"
click node_loss "https://github.com/dm4m/fsru/blob/main/loss.py"
click node_trainloop "https://github.com/dm4m/fsru/blob/main/main_kfold.py"
click node_eval "https://github.com/dm4m/fsru/blob/main/main_kfold.py"
click node_folds "https://github.com/dm4m/fsru/blob/main/main_kfold.py"
click node_readme "https://github.com/dm4m/fsru/blob/main/README.md"
click node_figures "https://github.com/dm4m/fsru/tree/main/fig"

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_weibo,node_mediaeval toneBlue
class node_entry,node_args,node_loader,node_dataset,node_model,node_loss,node_trainloop,node_eval,node_folds,node_artifacts toneAmber
class node_readme,node_figures toneMint
```

## Components

### External data

Downloaded multimodal rumor datasets used at runtime

- **Weibo data**: external dataset · Multimodal rumor dataset loaded from disk, not stored in repo
- **Twitter data**: external dataset · MediaEval/Twitter-style multimodal rumor data loaded from disk

### Experiment pipeline

Local training, evaluation, and model implementation

- [K-fold runner](https://github.com/dm4m/fsru/blob/main/main_kfold.py): experiment entry · Main orchestration script for repeated train/validate cycles · `main_kfold.py`
- [CLI config](https://github.com/dm4m/fsru/blob/main/arguments.py): experiment config · Central argument and hyperparameter definition layer · `arguments.py`
- [Data loader](https://github.com/dm4m/fsru/blob/main/data_loader.py): batching pipeline · Builds PyTorch loaders and fold-aware batch streams · `data_loader.py`
- [Datasets](https://github.com/dm4m/fsru/blob/main/datasets.py): sample formatter · Dataset definitions and multimodal sample construction · `datasets.py`
- [FSRU model](https://github.com/dm4m/fsru/blob/main/model.py): multimodal network · Core FSRU architecture for text-image fusion and classification · `model.py`
- [Losses](https://github.com/dm4m/fsru/blob/main/loss.py): objective module · Training objective and any auxiliary loss terms · `loss.py`
- [Train loop](https://github.com/dm4m/fsru/blob/main/main_kfold.py): optimization flow · Forward pass, backward pass, and parameter updates inside each fold · `main_kfold.py`
- [Evaluation](https://github.com/dm4m/fsru/blob/main/main_kfold.py): metrics flow · Validation and test scoring for each fold · `main_kfold.py`
- [Fold split](https://github.com/dm4m/fsru/blob/main/main_kfold.py): cross-validation · K-fold partitioning and run aggregation across splits · `main_kfold.py`
- **Checkpoints**: run artifacts · Saved model weights and fold-level experiment outputs

### Docs and figures

Repository documentation and illustration assets

- [README](https://github.com/dm4m/fsru/blob/main/README.md): documentation · Project overview, usage notes, and paper context · `README.md`
- [Figures](https://github.com/dm4m/fsru/tree/main/fig): static asset · Model illustration assets used by the documentation · `fig`

## Connections

- README → K-fold runner: describes · Documents the main experiment workflow
- README → Figures: includes · References the illustrative architecture figure
- CLI config → K-fold runner: configures · Provides command-line options and experiment settings
- K-fold runner → Fold split: orchestrates · Runs repeated cross-validation cycles
- Fold split → Data loader: builds · Creates fold-specific data streams
- Data loader → Datasets: wraps · Uses dataset objects to format samples
- Datasets → Weibo data: reads · Loads Weibo samples from external storage
- Datasets → Twitter data: reads · Loads Twitter/MediaEval samples from external storage
- Data loader → FSRU model: feeds · Supplies batched multimodal inputs to the network
- K-fold runner → FSRU model: constructs · Instantiates the FSRU model for each run
- FSRU model → Losses: produces · Model outputs are scored by the training objective
- Losses → Train loop: guides · Loss drives backpropagation and updates
- FSRU model → Train loop: updates · Parameters are optimized during training
- Train loop → Evaluation: yields · Completed training cycle is validated and tested
- Evaluation → Fold split: aggregates · Fold metrics are combined across splits
- Train loop → Checkpoints: writes · Produces checkpoints and experiment outputs
- Evaluation → Checkpoints: writes · Stores fold metrics and summary results
