# mohaaa216/gnn-flowchart-comparator architecture

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

- Interactive diagram: https://gitdiagram.com/mohaaa216/gnn-flowchart-comparator
- Repository: https://github.com/mohaaa216/gnn-flowchart-comparator

## Overview

This is a pedagogical Siamese-GNN flowchart comparator: it generates synthetic flowchart pairs, encodes them, optionally trains and evaluates a similarity model, then aligns node embeddings to visualize differences. The README also documents training-history plots and prediction examples. The demo is the runtime orchestrator; training is opt-in. Relationships below follow the sampled source and README. Other capabilities described as future work are not current subsystems.

Main entry points: [`demo.py`](https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/demo.py) (Demo Entry), [`models/train.py`](https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/models/train.py) (Trainer), [`data/generator.py`](https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/data/generator.py) (Flowchart Generator), [`models/encoder.py`](https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/models/encoder.py) (Siamese Comparator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Synthetic Data"]
  node_flow_generator["Flowchart Generator<br/>[generator.py]"]
  node_pair_generator["Pair Variants<br/>[generator.py]"]
  node_graph_converter["Graph Converter<br/>[dataset.py]"]
  node_family_split["Family Split<br/>[dataset.py]"]
  node_pair_batcher["Pair Batcher<br/>[dataset.py]"]
end

subgraph group_model["Similarity Model"]
  node_siamese_model["Siamese Comparator<br/>[encoder.py]"]
  node_flow_encoder["GINE Encoder<br/>[encoder.py]"]
  node_trainer["Trainer<br/>[train.py]"]
  node_evaluator["Evaluator<br/>[train.py]"]
  node_checkpoint["Model Checkpoint"]
end

subgraph group_analysis["Difference Analysis"]
  node_node_aligner["Node Aligner<br/>[node_diff.py]"]
  node_diff_visualizer["Difference Visualizer<br/>[node_diff.py]"]
end

subgraph group_demo["Demo Orchestration"]
  node_demo_entry["Demo Entry<br/>[demo.py]"]
  node_history_plotter["Training Curves<br/>[visualizations.py]"]
  node_prediction_results["Prediction Results"]
end

node_user(("User"))

node_user -->|"runs"| node_demo_entry
node_demo_entry -->|"generates graphs"| node_flow_generator
node_flow_generator -->|"creates variants"| node_pair_generator
node_demo_entry -->|"encodes pairs"| node_graph_converter
node_graph_converter -->|"validates graphs"| node_flow_generator
node_demo_entry -->|"splits families"| node_family_split
node_demo_entry -->|"trains optionally"| node_trainer
node_trainer -->|"batches pairs"| node_pair_batcher
node_trainer -->|"optimizes"| node_siamese_model
node_siamese_model -->|"encodes both graphs"| node_flow_encoder
node_trainer -->|"saves best model"| node_checkpoint
node_demo_entry -->|"loads model"| node_checkpoint
node_demo_entry -->|"evaluates test set"| node_evaluator
node_evaluator -->|"scores pairs"| node_siamese_model
node_demo_entry -->|"aligns embeddings"| node_node_aligner
node_demo_entry -->|"renders differences"| node_diff_visualizer
node_demo_entry -->|"plots training history"| node_history_plotter
node_demo_entry -->|"writes predictions"| node_prediction_results

click node_demo_entry "https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/demo.py"
click node_flow_generator "https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/data/generator.py"
click node_pair_generator "https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/data/generator.py"
click node_graph_converter "https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/data/dataset.py"
click node_family_split "https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/data/dataset.py"
click node_pair_batcher "https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/data/dataset.py"
click node_siamese_model "https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/models/encoder.py"
click node_flow_encoder "https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/models/encoder.py"
click node_trainer "https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/models/train.py"
click node_evaluator "https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/models/train.py"
click node_node_aligner "https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/explainability/node_diff.py"
click node_diff_visualizer "https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/explainability/node_diff.py"
click node_history_plotter "https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/visualizations.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_flow_generator,node_pair_generator,node_graph_converter,node_family_split,node_pair_batcher,node_user toneBlue
class node_siamese_model,node_flow_encoder,node_trainer,node_evaluator,node_checkpoint toneAmber
class node_node_aligner,node_diff_visualizer toneMint
class node_demo_entry,node_history_plotter,node_prediction_results toneRose
```

## Components

### Synthetic Data

- [Flowchart Generator](https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/data/generator.py): `data/generator.py`
- [Pair Variants](https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/data/generator.py): `data/generator.py`
- [Graph Converter](https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/data/dataset.py): `data/dataset.py`
- [Family Split](https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/data/dataset.py): `data/dataset.py`
- [Pair Batcher](https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/data/dataset.py): `data/dataset.py`

### Similarity Model

- [Siamese Comparator](https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/models/encoder.py): `models/encoder.py`
- [GINE Encoder](https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/models/encoder.py): `models/encoder.py`
- [Trainer](https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/models/train.py): `models/train.py`
- [Evaluator](https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/models/train.py): `models/train.py`
- **Model Checkpoint**

### Difference Analysis

- [Node Aligner](https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/explainability/node_diff.py): `explainability/node_diff.py`
- [Difference Visualizer](https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/explainability/node_diff.py): `explainability/node_diff.py`

### Demo Orchestration

- [Demo Entry](https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/demo.py): `demo.py`
- [Training Curves](https://github.com/mohaaa216/gnn-flowchart-comparator/blob/main/visualizations.py): `visualizations.py`
- **Prediction Results**

### Other components

- **User**

## Connections

- User → Demo Entry: runs (evidence: `README.md`)
- Demo Entry → Flowchart Generator: generates graphs (evidence: `demo.py`)
- Flowchart Generator → Pair Variants: creates variants (evidence: `README.md`)
- Demo Entry → Graph Converter: encodes pairs (evidence: `demo.py`)
- Graph Converter → Flowchart Generator: validates graphs (evidence: `data/dataset.py`)
- Demo Entry → Family Split: splits families (evidence: `demo.py`)
- Demo Entry → Trainer: trains optionally (evidence: `demo.py`)
- Trainer → Pair Batcher: batches pairs (evidence: `models/train.py`)
- Trainer → Siamese Comparator: optimizes (evidence: `models/train.py`)
- Siamese Comparator → GINE Encoder: encodes both graphs (evidence: `models/encoder.py`)
- Trainer → Model Checkpoint: saves best model (evidence: `models/train.py`)
- Demo Entry → Model Checkpoint: loads model (evidence: `demo.py`)
- Demo Entry → Evaluator: evaluates test set (evidence: `demo.py`)
- Evaluator → Siamese Comparator: scores pairs (evidence: `models/train.py`)
- Demo Entry → Node Aligner: aligns embeddings (evidence: `demo.py`)
- Demo Entry → Difference Visualizer: renders differences (evidence: `demo.py`)
- Demo Entry → Training Curves: plots training history (evidence: `demo.py`)
- Demo Entry → Prediction Results: writes predictions (evidence: `demo.py`)
