# lorenzo9uerra/graphids architecture

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

- Interactive diagram: https://gitdiagram.com/lorenzo9uerra/graphids
- Repository: https://github.com/lorenzo9uerra/graphids

## Overview

GraphIDS trains and evaluates a self-supervised network-intrusion detector: a user supplies dataset and experiment settings, the application prepares graph splits, trains an E-GraphSAGE-plus-Transformer model, then flags flows using reconstruction errors and reports metrics. The map also preserves temporal and shift-aware splitting, checkpointing, and experiment tracking. Source excerpts establish the main calls and model/trainer internals; preprocessing and cache details are supported by README documentation, while unsampled implementation details are not expanded.

Main entry points: [`main.py`](https://github.com/lorenzo9uerra/graphids/blob/main/main.py) (Experiment runner), [`utils/trainers.py`](https://github.com/lorenzo9uerra/graphids/blob/main/utils/trainers.py) (Training loop), [`utils/dataloaders.py`](https://github.com/lorenzo9uerra/graphids/blob/main/utils/dataloaders.py) (NetFlow dataset), [`models/graphids.py`](https://github.com/lorenzo9uerra/graphids/blob/main/models/graphids.py) (GraphIDS model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entry"]
  node_cli["CLI options<br/>[parser.py]"]
  node_runtime["Experiment runner<br/>[main.py]"]
end

subgraph group_data["Data preparation"]
  node_dataset["NetFlow dataset<br/>[dataloaders.py]"]
  node_splits["Temporal splits<br/>[shift_segments.py]"]
  node_graphs[("Graph splits and cache<br/>[dataloaders.py]")]
end

subgraph group_model["Detection model"]
  node_graphids["GraphIDS model<br/>[graphids.py]"]
  node_sage["E-GraphSAGE encoder<br/>[graphids.py]"]
  node_transformer["Transformer autoencoder<br/>[graphids.py]"]
end

subgraph group_run["Training and evaluation"]
  node_trainer["Training loop<br/>[trainers.py]"]
  node_threshold["Validation threshold<br/>[trainers.py]"]
  node_checkpoint[("Model checkpoint<br/>[graphids.py]")]
  node_evaluation["Anomaly evaluation<br/>[trainers.py]"]
end

node_user(("Researcher"))
node_wandb["Weights &amp; Biases"]

node_user -->|"sets options"| node_cli
node_cli -->|"configures"| node_runtime
node_runtime -->|"loads dataset"| node_dataset
node_dataset -->|"resolves segments"| node_splits
node_dataset -->|"prepares and caches"| node_graphs
node_runtime -->|"creates model"| node_graphids
node_graphids -->|"owns encoder"| node_sage
node_graphids -->|"owns autoencoder"| node_transformer
node_runtime -->|"trains model"| node_trainer
node_trainer -->|"encodes batches"| node_sage
node_trainer -->|"reconstructs windows"| node_transformer
node_trainer -->|"selects threshold"| node_threshold
node_trainer -->|"saves best model"| node_checkpoint
node_runtime -->|"loads checkpoint"| node_checkpoint
node_runtime -->|"tests model"| node_evaluation
node_evaluation -->|"scores reconstructions"| node_transformer
node_runtime -->|"initializes and logs"| node_wandb

click node_cli "https://github.com/lorenzo9uerra/graphids/blob/main/utils/parser.py"
click node_runtime "https://github.com/lorenzo9uerra/graphids/blob/main/main.py"
click node_dataset "https://github.com/lorenzo9uerra/graphids/blob/main/utils/dataloaders.py"
click node_splits "https://github.com/lorenzo9uerra/graphids/blob/main/utils/shift_segments.py"
click node_graphs "https://github.com/lorenzo9uerra/graphids/blob/main/utils/dataloaders.py"
click node_graphids "https://github.com/lorenzo9uerra/graphids/blob/main/models/graphids.py"
click node_sage "https://github.com/lorenzo9uerra/graphids/blob/main/models/graphids.py"
click node_transformer "https://github.com/lorenzo9uerra/graphids/blob/main/models/graphids.py"
click node_trainer "https://github.com/lorenzo9uerra/graphids/blob/main/utils/trainers.py"
click node_threshold "https://github.com/lorenzo9uerra/graphids/blob/main/utils/trainers.py"
click node_checkpoint "https://github.com/lorenzo9uerra/graphids/blob/main/models/graphids.py"
click node_evaluation "https://github.com/lorenzo9uerra/graphids/blob/main/utils/trainers.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_cli,node_runtime toneBlue
class node_dataset,node_splits,node_graphs toneAmber
class node_graphids,node_sage,node_transformer toneMint
class node_trainer,node_threshold,node_checkpoint,node_evaluation toneRose
class node_user,node_wandb toneIndigo
```

## Components

### Application entry

- [CLI options](https://github.com/lorenzo9uerra/graphids/blob/main/utils/parser.py): `utils/parser.py`
- [Experiment runner](https://github.com/lorenzo9uerra/graphids/blob/main/main.py): `main.py`

### Data preparation

- [NetFlow dataset](https://github.com/lorenzo9uerra/graphids/blob/main/utils/dataloaders.py): `utils/dataloaders.py`
- [Temporal splits](https://github.com/lorenzo9uerra/graphids/blob/main/utils/shift_segments.py): `utils/shift_segments.py`
- [Graph splits and cache](https://github.com/lorenzo9uerra/graphids/blob/main/utils/dataloaders.py): `utils/dataloaders.py`

### Detection model

- [GraphIDS model](https://github.com/lorenzo9uerra/graphids/blob/main/models/graphids.py): `models/graphids.py`
- [E-GraphSAGE encoder](https://github.com/lorenzo9uerra/graphids/blob/main/models/graphids.py): `models/graphids.py`
- [Transformer autoencoder](https://github.com/lorenzo9uerra/graphids/blob/main/models/graphids.py): `models/graphids.py`

### Training and evaluation

- [Training loop](https://github.com/lorenzo9uerra/graphids/blob/main/utils/trainers.py): `utils/trainers.py`
- [Validation threshold](https://github.com/lorenzo9uerra/graphids/blob/main/utils/trainers.py): `utils/trainers.py`
- [Model checkpoint](https://github.com/lorenzo9uerra/graphids/blob/main/models/graphids.py): `models/graphids.py`
- [Anomaly evaluation](https://github.com/lorenzo9uerra/graphids/blob/main/utils/trainers.py): `utils/trainers.py`

### Other components

- **Researcher**
- **Weights & Biases**

## Connections

- Researcher → CLI options: sets options (evidence: `utils/parser.py`)
- CLI options → Experiment runner: configures (evidence: `main.py`)
- Experiment runner → NetFlow dataset: loads dataset (evidence: `main.py`)
- NetFlow dataset → Temporal splits: resolves segments (evidence: `utils/dataloaders.py`)
- NetFlow dataset → Graph splits and cache: prepares and caches (evidence: `README.md`)
- Experiment runner → GraphIDS model: creates model (evidence: `main.py`)
- GraphIDS model → E-GraphSAGE encoder: owns encoder (evidence: `models/graphids.py`)
- GraphIDS model → Transformer autoencoder: owns autoencoder (evidence: `models/graphids.py`)
- Experiment runner → Training loop: trains model (evidence: `main.py`)
- Training loop → E-GraphSAGE encoder: encodes batches (evidence: `utils/trainers.py`)
- Training loop → Transformer autoencoder: reconstructs windows (evidence: `utils/trainers.py`)
- Training loop → Validation threshold: selects threshold (evidence: `utils/trainers.py`)
- Training loop → Model checkpoint: saves best model (evidence: `utils/trainers.py`)
- Experiment runner → Model checkpoint: loads checkpoint (evidence: `main.py`)
- Experiment runner → Anomaly evaluation: tests model (evidence: `main.py`)
- Anomaly evaluation → Transformer autoencoder: scores reconstructions (evidence: `utils/trainers.py`)
- Experiment runner → Weights & Biases: initializes and logs (evidence: `main.py`)
