# bdi-lab/monti architecture

> Architecture diagram of the GitHub repository bdi-lab/monti, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bdi-lab/monti
- Repository: https://github.com/bdi-lab/monti

## Overview

##### Project Type and Purpose
- This project is a research-oriented implementation aimed at exploring adversarial attacks on Graph Neural Networks (GNNs) in fraud detection contexts. It involves experiments on multi-target graph injection attacks against GNN-based fraud detectors.
- The project uses pre-trained models with varying configurations (e.g., GCN, GAGA, GraphSAGE, etc.), and it distinguishes between surrogate models (used for attack optimization) and victim models (the ones being attacked).

##### File Structure
- Main entry point: The file run.py acts as the main script to orchestrate training or inference.
- Models Directory:
- Contains the attack model definition (attack_model.py) that implements the MonTi attack.
- Contains victim_model.py which defines victim models (e.g., GCN and GAGA) and a collection of pre-trained models under the “pretrained_models” subdirectory further organized by types (surrogate and victim) along with their JSON configuration files.
- Modules Directory:
- Contains core functional components such as data_handler.py for data input and preprocessing, experiment_handler.py for managing experiments, result_manager.py for logging and results saving, and schedulers.py for training schedule and early stopping.
- Configurations and Templates:
- template.json and template_single.json act as configuration blueprints for multi-target or single-target experiments.
- Utility Functions:
- The utils directory contains helper files for constants and additional utility functions.

##### Key System Components
a. Input and Data Management:
- Dataset directories (./Datasets) and the data_handler module which load graphs (DGLGraph), data splits, and target assignments.
b. Experiment Orchestration:
- run.py as the controller that triggers experiments using configurations.
- experiment_handler, result_manager, and schedulers working in tandem for the experimental lifecycle.
c. Models and Components:
- The attack model (MonTi) in models/attack_model.py.
- The victim models (e.g., GCN, GAGA) in models/victim_model.py.
- Pre-trained model configurations and checkpoints stored under models/pretrained_models.
d. Configurations:
- JSON configuration files along with template configuration files ensuring reproducibility.

##### Architectural Relationships and Interactions
- The main execution flow starts from run.py, which reads a chosen configuration from either template files or the best_models configurations.
- run.py initializes data via modules/data_handler.py; this component loads datasets and preprocesses the graph data.
- The experiment_handler uses the preprocessed data to set up the training using the attack model (MonTi) while simultaneously referencing surrogate and victim models from the models directory.
- Once the experiment runs, the result_manager logs outputs and checkpoints are saved to the experimental_results folder.
- Schedulers handle early stopping and manage the decaying learning parameters as described in modules/schedulers.py.

##### Important Architectural Patterns or Principles
- Separation of Concern: The codebase clearly separates the data ingestion/preprocessing, experiment management, and model definitions.
- Configurability: Use of JSON configuration files and templates to promote reproducibility.
- Modularity: Divided structure (modules, models, utils) aids in readability and maintainability which is ideal for research code.
- Reusability: Pre-trained model configurations are stored separately allowing exchangeability of surrogate and victim model components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Input & Configuration"
        CT["Configuration Template (template.json)"]:::input
        ST["Configuration Template (template_single.json)"]:::input
        DS["Datasets"]:::input
        BM["Best Models"]:::input
    end

    subgraph "Execution Controller"
        RS["Run Script (run.py)"]:::controller
        DH["Data Handler (modules/data_handler.py)"]:::controller
    end

    subgraph "Experiment Workflow"
        EH["Experiment Handler (modules/experiment_handler.py)"]:::experiment
        RM["Result Manager (modules/result_manager.py)"]:::experiment
        SCH["Schedulers (modules/schedulers.py)"]:::experiment
    end

    subgraph "Models & Configurations"
        AM["Attack Model (models/attack_model.py)"]:::model
        VM["Victim Models (models/victim_model.py)"]:::model
        PM["Pre-trained Models (models/pretrained_models)"]:::model
    end

    subgraph "Utilities"
        UT["Utility Functions (utils/)"]:::utility
    end

    CT -->|"config"| RS
    ST -->|"config"| RS
    BM -->|"model_config"| RS
    DS -->|"data"| DH
    RS -->|"initialize"| DH
    DH -->|"prepare_data"| EH
    EH -->|"invoke_attack"| AM
    EH -->|"invoke_victim"| VM
    EH -->|"load_pretrained"| PM
    EH -->|"log_results"| RM
    EH -->|"control_training"| SCH
    RS -->|"utilizes"| UT

    click RS "https://github.com/bdi-lab/monti/blob/main/run.py"
    click DH "https://github.com/bdi-lab/monti/blob/main/modules/data_handler.py"
    click EH "https://github.com/bdi-lab/monti/blob/main/modules/experiment_handler.py"
    click RM "https://github.com/bdi-lab/monti/blob/main/modules/result_manager.py"
    click SCH "https://github.com/bdi-lab/monti/blob/main/modules/schedulers.py"
    click AM "https://github.com/bdi-lab/monti/blob/main/models/attack_model.py"
    click VM "https://github.com/bdi-lab/monti/blob/main/models/victim_model.py"
    click PM "https://github.com/bdi-lab/monti/tree/main/models/pretrained_models"
    click CT "https://github.com/bdi-lab/monti/blob/main/template.json"
    click ST "https://github.com/bdi-lab/monti/blob/main/template_single.json"
    click UT "https://github.com/bdi-lab/monti/tree/main/utils/"

    classDef input fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef controller fill:#c8e6c9,stroke:#1b5e20,stroke-width:2px;
    classDef experiment fill:#ffe082,stroke:#ff6f00,stroke-width:2px;
    classDef model fill:#ffccbc,stroke:#bf360c,stroke-width:2px;
    classDef utility fill:#d1c4e9,stroke:#4a148c,stroke-width:2px;
```
