# keitabroadwater/gnns_in_action architecture

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

- Interactive diagram: https://gitdiagram.com/keitabroadwater/gnns_in_action
- Repository: https://github.com/keitabroadwater/gnns_in_action

## Overview

##### Project Type and Its Purpose
- This repository serves as the code and data companion for the book “Graph Neural Networks in Action.” It is primarily an educational resource that organizes Jupyter notebooks, datasets, and supplemental files by chapter.
- Each chapter’s folder contains experiments and examples illustrating core concepts of graph neural networks (from basic graph embeddings to advanced topics like spatial-temporal GNNs, graph autoencoders, and even scalability concerns).

##### File Structure
- At the top level, you see common configuration files (.gitignore, .gitattributes, README.md) and a set of directories named by chapter (chapter_2, chapter_3, …, chapter_8). This organization reflects a modular design where each chapter is largely self-contained.
- Within chapters, you find:
- Jupyter notebooks (".ipynb") that give hands-on examples and implementations.
- Data files (e.g., CSVs, zipped datasets, npy files) that are used as inputs for the experiments.
- Secondary directories (like “archived_files” in chapter_2 or “data” in chapter_4) which hold legacy or large files.
- This reveals that the architecture is divided functionally by chapter/topic – each acting as a module covering a specific aspect of GNNs.

##### Insights from the README
- The README outlines the book’s structure across three parts: basic concepts, core GNN models, and advanced topics.
- It provides a sequential roadmap of topics (from graph embeddings in chapter 2, moving through various GNN architectures in chapters 3–5, to dynamic/large-scale graphs in chapters 6–8). This sequential progression can be represented in the system design through clearly labeled sections.
- The resource emphasizes that the repository supports both learning and hands-on experimentation—this must be depicted by showing the interplay between “code modules” (the notebooks) and “data sources” (the supplemental datasets).

a. Main Components to Include:
- A “Repository Hub” node representing the entire codebase.
- A “Data Store” node covering datasets (CSV files, zipped data like YelpChi.zip, JSONs, npy files) that are accessed by multiple chapters.
- “External Resources” for datasets that come from sources outside the repository (for instance, the OGB datasets mentioned in the README).
- “Notebook Execution Environment” (e.g., Jupyter Notebooks) indicating that the experiments and code examples are intended to be executed interactively.

b. Relationships and Interactions:
- Link data flows from the “Data Store” to the appropriate chapter modules where data processing, model training, or experimentation occurs.

c. Architectural Patterns and Design Principles:
- The design is modular and loosely coupled as each chapter is self-contained.
- “layered” educational approach: foundational concepts in early chapters leading to advanced methods, which can be depicted as a progressive flow.
- Separation between code (Jupyter notebooks), configuration/data files (in various subdirectories), and external datasets.

d. Technologies and Frameworks:

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Nodes
    RepositoryHub["Repository Hub"]:::repository
    Chapter2["Chapter 2 – Graph Embeddings"]:::chapter
    Chapter3["Chapter 3 – Subgraph Techniques"]:::chapter
    Chapter4["Chapter 4 – Graph Attention Networks (GAT)"]:::chapter
    Chapter5["Chapter 5 – Graph Autoencoder and Drug Discovery"]:::chapter
    Chapter6["Chapter 6 – Advanced Models (GAT, NRI, dynamic graph processing)"]:::chapter
    Chapter7["Chapter 7 – Graph Coarsening, Sparse/Dense Representations, and Batching"]:::chapter
    Chapter8["Chapter 8 – Scalability and Final Experiments"]:::chapter
    DataStore["Data Store"]:::datastore
    NotebookEnv["Notebook Execution Environment"]:::notebook

    %% Repository Hub to Chapters (modular structure)
    RepositoryHub -->|"contains"| Chapter2
    RepositoryHub -->|"contains"| Chapter3
    RepositoryHub -->|"contains"| Chapter4
    RepositoryHub -->|"contains"| Chapter5
    RepositoryHub -->|"contains"| Chapter6
    RepositoryHub -->|"contains"| Chapter7
    RepositoryHub -->|"contains"| Chapter8

    %% Progressive Learning Flow
    Chapter2 -->|"progressesTo"| Chapter3
    Chapter3 -->|"progressesTo"| Chapter4
    Chapter4 -->|"progressesTo"| Chapter5
    Chapter5 -->|"progressesTo"| Chapter6
    Chapter6 -->|"progressesTo"| Chapter7
    Chapter7 -->|"progressesTo"| Chapter8

    %% Data flows from Data Store to chapters with data dependencies
    DataStore ---|"feeds"| Chapter2
    DataStore ---|"feeds"| Chapter4
    DataStore ---|"feeds"| Chapter6
    DataStore ---|"feeds"| Chapter8

    %% Notebook Execution Environment for interactive notebooks in each chapter
    Chapter2 ---|"executesIn"| NotebookEnv
    Chapter3 ---|"executesIn"| NotebookEnv
    Chapter4 ---|"executesIn"| NotebookEnv
    Chapter5 ---|"executesIn"| NotebookEnv
    Chapter6 ---|"executesIn"| NotebookEnv
    Chapter7 ---|"executesIn"| NotebookEnv
    Chapter8 ---|"executesIn"| NotebookEnv

    %% Styles
    classDef repository fill:#b3cde0,stroke:#333,stroke-width:2px;
    classDef chapter fill:#ccebc5,stroke:#333,stroke-width:2px;
    classDef datastore fill:#fbb4ae,stroke:#333,stroke-width:2px;
    classDef notebook fill:#decbe4,stroke:#333,stroke-width:2px;

    %% Click Events
    click RepositoryHub "https://github.com/keitabroadwater/gnns_in_action/tree/master/Root directory"
    click Chapter2 "https://github.com/keitabroadwater/gnns_in_action/tree/master/chapter_2/"
    click Chapter3 "https://github.com/keitabroadwater/gnns_in_action/tree/master/chapter_3/"
    click Chapter4 "https://github.com/keitabroadwater/gnns_in_action/tree/master/chapter_4/"
    click Chapter5 "https://github.com/keitabroadwater/gnns_in_action/tree/master/chapter_5/"
    click Chapter6 "https://github.com/keitabroadwater/gnns_in_action/tree/master/chapter_6/"
    click Chapter7 "https://github.com/keitabroadwater/gnns_in_action/tree/master/chapter_7/"
    click Chapter8 "https://github.com/keitabroadwater/gnns_in_action/tree/master/chapter_8/"
```
